Routing Rules

Introduction

The main component in ONEiO to create a logical information flow is called a Routing Rule. It includes all information needed to transfer data between two or more endpoints. All mappings between corresponding value pairs and all creation of conversation and/or runtime variables are being done inside of the main rule view.

Table of Contents

Rule list view

• Edit Section
  • Rule name filter
  • Use Case filter
  • Bulk actions
• List Section
  • Rule Versions

Rule Editor

• Rule and Route
• Rule Information
• Route Information
  • Inbound
  • Operation
  • Outbound
  • Condition
  • Delays
  • Response rules

Mappings

• Types of Mappings
  
  • Mapping
  • Conditional mapping
• Categories of Mappings
  • Outbound Mappings
  • Runtime mappings
  • Conversation mappings
  • Attachment mappings
  • Header Attribute Mappings

Advanced editing

Rule list view

Here you get an overview of all routing rules in your subscription/environment, access to those rules, and the possibility to create new rules when needed. 

This view consists of two parts, the upper Edit section, and the lower List section. 

Edit Section

The edit section lets you work with rules in the list view in multiple ways. The left-hand side includes filters for both Rule Name and Use Case. And a switch to either show or not show Response Rules. The right-hand side has Bulk actions. Plus Import and Rule creation.

Rule name filter

Rules can be filtered by name, the filter is not case-sensitive.

Use Case filter

Rules can be filtered by Use Case, the filter is not case-sensitive.

Bulk actions

Available Bulk actions include.

• Enable
• Disable
• Delete

List Section

This section gives an overview of all Routing Rules available in this environment.

The left side chevron opens the rule versioning where you get a view of all versions of this particular rule and next to it is an indicator of whether the rule is active or not. Green means active, and gray is inactive.

On the right side, the three-dotted menu gives you the following options.

1. Disable rule
2. View rule
3. Edit rule
4. Delete rule

You can also access a rule by double-clicking the list row.

Rule Versions

This view shows all versions of a rule and gives the option to:

1. Set as current (for versions that are not currently set as current)
2. View version
3. Create a new version based on this one.
   • This function opens up the same view as "+ Create a new rule", but with the mappings of the rule, this is triggered. Note that the new rule is created only after the creation is submitted.

Rule Editor

Rule view consists of two tabs.

• Rule and Route presents the definitions of when the rule is triggered
• Mappings present what is done when this rule is triggered.

Rule and Route

Here you see the Rule editor in editing mode. This view is split into two parts, the upper Rule Information, and the lower Route Information.

Rule Information

Information given here on the left is:

On the right is a graphical representation of the rule routing, representing the inbound and outbound endpoints.

Route Information

The route information defines the way a particular message will be routed, what conditions needed to be matched for this rule to be executed, and if set delays will occur.

The following fields are available:

Inbound 

Defines to what inbound messages the rule is defined.

• Source system
• Source entity type
• Conditions can be defined if there is a need to not execute the rule for all inbound messages of the defined endpoint/entity type.
  • Attribute conditions can be defined against inbound attributes or conversation variables
  • Attachments conditions define the execution of a rule depending if the inbound message has attachments or not

Operation

Defines what the rule will do once it is matched.  

• Action defines what happens after the rule is matched
  • Route to the target relays the message to the target according to the mappings defined.
  • Process-only does all the same things as Route but does not send out the outbound message. This is normally used to set some values to a conversation for later use, even if we do not want to relay the message.
  • Drop the message stops all processing of the inbound message. Note that all drop rules are handled first, regardless of rule priorities.
• Apply rule for is used the same way as the conditions in the inbound section, but is related to how this message correlates to the target endpoint/entity type. You can define if the rule is matched if there has already been activated to this ticket in the target endpoint/entity type.
  • CREATE messages mean that the rule matches if we have not sent this ticket earlier to the defined endpoint/entity type, or if the target system has not sent any messages to this ticket. I.e. the conversation does not exist. 
  • UPDATE messages mean that the rule matches if we have sent this ticket earlier to the defined endpoint/entity type, or if the target system has sent any messages to this ticket. I.e. the conversation exists.
  • All messages mean that the rule matches regardless of if the ticket has been seen before.
• Iterate option can be used if there is a need to produce multiple outbound messages from a single inbound message. F.ex. there can be a situation where an inbound message contains three attachments but the target would need them to be sent one by one.
  • Message element selection produces as many outbound messages as there are sub-elements in the inbound messages element defined. For each outbound message, the selected element will have just a single value from the sub-elements, starting from the first one.
  • Delimiter-separated values selection produces as many outbound messages as there are split results in the selected inbound message's element. The split is done with the configured separator. E.g. if the inbound message's element contains the string "First; Second; Third" and we define a semicolon as the separator, we will get 3 outbound messages, where first has value "First" as the element value, second has value "Second" as the element value and third has value "Third" as the element value.
  • By each inbound attachment, selection produces as many outbound messages as there are attachments in the inbound message

Outbound

Defines where outbound messages are sent.

• Target system
• Target entity type
• Target message type is an optional selection that can be used in case the target system requires the use of different APIs or data structures. These are defined in the endpoint configuration.  

Condition

• Message conditions are conditions checked against the inbound message. There are two types of message conditions: conditions that check the attributes of the inbound message and conditions that check attachments of the inbound message.

   

• Attribute conditions

  The parts of the condition are:

  • attribute: what attribute to check. Attributes can be from the inbound message or a conversation variable. 
  • operation: How to check. Here are the possible operations and their usage.

    Operation	Usage
    EQUALS, NOT_EQUALS	Exact match (or inverse) for a string value
    EXISTS, NOT_EXISTS	Checks if the attribute exists (or not) regardless if the attribute contains a value
    STARTS_WITH, NOT_STARTS_WITH	Matches the beginning of a string value (or not)
    IN, NOT_IN	Matches a value in an array. This can be used to create an OR function
    CONTAINS, NOT_CONTAINS	Matches part of a string (or not)

  • value: What value should we use for the comparison. This single-value is used for all the other operations than IN and NOT_IN. Value can be a string or an attribute. If you set ${some_attribute} as value, the conditions need to match the value of attribute some_attribute. Attributes can be from the inbound message or a conversation variable. 

  There can be several message conditions defined. When there are multiple conditions, all of them have to match (AND operation).

Delays

• Time Delay defines a time in seconds that the rule execution is delayed. Note that the delay is done after the mappings have been executed.
• Conversation variable delay makes the rule delay as long as there is some value in the variable defined. This can be used to f.ex. delay a comment or attachment addition before the id of the target ticket is found from the defined conversation variable.
• Endpoint ID delay (deprecated)
• Here you can find more information about delayed routing logic.

Response rules

Response rules are created from the rule they should react to. If you navigate to a rule's tab Rule and Route, you can see all response rules that possibly could match this rule currently. There is also Create new button, in case you need to create a new one.

Please note that in the list of a single rule, there can be multiple possible response rules. The amount of rules matched in the actual case is then dependent on the conditions that the response rules have.

Mappings

Under the section called mappings, there are three main categories.

1. Outbound mappings
2. Runtime mappings 
3. Conversation mappings

We will dive deeper into these categories later. 
Each of these three categories can have either of these two types - a mapping and/or a conditional mapping and you can add as many of these two types straight from the UI.  The image below highlights how to add these two types when creating a new rule and the ability to collapse and expand the list of mappings under each category.

To ease the setup of mappings, ONEAi® can suggest mappings. You will need to first select the endpoints and entity types for the rule to ask ONEAi® for suggestions. Clicking the third ONEAi button will open a modal and suggest suitable mappings. You can then decide which suggested mappings to add to the mappings. ONEAi® suggestions only work for mappings and conditional mappings are not suggested.

Adding a mapping or conditional mappings in a new rule creation

Listed below are the editing options for mappings or conditional mappings to an already existing rule with mappings:

• Duplicate a mapping or a conditional mapping
  
  
  
• Delete a mapping or a conditional mapping
  
  
  
• Add a new mapping or conditional mapping to an existing rule with mappings. Hover on the line beneath any mapping to reveal the options to add a new mapping or conditional mapping.
  
  
  
• Move/Drag a mapping up or down the list of mappings
  

Let us now consider the two types that can be add straight from the UI.

Mapping

On the Inbound side(left hand side of the arrow) of each mapping, you can have one or a combination of inbound source attribute(s) and fixed value(s) that will be set or mapped to the outbound side(on the right hand side of the arrow). 

Here are 3 different but common examples of mappings showing view and in edit mode for each  examples

• First example is an inbound source attribute mapped to a outbound attribute. By default, the inbound side is treated as source attribute with the toggle turned off in edit mode.
  • View mode
    
    
    
  • Edit mode
    
    
    
    
• Second example is a inbound fixed values mapped to a outbound attribute. The toggle needs to be turned on in edit mode.
  
  • View mode
    
    
    
  • Edit mode
    
    
    
    
• The third example has the combination of inbound source attributes, fixed values, conversation variables and runtime variables mapped to outbound. Upon saving, the toggle is automatically turned on and cannot be turned off (in this state, the toggle, though turned on, is slightly blur compared to the previous image). 
  • View mode
    
    
    
  • Edit mode
    

Conditional Mapping

Conditional mappings are presented in a form of a table mapping. When the message includes the defined source values, the corresponding target values will be set to the outbound message.

Example: Impact == 1, Urgency == 3 --> Priority = "High"

You can use one or more source and/or target attributes. Table is read from top down. When all the source values are met, the corresponding values to outbound messages are set. Note that the matching against source values is done case-insensitively.

As mentioned above, the editing options for mappings are also available for conditional mappings. Additional editing options include: 

1. Adding columns Adding rows
2. Duplicating columns and rows
3. Deleting tables

• Source attribute(s)

  • Source is the attribute that is used as the compared value. Attributes can be inbound, virtual or conversation attributes. For table headings, only variables can be used, NOT placeholders. F.ex 
    • sf:conversation:fuu OK
    • ${sf:conversation:fuu} NOT OK
  • As a compared value, you can use a string value, attributes with expression ${inbound/virtual/conversation attribute}, or a special value matcher
    • Available matchers
      • ANY
      • BLANK (matches spaces, tabs, etc.)
      • NOT_BLANK (matches any alphanumeric value)
      • No value (matches empty strings or missing fields)
• Target attribute(s)
  • As a value to the outbound message, you can select a string value, or concatenation of string and attribute values, attributes with expression ${inbound/virtual/conversation/header attribute}

Outbound mappings

A view of the Outbound Mappings

ONEiO has multiple different namespaces for attributes. The namespaces are marked in the attribute name. The following table shows what namespaces currently exist.

• Fallback value. If "Use fallback value" is checked and text template processing results in an empty string, the value from this field will be used (even if it is an empty string).

• Formatters

  • Formatters can be used to manipulate the values passed from source to target.

  • In View mode, if the formatter is configured on, it is indicated by FX text highlighted in blue. Click on it reveals the formatters configured.
    
    
    
    
    
    
  • In Edit more, you will see the letters "fx" for all the mappings in between the inbound and outbound. You can access the formatters section to see what is already configured and access all the formatters options. 
    
    
    
    
    

  • The following formatters are available 

    Formatter	Usage
    Regular expression	Can be used to only take part of a message using a regular expression. The value of the first matching capture group is returned. To avoid possible problems with backtracking regular expressions we are using the RE2 engine which has some restrictions described HERE. A good way to test the RegEx is reger101.com. Please choose Java 8 as the format. Note that escape sequences such as newline \n and tab \t need to be escaped, so they need to be written as \\n for example.
    Truncate	For truncating message to given max length.  Some systems cannot handle fields with more than 255 characters
    Lowercase	Characters to lowercase
    Uppercase	Characters to 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.
    Remove HTML tags	Removes all HTML tags from the value. Also replaces all non-breaking spaces ( ) with whitespace.
    Replace all matching characters	Replaces all occurrences that matched a given template with a 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. Note that replacement is a literal string, i.e. it will be inserted as-is and no placeholder replacement will happen.
    Change date format	Changes date format for given date string. If an attribute is marked as the date in ONEiO'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 the initial format of the date. Should be a valid date format. If not present, the default date format is ISO 8601. fromTimeZone specifies the timezone that the given date is in. If not present, defaults to UTC toFormat specifies the destination format of the date. Also, should be a valid date format and is required. toTimeZone specified the timezone that the destination attribute should be in. If not present, defaults to UTC.
    Trim whitespace
    Language translate	Translates the input value. source specifies the language of the source text. The value should be one of the language codes listed in Supported languages. If a language is not specified, the system will attempt to identify the source language automatically. target specifies the language to translate the source text into. The value should be one of the language codes listed in the Supported languages
    Base64 decoding	Decodes a Base64 encoded value to a string. E.g. the value c3VwcG9ydEBvbmVpby5jbG91ZA== would be decoded to support@oneio.cloud.
    Convert bytes	Convert bytes to a human-readable format (e.g. MB, GB). When applied, for example, the value 4429185024 would be formatted as 4.13 GB

     

• Target
  • Target attribute in the outbound message body.
  • When entering the target attribute, ONEAi® will suggest an attribute that you can add to the target field. It can be accepted by either clicking on the ONEAi® button or using the keyboard shortcut Ctrl/Cmd+Enter.

Runtime Mappings

Conversation Mappings

Conversation Attribute Mappings

Conversation attribute mappings allow storing attribute values to a conversation and make them available later in other rules. Conversation attribute mappings differ from normal mappings in that the value will not be sent to outbound messages. Instead, the value is stored in the conversation and can be used conditions, or as the source value of regular attribute mappings.

A typical use case would be to store the status/state of a ticket as a conversation attribute so that subsequent update rules can "know the previous status" or storing a system's id in a multi-endpoint environment.

It is worth noting that when executing a specific rule, the conversation attribute mappings are done after regular mappings.

Notice the usage of sf:conversation: prefix in the attribute name. This needs to be used everywhere in conditions and mappings to denote that we actually mean a conversation attribute.

Conversation Counters

It is possible to have conversation attributes that have integer values and can be used as counters. These counters have their own attribute mappings to increment and reset the value. They also have their own conditions LESS_THAN and GREATER_THAN_OR_EQUALS. Counters have the prefix sf:conversation:counter:. At the moment, the rule editor does not support creating or editing conversation counters. This feature needs to be handled with JSON export/import of the rule. 

INCREMENT COUNTER

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 an Increment counter mapping, which can increment integer-valued conversation attributes. The next example increments counter myCounter (important: counter should start with "sf:conversation:counter:" prefix).

Attachment mappings

Attachments are mapped by adding an attachment mapping to the routing rule. Without it, no attachments will be routed to the target system. These configuration can be found right below the outbound mappings and conversation Mappings

• Map Source Attachments
  • With ON selection, all inbound attachments are added to the outbound message.
• Map Conversation Attachments
  • With ON selection, all attachments from a conversation, that are not yet relayed to the target system/target entity, are added to the outbound message.
• Remove Conversation Attachments
  • With ON selection, all attachments in the conversation are removed. This removal is done after the rule is processed, i.e. the mapping of conversation attachments is done before the removal. 

The Attachment mapping has several optional configuration options which can be used to filter the mapped attachments.

extensionBlacklist

filterFilesWithoutExtension

maxNumberOfAttachments

maxIndividualAttachmentsSize

maxTotalAttachmentsSize

Header Attribute Mappings

While not having its own section in the UI, there is a possibility to use header attributes in mappings. Currently, we support the following mappings as the source and target attributes in routing rules.

• sf:header:id
• sf:header:conversation_id
• sf:header:operation
• sf:header:receive_time
• sf:header:receive_time_isodate
• sf:header:source_system
• sf:header:source_type
• sf:header:source_message_type
• sf:header:source_id
• sf:header:source_parent_id
• sf:header:target_system
• sf:header:target_type
• sf:header:transaction_id

Advanced editing

For advanced editing (JSON) and advanced functionalities, please refer to this article: Routing Rule JSON structure