Processing Emails with JSON Content

Motivation

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

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

Email JSON Format

The email compiled 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 components:

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

  The values are always the visible values of the fields, i.e. for list type attributes, the label and not the ID must be specified.

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

  Most personal 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. An 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 like 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. Explanation below under item.emailReceived.isJSON.tokenValue

Configuring the JSON Processing

The following values can be set under Server Configuration -> Miscellaneous -> “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 to be processed as JSON content
item.emailReceived.isJSON.fromAddress	The sender address of the email to be processed as JSON content
item.emailReceived.isJSON.addNotOnFormAttributes	Whether to add the attributes identified from the JSON that are not present in the form for the new entry; default is false (neglect attributes not in the form)
item.emailReceived.isJSON.addNotOnFormAttributes	Whether to add the attributes identified from the JSON
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 will be 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 designated as the creator of the newly created entry.

Notes for Developers

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

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

jsonParserService.applyJSONContent(inputBinding, emailRejector, true);

The value “true” for validateJSONEmailCondition ensures that the function is only called if 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 above code can alternatively be called by scripts for workflow activities, setting validateJSONEmailCondition to “false” if further post-processing for the item is required before saving, after processing the JSON content.