Start integrating with ONEiO for free!
SIGN UP

Routing Rule JSON structure

The exported rule is in JSON format that can be edited and imported if needed. A basic rule with two outbound mappings looks the following:

{
"version": 1,
"changeDescription": "test",
"createdTime": 1607344697357,
"createdBy": "user@oneio.cloud",
"active": true,
"activatedTime": 1607344697357,
"activatedBy": "user@oneio.cloud",
"action": "ROUTE",
"ruleId": "2d5b51cde6674907a49f90a7b218c5a4",
"name": "test rule",
"sourceSystemId": "sebastian_snc_jira_snc",
"sourceEntityType": "incident",
"targetSystemId": "sebastian_jira",
"targetEntityType": "Issue",
"targetMessageType": "",
"entityConditions": [],
"conversationConditions": [],
"delayConditions": [],
"virtualAttributeMappings": [],
"mappings": [
{
"type": "Single",
"template": "${short_description}",
"sourceFormatters": [],
"targetAttribute": "fields.summary"
},
{
"type": "Single",
"template": "${description}",
"sourceFormatters": [],
"targetAttribute": "fields.description"
}
],
"conversationAttributeMappings": [],
"attachmentMapping": {
"extensionBlacklist": [],
"filterFilesWithoutExtension": false,
"mapAttachmentsFromConversation": false,
"removeAttachmentsFromConversation": false,
"mapAttachmentsFromSourceMessage": false
},
"priority": 0,
"routeOneTargetPerAttachment": false,
"saveAttachmentsToConversation": false,
"linkedRules": []
}

The first section shows the inbound endpoint, entity and message type, routing information and the outbound endpoint, entity type and message type. 

This information is followed by the mappings in this order:

Attribute Mapping
attachmentMapping Attachment mappings
virtualAttributeMappings Runtime variables
mappings Outbound mappings
conversationAttributeMappings Conversation variables

Lets have a look at a single mapping and which attributes are part of this mapping.

{
"type": "Single",
"template": "${short_description}",
"sourceFormatters": [],
"targetAttribute": "fields.summary"
}

This mapping consists of four attributes, with a fifth attribute fallbackValue only added when in use.

Attribute Usage
targetAttribute Outbound Value
type

TableTranslate

MultiValueToSingle

CounterIncrement

CounterReset

Single

template Source Value
sourceFormatters

RegExp

Truncate

Lowercase

Uppercase

Capitalize

RemoveHtmlTags

ReplaceAll

Date

Translate

Trim

 

Type options

 

TableTranslate

TableTranslate is a very powerful way of mapping one or more related source attributes to one or more target attributes at the same time. It is probably the most commonly used mapping type after Copy and Template.

For a TableTranslate, you define one to several source to target attribute pairs. When the source matches, the target will be result of the mapping. 

The matching happens from first to last in the translation table. This means, that the first line that matches the source attribute value is used.

For source, you can use valuematch and null as detailed below:

Source When does it match?
match

Denotes a special value matcher:

ANY matches any value, also a missing one

BLANK matches when the value is only whitespace (spaces, tabs, linebreaks and newlines)

NOT_BLANK matches when the value contains other text that just whitespace

null Matches when no source attribute of the given name exists, meaning it was never sent by the source system.
value Matches a specific value

 

For target, you can use valuevalueExpression and null as detailed below:

Target What is the result?
value Sets a specific value as the target
valueExpression

Allows combining text and values of attributes using a special notation.

The text is set as given while anything between ${} is interpreted as a placeholder for an attribute name. The placeholder is replaced with the attribute value or set as empty if the attribute was not found.

Attributes from all namespaces are supported: regular, virtual, conversation and header attributes.

null Does not set any value. Useful in cases where nothing should be sent for specific source values.

 

In the following example, we're mapping from multi-level category the another multi-level category:

{
   "type":"TableTranslate",
   "template":[
      "category1",
      "category2"
   ],
   "targetAttributes":[
      "cat_a",
      "cat_b"
   ],
   "translationTable":[
      {
         "source":[
            {
               "value":"ADVANCED ORDERS"
            },
            {
               "value":"DIFFERENT STUFF"
            }
         ],
         "target":[
            {
               "value":"Acme"
            },
            {
               "value":"CAT-000316"
            }
         ]
      },
      {
         "source":[
            {
               "match":"ANY"
            },
            {
               "value":"STUFF"
            }
         ],
         "target":[
            {
               "value":"Small Potatoes"
            },
            {
               "value":"CAT-000316"
            }
         ]
      },
      {
         "source":[
            {
               "match":"BLANK"
            },
            {
               "match":"BLANK"
            }
         ],
         "target":[
            {
               "value":"Small Potatoes"
            },
            {
               "valueExpression":"CAT-${category_id}"
            }
         ]
      }
   ]
}

MultiValueToSingle

Whenever you have a list of values from the same source which need to be aggregated to the same target field then this mapping is handy.

E.g. if Service-Flow receives the following json containing an array:

{root: { array: ["first", "second"]}}

It would be mapped into two Service-Flow attributes with the name "root.array" and the values: "first" and "second": 

root.array: first
root.array: second

These two attributes can be mapped into one single field with the "Multiple values to single value" mapping. A mapping with the delimiter ", " would map the "root.array" multi-value into the value "first, second". Here's an example of the resulting field: 

singleField: first, second

Here's an example how the configuration looks like:

{
"type": "MultiValueToSingle",
"sourceAttribute": "root.array",
"targetAttribute": "singleField",
"delimiter": ", "
}

The delimiter is ", " by default, but can be configured to anything.

 

CounterIncrement

There are some cases when we want to decide what to do based on how many times something has happened. For these cases, there's a CounterIncrement mapping, which can increment integer valued conversation attributes. The next example increments counter myCounter: 

{
"type": "CounterIncrement",
"counterName": "sf:conversation:counter:myCounter",
}

The counter has to start with the "sf:conversation:counter:" prefix

 

CounterReset

There are some cases when we want to reset a counter which was incremented with CounterIncrement mapping. This can be done with a Reset counter mapping. The next example resets counter myCounter to zero:

{
"type": "CounterReset",
"counterName": "sf:conversation:counter:myCounter",
}

The counter has to start with the "sf:conversation:counter:" prefix

 

Source Formatter options

Formatter Example configuration

Regular expression

Can be used to only take part of message using a regular expression. Value of the first matching capture group is returned.

To avoid possible problems with backtracking regular expressions we are using RE2 engine which has some restrictions described here.

{
"type": "Single",
"template": "${description}",
"sourceFormatters": [
{
"type": "RegExp",
"expression": "^.*\\(Work notes\\)\\s*([\\s\\S]*)"
}
],
"targetAttribute": "summary"
}

Truncate

For truncating message to given max length.
Some systems cannot handle fields with more than 255 characters

{
"type": "Single",
"template": "${description_truncate}",
"sourceFormatters": [
{
"type": "Truncate",
"length": 255
}
],
"targetAttribute": "description_truncate"
}

Lowercase

Characters to lowercase

{
"type": "Single",
"template": "${description_lowercase}",
"sourceFormatters": [
{
"type": "Lowercase"
}
],
"targetAttribute": "description_lowercase"
}

Uppercase

Characters to uppercase

{
"type": "Single",
"template": "${description_uppercase}",
"sourceFormatters": [
{
"type": "Uppercase"
}
],
"targetAttribute": "description_uppercase"
}

Capitalize

Capitalizes each word from the value. I.e. first character is in upper case and all the rest are in lower case.
Supported word separators are space and dash (-) characters.

{
"type": "Single",
"template": "${description_capitalize}",
"sourceFormatters": [
{
"type": "Capitalize"
}
],
"targetAttribute": "description_capitalize"
}

Remove HTML tags

Removes all HTML tags

{
"type": "Single",
"template": "${description_remove_html}",
"sourceFormatters": [
{
"type": "RemoveHtmlTags"
}
],
"targetAttribute": "description_remove_html"
}

Replace all matching characters

Replaces all occurrences that matched a given template with given replacement.

The matching can be done also by using regular expressions. To do that, set the isRegex field as true.

When using regular expression matching, the template field must contain a valid regular expression.

{
"type": "Single",
"template": "${description_replace}",
"sourceFormatters": [
{
"type": "ReplaceAll",
"template": ":",
"replacement": "-",
"isRegex": false
}
],
"targetAttribute": "description_replace"
}

Change date format

Changes date format for given date string. If an attribute is marked as date in Service-Flow's internal schema for some system, then the date string is always already in ISO 8601 format. Otherwise the date string could be taken from some other field, for example with a Regular expression formatter and it could be in some other date format.

fromFormat specifies initial format of the date. Should be valid date format, EpochTime or EpochTime_s which can be used in the case the date string has a number with milliseconds or seconds from the Epoch. If not present, default date format is ISO 8601.

fromTimeZone specifies the timezone that the given date is in. If not present, defaults to UTC. In the case of EpochTime and EpochTime_s in fromFormat, this is not relevant at all.

toFormat specifies destination format of the date. Also should be a valid date format, EpochTime or EpochTime_s and is required.

toTimeZone specified the timezone that the destination attribute should be in. If not present, defaults to UTC.

{
"type": "Single",
"template": "${description_date}",
"sourceFormatters": [
{
"type": "Date",
"fromFormat": "dd/mm/yyyy",
"fromTimeZone": "Europe/Helsinki",
"toFormat": "mm/dd/yyyy",
"toTimeZone": "America/Chicago"
}
],
"targetAttribute": "description_date"
}

Translate

Changes the language of an output via Google Translate

{
"type": "Single",
"template": "${description_translate}",
"sourceFormatters": [
{
"type": "GoogleTranslate",
"target": "en",
"source": "fi"
}
],
"targetAttribute": "description_translate"
}

Trim whitespace

Removes all leading and trailing whitespace.

{
"type": "Single",
"template": "${description_trim}",
"sourceFormatters": [
{
"type": "Trim"
}
],
"targetAttribute": "description_trim"
}

Using multiple formatters in attribute mapping

There is also support for using multiple formatters for the same attribute mapping. The formatters are applied in the order they are in the sourceFormatters array. Here's an example on first selecting text with a regular expression and then truncating the result to 5 characters:

{
"type": "Single",
"template": "${description_truncate}",
"sourceFormatters": [
{
"type": "RegExp",
"expression": "(INC.*)"
},
{
"type": "Truncate",
"length": 5
}
],
"targetAttribute": "description_truncate"
}

It is allowed to use either only sourceFormatter or sourceFormatters property in one attribute mapping for clarity. Specifying both properties will lead to error when uploading the mapping.

Fore more information on the export & import of Routing Rules please visit this article:

How to use the Routing Rule export & import function.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.