Start integrating with ONEiO for free!
SIGN UP

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.

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. 

ONEiO__xONEiO_Demo_-_Enterprise__1_.png

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

Edit Section

ONEiO__xONEiO_Demo_-_Enterprise__1__edit.png

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.

ONEiO__xONEiO_Demo_-_Enterprise__5_.png

Use Case filter

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

ONEiO__xONEiO_Demo_-_Enterprise__6_.png

Bulk actions

Available Bulk actions include.

  • Enable
  • Disable
  • Delete

ONEiO__xONEiO_Demo_-_Enterprise__2_.png

 

List Section

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

ONEiO__xONEiO_Demo_-_Enterprise__1__list.png  

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 the rule is active or not. Green means active, gray 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

ONEiO__xONEiO_Demo_-_Enterprise__3_.png

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 from. Note that the new rule is created only after the creation is submitted.

ONEiO__xONEiO_Demo_-_Enterprise__4_.png

 

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

ONEiO__xONEiO_Demo_-_Enterprise__7_.png

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

ONEiO__xONEiO_Demo_-_Enterprise__7__rule_information.png

Information given here on the left are:

Field Name Usage
Name

The best practice is to use as short names as possible. This will help you out in various situations while running the integrations.

Use Case

Use Case can be used to tag routing rules for easy filtering in the Routing Rule list view.

Priority

Priority defines the order of the rule execution in case multiple rules are matched to the same inbound message. The highest priority number is run before the lower. For. ex. Two rules matching an inbound message; A has priority 0 and B has priority 5. In this case, B is run first and A after the transaction of B is complete.

Version

Which version number of this rule is currently visible.

Updated

Date, Time & Email of the last update to this routing rule

Change description

Description of the last change if given on save.

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

Route Information

ONEiO__xONEiO_Demo_-_Enterprise__7__route_information.png

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

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 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 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 inbound message's element contains the string "First; Second; Third" and we define 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
  • Conditions
    • 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)

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.  
  •  

Mappings

Outbound mappings

ONEiO__xONEiO_Demo_-_Enterprise__10_.png

Single mapping

Source is that value the will be set to the outbound attribute. You can combine any number of inbound attributes and fixed values. Inbound attributes are referenced using a placeholder expression ${attribute}.

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

  Prefix Child values Notes
Inbound message attributes   Anything. User-defined When there's no namespace, the attributes are from the actual message bodies. Example:  ${inbound_attribute}
Runtime variables sf:virtual: Anything. User-defined Use for accessing runtime variables. Example:  ${sf:virtual:my_runtime_variable}
Conversation variables sf:conversation: Anything. User-defined Use for accessing conversation variables.Example:  ${sf:conversation:my_conv_variable}
Header attributes sf:header: id
conversation_id
operation
receive_time
receive_time_isodate
source_system
source_type
source_message_type
source_id
source_parent_id
target_system
target_type
transaction_id
 

Use for accessing message header values. Example:  ${sf:header:receive_time_isodate}

 
  • 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. 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 GoLang as the format.

      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 using Google Translate service.

      • 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

Table mapping

Table mapping is used as conditional 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.

  • 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 or a special value matcher
      • Available matchers
        • ANY
        • NOT_BLANK
        • No value
  • 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}

Runtime variables 

ONEiO__xONEiO_Demo_-_Enterprise__11_.png

With runtime variables, you can define values that can be used as source values in Attribute Mappings in the same rule. This way the actual mappings can be made simpler, more readable and you can avoid repeating the same kind of configuration many times. Runtime variables are evaluated at routing time using the values in the incoming message and are available only for the duration of that specific execution. For subsequent messages values are evaluated again. All the same mappings as in Attribute Mappings are available to be used.

Values of the runtime variables are evaluated before any other mappings, i.e. they are available to be used in both Attribute mappings and in Conversation attribute mappings.

NOTE

Currently, runtime variables cannot be used in Table Mapping Conditions.

 

Conversation variables

ONEiO__xONEiO_Demo_-_Enterprise__12_.png

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

ONEiO__xONEiO_Demo_-_Enterprise__13_.png

Attachments are mapped by adding an attachment mapping to the routing rule. Without it, no attachments will be routed to the target system.

  • 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.

Option Values Description
extensionBlacklist
An array of file extensions. Any attachments that have a matching file extension will be filtered out
filterFilesWithoutExtension
Boolean If true, any attachments that don't have a file extension will be filtered out. Default is false
maxNumberOfAttachments
Number Specifies the maximum number of attachments that will be routed. Any additional attachments will be filtered out
maxIndividualAttachmentsSize
Number (bytes) Specifies the maximum file size of each individual attachment in bytes. Any attachment larger than the value will be filtered out
maxTotalAttachmentsSize
Number (bytes) Specified the maximum total size of attachments in bytes. When the limit is reached, any additional attachments are filtered out

 

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 following mappings as 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
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

2 comments
  • It would be useful if we could group routing rules
    It gets difficult to find a particular routing rule for a particular integration, when there are too many routing rules.

     

    1
    Comment actions Permalink
  • please add sf:errors

    0
    Comment actions Permalink

Please sign in to leave a comment.