Start integrating with ONEiO for free!

Routing Rules


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

Rule Editor


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:

Field Name Usage

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


Which version number of this rule is currently visible.


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


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:


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


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


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.  


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


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



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.

Add your first mapping - two options.png

Adding a mapping or a 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
    Duplicating a mapping.png

  • Delete a mapping or a conditional mapping
    Deleting a mapping.png

  • 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.
    Add a new mapping or conditional mapping to an existng rule with mappings.png

  • Move/Drag a mapping up or down the list of mappings
    Drag to move mapping up or down in the current section.png


There are other types of mappings that cannot be added directly from the UI and require exporting the Routing Rule JSON structure and adding that directly. These are MultiValueToSingle, CounterReset and CounterIncrement. More of this in our article on Routing rule JSON Structure.

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


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
       An inbound source attribute mapped to an outbound attribute - view mode.png

    • Edit mode
      An inbound source attribute mapped to an outbound attribute - edit mode.png

  • Second example is a inbound fixed values mapped to a outbound attribute. The toggle needs to be turned on in edit mode.
    • View mode
      inbound fixed value mapped to a outbound attribute - view mode.png

    • Edit mode
      inbound fixed value mapped to a outbound attribute - edit mode.png

  • 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
      A combination of attributes and fixed values mapped to an outbound attribute - view mode.png

    • Edit mode
      A combination of attributes and fixed values mapped to an outbound attribute - edit mode.png

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

Outbound mappings

A view of the Outbound Mappings.png

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.

  Prefix Child values Notes
Inbound message attributes   Anything. User-defined Unless you are utilising a combination of actual inbound source attributes (${inbound_attribute}), fixed values and other attribute namespace, you can use the toggle to switch between an actual source attribute or a fixed value 
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

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

Errors and Warnings




Use to access errors and warnings from the response payload or error response. Example: ${sf:errors}. See more about how to handle error messages and how to extract them with regex.
  • 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.

      Screenshot 2024-06-06 at 14.14.13.png

      Screenshot 2024-06-06 at 14.17.00.png

    • 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. 
      Screenshot 2024-06-06 at 14.23.50.png

      Screenshot 2024-06-06 at 14.29.57.png

    • 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 Please choose GoLang 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.


      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

      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

      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

Runtime Mappings

Runtime Mappings.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.


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


Conversation Mappings

Conversation Mappings.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. 


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

Screenshot 2024-06-06 at 13.40.44.png

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.

Option Values Description
An array of file extensions. Any attachments that have a matching file extension will be filtered out
Boolean If true, any attachments that don't have a file extension will be filtered out. Default is false
Number Specifies the maximum number of attachments that will be routed. Any additional attachments will be filtered out
Number (bytes) Specifies the maximum file size of each individual attachment in bytes. Any attachment larger than the value will be filtered out
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 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

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


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


    Comment actions Permalink
  • please add sf:errors

    Comment actions Permalink

Please sign in to leave a comment.