Abonnenten importieren – ImportSubscribers

Request-Klasse: SubscriberImportRequest
Response-Klasse: SubscriberImportResponse

Der allgemeine Aufruf des Webservice erfolgt über die Importer Klasse. Diese Importerklasse hat als Übergabeparameter einen ImportRequest, welcher alle Informationen beinhaltet, welche für den Import notwendig sind und gibt als Rückgabewert einen ImportResponse, welcher eventuelle Fehlermeldungen, statistische Daten und dergleichen beinhaltet.

Aufruf des Importers für den Abonnentenimport

Für den Import wird der Importer instanziert. Dieser bekommt als Übergabeparameter einen SubscriberImportRequest. Jeder Schnittstellenaufruf an das System erfordert einen SecurityContext, welcher in diesem SubscriberImportRequest eingebettet ist.
Dieser SecurityContext beinhaltet die Login-Daten; - also welcher User sich für welchen Mandanten anmeldet und auch über welche Schnittstelle (identifiziert durch die Eigenschaft Source.) Der Wert der Source Eigenschaft wird von eworx Network & Internet GmbH für die jeweilige Anbindung vergeben und ist von dort anzufordern.
Weiters beinhaltet der SubscriberImportRequest das Duplikatskriterium, welches das Abonnentenfeld identifiziert, dass eindeutig sein muss (z.B.: CRMID, Email, ...). Dieses Feld muss natürlich in mailworx entsprechend konfiguriert sein! Als Duplikatskerterium muss der InternalName des Feldes angegeben werden. Der SubscriberImportRequest enhält auch die Sprache, die für die Abonnenten verwendet wird. Es muss entweder die Sprache im Request oder die Sprache jedes einzelnen Abonnenten gesetzt sein.

Die eigentlichen Abonnentendaten welche importiert werden sollen, befinden sich in der Liste von Subscribers. Weitere Informationen, wie ein Abonnent tatsächlich aufgebaut ist, später.

Der SubscriberImportRequest spezifiziert zu guter letzt noch eine Liste von AfterImportActions, welche Aktionen definiert, die nach erfolgreichem Import aufgerufen werden sollen. Weitere Informationen dazu später.

 

Als Ergebnis des Funktionsaufrufs Importer.ImportSubscriber wird ein SubscriberImportResponse geliefert, welcher die Anzahl der gefundenen Duplikate, Anzahl der Fehler beim Import, Anzahl der importierten (neu hinzugefügten) Abonnenten und der aktualisierten Abonnenten beinhaltet. Weiters beinhaltet diese Klasse ein Array, welche eine Instanz eines SubscriberResponseEntry beinhalten.

Der SubscriberResponseEntry gibt folgendes an:

  • Action: Welche Aktion wurde für diesen Abonnenten getätigt?
  • AffectedSubscriber: Die ID des Abonnenten, welcher durch den Import betroffen war.
  • Error: Gegebenfalls eine Fehlermeldung, welche beim Import geworfen wurde.
  • UniqueId: Das verwendete Duplikatskriterium des Abonnenten.

Weiters bietet der Importer eine Methode ValidateRequest, welche Benutzer-, Passwort-, Account-, Schnittstellenangaben prüft.

 

Abbildung der Abonnentendaten

Ein Abonnent besitzt prinzipiell folgende Optionen:

  • Optin: Bekommt der Abonnent E-Mails oder hat er den Newsletter abbestellt. Default Value TRUE
  • Language: Die Sprache des Abonnenten. Hier wird die ISO Darstellung der Länderkürzel verwendet. Z.B.: DE für Deutsch, EN für Englisch, ...
  • Mailformat: Enumeration mit dem E-Mail-Format, welches der Abonnent bekommt.
  • Status: Wie lautet der Status des Abonnenten bzgl. E-Mail (Aktiv | Inaktiv)
  • SmsStatus: Wie lautet der Status des Abonnenten bzgl. SMS (Aktiv | Inaktiv)
  • Registrationdate: Das Registierungsdatum des Abonnenten im System.
  • IPAddress: Die IPAddresse des Empfängers, die dieser bei der Registrierung zum Newsletter hatte. Wurde der Abonnent manuell eingetragen oder importiert, so wird die IP-Adresse nicht gesetzt.
  • OptOutDate: Das Datum der Abmeldung des Abonnenten, falls sich dieser selbst abgemeldet hat.
  • Fields: Ein Array mit den Abonnentenfeldern. Diese Eigenschaft beinhaltet alle Abonnentenwerte die importiert werden sollen. Ist ein Wert nicht vorhanden, so werden die Original-Werte des Abonnenten beibehalten bzw. die Standardwerte des Systems automatisch gesetzt, falls ein Abonnent neu hinzugefügt wurde.

All diese Standardfelder (Mailformat, Optin, RegistrationDate, Status) sind null-able. Bei Abonnenten, die bereits im System vorhanden sind, können diese Werte mit null besetzt werden und es bleiben die Standard-Werte im System vorhanden. Bei neuen Abonennten, die noch nicht im System vorhanden sind, sollen diese Werte gesetzt werden! Ist dies nicht der Fall, werden Standardwerte vom System vergeben.

Die Abonnentenwerte werden mit den konkreten Klassen gefüllt. Wobei jede dieser Klassen mindestens einen Namen besitzt und meist auch einen Wert. Der Name des Feldes in der Klasse wird beim Import auf ein intern konfiguriertes Feld in mailworx gemappt. Kann dies nicht erfolgen, so wird eine Exception geworfen. Gleiches gilt, wenn Werte nicht gültig gesetzt wurden.
Ist in mailworx zum Beispiel ein Feld „Geburtsdatum“ für die Abonnenten konfiguriert, so wird dieses Feld importiert, indem man ein SubscriberDateTimeField instanziert mit dem Namen „Geburtsdatum“ und dem entsprechenden Wert.
Als Feld-Mapping-Name werden die in mailworx konfigurierten Felder in der entsprechenden Sprache (wie auch beim Abonnenten konfiguriert) verwendet.

Der Ablauf beim Import

Der Import läuft wie im folgenden Flussdiagramm dargestelltem Schema ab:
Beim Import werden weiters noch ein Array von diversen Aktionen mitgegeben. Um die Bedeutung dieser Aktionen (engl. Actions) besser verstehen zu können, wird kurz auf den Ablauf des Imports eingegangen.

Wie im Flowchart links ersichtlich, gibt es Aktionen, die jeweils nur einmal pro Import ausgeführt werden (grün) und Aktionen, welche für jeden Abonnenten ausgeführt werden (blau). Hierbei existieren jeweils Aktion, die vor- bzw. nach der entsprechenden Ausführung angezeigt werden.

Für die BeforeImportAction, PreSubscriberAction, PostSubscriberAction und AfterImportAction existiert jeweils eine Eigenschaft mit einem Array derartiger Objekte in der ImportRequestKlasse.

Im Folgenden wird eine Auswahl angeführt mit den vorhandenen Aktionen für die Schnittstelle. Diese Aktionen werden bei Bedarf von eworx Network & Internet GmbH erweitert.

Im Moment existieren für die Schnittstelle folgende Ausprägungen von BeforeImportAction: RemoveDuplicatesAction. Hier werden die importierten Daten nach einem Duplikatskriterium durchsucht und sollten mehrere Datensätze mit dem gleichen Wert in diesem Kriterium vorhanden sein, so werden die Duplikate entfernt.

Im Moment existieren für die Schnittstelle folgende Ausprägungen von AfterImportAction.
SendNotificationAction. Hier wird nach Abschluss des Imports eine E-Mail an eine angegebene E-Mail-Adresse gesendet.
Im Moment existieren für die Schnittstelle folgende Ausprägungen von PreSubscriberAction. Hier sind im Moment keine Aktionen vorhanden.

Einflussnahme vor dem Import

BeforeImportActions werden ausgeführt, bevor einzelne Abonnenten importiert werden. Es existieren zwei mögliche Aktionen:
ClearProfileAction:
Hier werden alle Abonnenten von einer bestimmten statischen Abonnentengruppe mit dem entsprechenden Namen entfernt. Die Abonnenten werden nicht gelöscht! Sie werden lediglich aus der Abonnentengruppe entfernt und somit beinhaltet die Abonnentengruppe keine Abonnenten mehr. Dies kann erforderlich sein, wenn anschließend die importierten/aktualisierten Abonnenten wieder in die Abonnentengruppe gespeichert werden sollen und am Ende des Imports sichergestellt werden soll, dass lediglich importierte/aktualisierte Abonnenten dieser Abonnentengruppe zugeordnet sein sollen.
RemoveDuplicatesAction:
Entfernt alle Abonnenten, die doppelt in der Import Liste vorhanden sind. Hier ist die Angabe des entsprechenden Duplikat-Feldes notwendig, sowie ob es sich bei diesem Feld um ein Meta-Feld (ID, Registrierungsdatum,…) handelt. Es wird empfohlen, die Duplikatsfreiheit bereits im Vorfeld sicherzustellen!

Was passiert nach dem Import?

Der Importer enthält eine Liste von AfterImportActions. Diese Aktionen können in der ersten Phase wie folgt sein:

SendNotificationAction:
Sendet eine E-Mail an eine konfigurierte Adresse, nachdem der Import abgeschlossen ist.

Was passiert nachdem ein Abonnent importiert/aktualisiert wurde?

mailworx definiert Aktionen, welche für jeden Abonnenten ausgeführt werden als PostSubscriberActions. Diese werden ausgeführt, nachdem ein Abonnent in mailworx importiert oder aktualisiert wurde.

SendCampaignAction:
Sendet allen Abonnenten die neu hinzugefügt wurden (falls ExecuteWith mit Insert gesetzt ist) und allen die aktualisiert wurden (falls AddUpdate gesetzt ist) eine E-Mail Kampagne mit einer entsprechenden Guid. Dabei müssen die Felder für Vorname, Nachname und E-Mail beim Import angegeben werden.

ProfileAdderAction:
Fügt alle Abonnenten die neu hinzugefügt wurden (falls ExecuteWith mit Insert gesetzt ist) und alle die aktualisiert wurden (falls ExecuteWith mit Update gesetzt ist) in eine statische Abonnentengruppe mit einem entsprechenden Namen hinzu. Falls diese Abonnentengruppe bereits existiert, werden die Abonnenten der existierenden Abonnentengruppe hinzugefügt. Ansonsten wird die Abonnentengruppe neu erstellt und die Abonnenten angefügt. Wird eine Guid angegeben, so wird versucht die Abonnentengruppe mit dieser Guid zu verwenden, existiert dieses nicht wird der Name verwendet.
Hinweis: Der Name der Abonnentengruppe ist auf 50 Zeichen beschränkt!

SendSMSCampaignAction:
Sendet allen Abonnenten die neu hinzugefügt wurden (falls ExecuteWith mit Insert gesetzt ist) und allen die aktualisiert wurden (falls ExecuteWith mit Update gesetzt ist) eine SMS Kampagne mit einer entsprechenden Guid. Dabei muss das Feld Telefonnummer beim Import angegeben werden. Wird die Telefonnummer nicht angegeben, so wird der Abonnenten importiert, aber keine SMS versendet.