Processing emails with JSON content

Processing emails with JSON content#

Motivation#

Some companies offer their customers a contact form through which they collect structured data in advance. For security reasons, many organizations do not want to make their Allegra system directly accessible and send the form data by email.

Allegra is able to extract structured data from an email when that data is contained in it in a specific format.

Email JSON format#

The email assembled by the contact form should provide the data in the following JSON format:

{
"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>"
}

The JSON can contain three main parts:

  • item: contains the attributes of the item. The keys are either attribute names or labels, as defined in the configuration under Customize -> Item attributes.

    The values are always the visible values of the fields, that is, for attributes of the List type the label and not the ID must be specified.

  • person: contains the person-related attributes. The labels of these attributes are fixed and cannot be changed through the Allegra user interface.

    Most person attributes are optional, but either firstName and lastName or userName are required.

    Each attribute value should be a string. This also applies to all list-based attributes such as the department label. One exception is disableEmailNotification, which can also be a boolean value (true or false).

    The locale attribute, if present, should be either browser or a valid Java locale string such as de or de_DE.

    The country and countryISOCode attributes are mutually exclusive; only one of the two should be used. countryISOCode` should, if present, be the official two-letter ISO code of a country.

  • token: a string value. See the explanation further below under item.emailReceived.isJSON.tokenValue

Configuring JSON processing#

The following values can be set under Server configuration -> Other -> “Edit advanced settings” to adjust the JSON email processing.

JSON email configuration#

Attribute key

Remark

item.emailReceived.isJSON.subjectKeyword

The keyword that must be contained in the email subject for it to be processed as JSON content

item.emailReceived.isJSON.fromAddress

The sender address of the email that is to be processed as JSON content

item.emailReceived.isJSON.addNotOnFormAttributes

Whether the attributes identified from the JSON that are not present in the form for the new entry should also be added; the default setting is false (do not neglect attributes not in the form)

item.emailReceived.isJSON.addNotOnFormAttributes

Whether the attributes identified from the JSON should also be added

item.emailReceived.isJSON.tokenValue

If such an entry is present in the configuration, the submitted JSON should contain a token with this <tokenvalue>; otherwise the email is treated as spam and discarded. This is a security measure to prevent new items from being created from places other than the customer’s CMS. If no such entry is specified in the configuration, the token should not be specified in the JSON.

People are identified by their email addresses. If a person cannot be found by email and the registration of new users is allowed, a new user is registered. This person is set as the creator of the newly created entry.

Notes for developers#

The following code is called by the standard incoming email processing:

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

jsonParserService.applyJSONContent(inputBinding, emailRejector, true);

The value “true” for validateJSONEmailCondition ensures that the function is only called when either a subject keyword (item.emailReceived.isJSON.subjectKeyword) or a sender address (item.emailReceived.isJSON.fromAddress) matches.

If none of the JSON templates match, the code above can alternatively be called from workflow activity scripts, with validateJSONEmailCondition set to “false” when, after processing the JSON content, further post-processing of the item is required before saving.

Contents