Wartung der Empfängerfelder

Wie auch beim Empfängerimport, erfolgt dieser Web-Service Aufruf über die URL bzw. die Klasse ServiceAgent. Dieser ServiceAgent bietet verschiedene Methoden an, um das Auslesen der Empfängerfelder oder auch, wie hier angeführt, das Hinzufügen oder Aktualisieren der Empfängerfelder zu ermöglichen.

Zum Abrufen der Empfängerfelder wird die Methode GetSubscriberFields verwendet. Dieses Dokument erläutert die Methode UpdateSubscriberFields, welche für die Aktualisierung, also das Hinzufügen und das Bearbeiten von Empfängerfeldern ermöglicht. Wie alle Web-Service Methoden der eworx Marketing Suite, basiert auch diese Methode auf Request- und Response-Message, wobei die Request-Message alle für die Verarbeitung relevanten Daten beinhaltet. Die Response-Message beinhaltet alle Daten, die entsprechend zurückgegeben werden und die dazu nötigen Informationen wie z.B. die vergebenen IDs, wurde ein Feld hinzugefügt oder aktualisiert und dergleichen.

Request Objekt

Dieses Objekt beinhaltet alle Werte, die von der eworx Marketing Suite verarbeitet werden sollen, also die Authentifizierungsdaten, oder auch konkreten Empfängerfelder-Daten, sowie Verhaltensangaben. Die Verhaltensangaben bestimmen, wie sich die eworx Marketing Suite verhalten soll, wenn Felder bereits vorhanden sind, oder eben nicht vorhanden sind.
Auch diese Request-Klasse leitete von SecureRequestMessage ab, welche die Authentifizierungsinformationen beinhaltet. Hierzu sei auf die Beschreibung des Empfängerimport-Dokumentes verwiesen, welches sowohl die Verwendung, als auch die einzelnen Parameter genau spezifiziert.

UpdateSubscriberFieldsRequest beinhaltet somit ein Array mit den entsprechenden Empfängerfeldern, welcher hinzugefügt/aktualisiert werden sollen. Field ist eine abstrakte Klasse, welche entsprechende Ableitungen für verschiedene Feldtypen besitzt. Eine konkrete Ausprägung, auf die detailierter eingegangen wird ist SelectionField. Hierzu später mehr.

Die Eigenschaft CreateMissingFields weißt der eworx Marketing Suite an, dass Felder, die bisher nicht in der Marketing Suite vorhanden sind erzeugt werden. Die Identifikation erfolgt hier primär über den InternalName, welcher durch die Methode GetSubscriberFields in Erfahrung gebracht werden kann bzw. wird auch versucht über die entsprechende Bezeichnung (DisplayName) eine Übereinstimmung zu finden. Kann hier keine Übereinstimmung gefunden werden und die Eigenschaft CreateMissingFields ist auf FALSE gesetzt, so wird eine DoesNotExistException geworfen, sofern ein Feld nicht gefunden werden kann.

Die Eigenschaft DeleteMissingSelectionValues ermöglicht es, dass bei Auswahlen in der eworx Marketing Suite (Ein- oder Mehrfachauswahlen), die zwar in der Marketing Suite, jedoch nicht in der Request-Message vorhanden sind, von der eworx Marketing Suite entfernt werden. Ist diese Eigenschaft nicht gesetzt, so bleiben alle vorhandenen Auswahlmöglichkeiten in der eworx Marketing Suite vorhanden.

Unterstütze Feldtypen

Folgende Feldtypen werden bei der Erstellung unterstütz:

BooleanField (Ja/Nein)
DateTimeField
NumberField
WholeNumberField
RealNumberField
SelectionField
MultiSelectionField (Mehrfachauswahl)
TextField
LongTextField (Notiz)
MdbField (Mediendatenbank)
UrlField

Behandlung von Auswahlfelder

Ein Auswahlfeld (SelectionField) leitet von Field ab und kann somit der Request-Message übergeben werden.

Im Gegensatz zur Methode GetSubscriberFields unterstützt die Methode UpdateSubscriberFields zwei Möglichkeiten um die Selection Fields zu identifizieren bzw. zu verwalten.
Die Eigenschaft Selections bietet ein String-Array mit den verschiedenen Auswahlmöglichkeiten. Im Falle einer Mehrsprachigkeit oder wenn der Interne Name als Identifizierung für die Umbenennung von Feldern benötigt wird, ist es jedoch erforderlich SelectionObjects zu verwenden. Die Methode GetSubscriberFields unterstützt dies nicht und liefert hier lediglich einen Null-Wert.

Für den Fall das die Eigenschaft SelectionObjects gesetzt ist, wird die Eigenschaft Selections ignoriert.

SelectionObjects ist ein Array aus SelectionFieldElement, welche nun die Bezeichnung einer Auswahl, den internen Namen (InternalName) und die Sprache für diese Bezeichnung des Feldes besitzt.

Die Identifikation der Auswahl ist gleich wie bei den Feldern, also der InternalName bzw. die Caption in der entsprechenden Sprache.

Ist der InternalName nicht gesetzt, so wird ein Interner Name durch die Caption berechnet.

Ist die Language-Eigenschaft NULL, so wird die Sprache vom Request-Objekt verwendet. Die Language ist hier notwendig, wenn ein Feld in verschiedenen Sprachen aktualisiert werden soll. Dann kann das SelectionFieldElement mehrmals vorkommen und zwar mit verschiedenen Caption-Werten und verschiedenen Language-Werten. Der InternalName muss zur Identifikation gleich sein!

Zur Erstellung eines Mehrfachauswahlfeldes kann anstatt der Klasse SelectionField die Klasse MultiSelectionField verwendet werden.

Beispiel Request „Wartung Empfängerfelder“

Ein C# Codebeispiel zur Veranschaulichung der Verwendung.

Variante 1: Verwendung der Eigenschaft Selections

UpdateSubscriberFieldsRequest request = new UpdateSubscriberFieldsRequest();
request.Language = "DE";
request.SecurityContext = GetSecurityContext();
request.CreateMissingFields = true;
request.DeleteMissingSelectionValues = true;

List<Field> fieldsToUpdate = new List<Field>();

TextField fld1 = new TextField();
fld1.DisplayName = "MyFirstTextField";
fld1.UntypedValue = "This is the default value of the field";

SelectionField fld2 = new SelectionField();
fld2.DisplayName = "MyWebService Automarke deutsch";
fld2.InternalName = "mywebserviceautomarke";
fld2.Selections = new String[] { "Audi", "Mazda", "BMW", "Skoda", "Merzedes", "Sonstige" };

fieldsToUpdate.Add(fld1);
fieldsToUpdate.Add(fld2);

request.Fields = fieldsToUpdate.ToArray();

UpdateSubscriberFieldsResponse response = agent.UpdateSubscriberFields(request);
…

Hier werden zwei Felder an den Webservice geschickt: 1) Ein Textfeld mit der Bezeichnung „MyFirstTextField“. Der interne Name wird automatisch berechnet. Sollte dieser gesetzt werden, so ist empfohlen, diesen aus GetSubscriberFields() erst auszulesen.
Des weiteren wird eine Auswahl mit dem Internen Namen „mywebserviceautomarke“ gesendet. Die Auswahlmöglichkeiten werden in der Sprache Deutsch angelegt, da die Request Nachricht als Deutsch spezifiziert wurde.

Variante 2: Verwendung der Eigenschaft SelectionObjects

UpdateSubscriberFieldsRequest request = new UpdateSubscriberFieldsRequest();
request.Language = "DE";
request.SecurityContext = GetSecurityContext();
request.CreateMissingFields = true;
request.DeleteMissingSelectionValues = true;

List<Field> fieldsToUpdate = new List<Field>();

TextField fld1 = new TextField();
fld1.DisplayName = "MyFirstTextField";
fld1.UntypedValue = "This is the default value of the field";
fld1.InternalName = "myfirsttextfield";

SelectionField fld2 = new SelectionField(); 
fld2.DisplayName = "MyWebService Automarke deutsch"; 
fld2.InternalName = "mywebserviceautomarke"; 
List<SelectionFieldElement> elems = new List<SelectionFieldElement>(); 
elems.Add(GetNewSelectionFieldElement("Audi", "audi", request.Language)); 
elems.Add(GetNewSelectionFieldElement("Mazda", null, null)); 
elems.Add(GetNewSelectionFieldElement("BMW", "bmw", null)); 
elems.Add(GetNewSelectionFieldElement("Merzedes", null, request.Language)); 
elems.Add(GetNewSelectionFieldElement("Sonstige", "sonstige", "DE")); 
elems.Add(GetNewSelectionFieldElement("Other", "sonstige", "EN"));
fld2.SelectionObjects = elems.ToArray();

fieldsToUpdate.Add(fld1);
fieldsToUpdate.Add(fld2);

request.Fields = fieldsToUpdate.ToArray();

UpdateSubscriberFieldsResponse response = agent.UpdateSubscriberFields(request);


private static SelectionFieldElement GetNewSelectionFieldElement(string caption, string internalName, string language) { 
	SelectionFieldElement elem = new SelectionFieldElement(); 
	elem.Caption = caption; 
	elem.InternalName = internalName; 
	elem.Language = language; 
	return elem; 
}

Diese Variante verwendet die Option mit SelectionObjects, welche eine weitere Spezifikation von Auswahlen ermöglicht. Hier können für jedes Element optional die Bezeichnung, der Interne Name und die Sprache gesetzt werden. Durch die zwei Zeilen
elems.Add(GetNewSelectionFieldElement("Sonstige", "sonstige", "DE"));
elems.Add(GetNewSelectionFieldElement("Other", "sonstige", "EN"));
ist ersichtlich, dass es bei dieser Option auch möglich ist, eine Auswahl in verschiedene Sprachen anzulegen bzw. zu aktualisieren.

Response Objekt

Als Rückgabewert des Web-Service Aufruf wird eine Instanz der UpdateSubscriberFieldsResponse Klasse zurückgegeben. Diese Klasse beinhaltet ein Array von Einträgen (UpdateSubscriberFieldResponseEntry), welche entsprechende Auskunft über die getätigte Aktion liefert.

Ist die Eigenschaft Created auf TRUE gesetzt, so wurde das Feld erzeugt. Die vergebene GUID des Feldes und der vergebene interne Name werden ebenfalls zurückgegeben.
Ist die Eigenschaft Created auf FALSE gesetzt, so wurde das Feld aktualisiert.
Tritt ein Fehler auf, so wird eine entsprechende Exception geworfen, und somit kommt es zu keinem Response beim Aufruf des Web-Service.