Verarbeitung von E-Mails mit JSON-Inhalt

Verarbeitung von E-Mails mit JSON-Inhalt#

Motivation#

Manche Unternehmen bieten ihren Kunden ein Kontaktformular an, über das sie schon vorab strukturiert Daten abfragen. Viele Organisationen wollen ihr Allegra-System aus Sicherheitsgründen nicht direkt zugänglich machen und verschicken die Formulardaten per E-Mail.

Allegra ist in der Lage, strukturierte Daten aus einer E-Mail zu extrahieren, wenn diese in einem bestimmten Format darin enthalten sind.

E-Mail JSON-Format#

Die vom Kontaktformular zusammengestellte E-Mail sollte die Daten im folgenden JSON-Format bereitstellen:

{
"item": {
    "<itemAttributeNameOrLabel1>":"<attributeValue1>",
    "<itemAttributeNameOrLabel2>":"<attributeValue2>",
    "...": "..."
},
"person": {
    "firstName":"<firstName>",
    "lastName":"<lastName>",
    "userEmail":"<e-mail>",
    "userName":"<loginname>",
    "disableEmailNotification":"<booleanTrueOrFalse>",
    "department":"<departmentLabel>",
    "company": "<company>",
    "locale":"<localeStr>",
    "phone":"<phone>",
    "address1":"<address1>",
    "address2":"<address2>",
    "city":"<city>",
    "zipcode":"<code>",
    "country":"<countrylabel>",
    "countryISOCode":"<two-lettercountryISOCode>"
},
"token":"<theTokenFromSettings>"
}

Das JSON kann drei Hauptbestandteile enthalten:

  • item: enthält die Attribute des Elements. Die Schlüssel sind entweder attributierte Namen oder Bezeichnungen, wie in der Konfiguration Anpassen -> Vorgangsattribute definiert.

    Die Werte sind immer die sichtbaren Werte der Felder, d. h. für Attribute vom Typ Liste muss die Bezeichnung und nicht die ID angegeben werden.

  • person: enthält die personenbezogenen Attribute. Die Bezeichnungen dieser Attribute sind fest vorgegeben und können nicht über die Allegra-Benutzeroberfläche geändert werden.

    Die meisten Personenattribute sind optional, aber entweder firstName und lastName oder userName sind erforderlich.

    Jeder Attributwert sollte ein String sein. Das gilt auch für alle listenbasierten Attributen wie z.B. der Abteilungsbezeichnung. Eine Ausnahme stellt, disableEmailNotification dar, das auch ein boolescher Wert sein kann (true oder false).

    Das Attribut locale, falls vorhanden, sollte entweder browser oder ein gültiger Java-Locale-String wie de oder de_DE sein.

    Die Attribute country und countryISOCode schließen sich gegenseitig aus; es sollte nur jeweils eines von beiden verwendet werden. countryISOCode` sollte, falls vorhanden, der offizielle zweistellige ISO-Code eines Landes sein.

  • token: ein String-Wert. Erläuterung weiter unten unter item.emailReceived.isJSON.tokenValue

Konfigurieren der JSON-Verarbeitung#

Die folgenden Werte können unter Serverkonfiguration -> Sonstige -> „Erweiterte Einstellungen bearbeiten“ eingestellt werden, um die JSON-E-Mail-Verarbeitung anzupassen.

JSON-E-Mail-Konfiguration#

Attribut-Schlüssel

Bemerkung

item.emailReceived.isJSON.subjectKeyword

Das Schlüsselwort, das im E-Mail-Betreff enthalten sein muss, um als JSON-Inhalt verarbeitet zu werden

item.emailReceived.isJSON.fromAddress

Die Absenderadresse der E-Mail, die als JSON-Inhalt verarbeitet werden soll

item.emailReceived.isJSON.addNotOnFormAttributes

Ob auch die aus dem JSON identifizierten Attribute hinzugefügt werden sollen, die nicht im Formular für den neuen Eintrag vorhanden sind; Standardeinstellung ist false (vernachlässige Attribute nicht im Formular)

item.emailReceived.isJSON.addNotOnFormAttributes

Ob auch die aus dem JSON identifizierten Attribute hinzugefügt werden sollen

item.emailReceived.isJSON.tokenValue

Wenn ein solcher Eintrag in der Konfiguration vorhanden ist, sollte das übermittelte JSON einen Token mit diesem <tokenvalue> enthalten, andernfalls wird die E-Mail als Spam behandelt und verworfen. Dies ist eine Sicherheitsmaßnahme, um zu vermeiden, dass neue Elemente von anderen Orten als dem CMS des Kunden erstellt werden. Wenn kein solcher Eintrag in der Konfiguration angegeben ist, sollte das Token nicht im JSON angegeben werden.

Personen werden durch ihre E-Mail-Adressen identifiziert. Wenn eine Person nicht per E-Mail gefunden werden kann und die Registrierung neuer Benutzer erlaubt ist, wird ein neuer Benutzer registriert. Diese Person wird als Ersteller des neu erstellten Eintrags festgelegt.

Hinweise für Entwickler#

Der folgende Code wird von der Standard-E-Mail-Empfangsverarbeitung aufgerufen:

JSONParserService jsonParserService = SpringApplicationContext.getBean(
                                                     DefaultJSONParserService.class);

jsonParserService.applyJSONContent(inputBinding, emailRejector, true);

Der Wert „true“ für validateJSONEmailCondition stellt sicher, dass die Funktion nur aufgerufen wird, wenn entweder ein Betreff-Schlüsselwort (item.emailReceived.isJSON.subjectKeyword) oder eine Absenderadresse (item.emailReceived.isJSON.fromAddress) übereinstimmt.

Wenn keine der JSON-Vorlagen übereinstimmt, kann der obige Code alternativ von Skripten für Workflow-Aktivitäten aufgerufen werden, wobei validateJSONEmailCondition auf „false“ gesetzt wird, wenn nach der Verarbeitung des JSON-Inhalts noch weitere Nachbearbeitungen für das Element vor dem Speichern erforderlich sind.

Inhalt