Routing Rules

General info about routing of messages


The rules matching works as follows, see figure above:

  1. Get all rules ordered by priority (higher priority rule gets handled before lower priority rule)

  2. Initially match rules by source system and entity type of message

  3. Check if conditions match the rules

  4. Does rule match response conditions
    • Normal rule and normal message
    • Response rule and response message with matching response conditions
  5. Check if any drop rules match

    • If drop rule, drop message and do no more routing

  6. Ignore rules with wrong operation, i.e. create rule for updates and updates for creates

  7. Identify rules which should be delayed and rules for further processing

  8. Process delayed rules

  9. Route the matching rules

  10. No routing result if no rules match



Matching is case insensitive

All the matching in Routing Rules against attribute names and values is done case-insensitively.


Multiple rules can match the incoming message and in this case, it might be routed to multiple target systems. Next figure shows how the rule matching process works.

When multiple routing rules are matching the same message, the processing order of the rules is based on rule priority values. Rules have a priority of 0 by default. Rule with higher priority (larger value) gets handled before rules with lower priority. Rules with the same priority are handled in a non-determined order.


Delay Rule Executions

In some cases, a message cannot be routed when received, this is when delaying the rule execution comes in handy. See delay routing logic page for details.

Rule editor UI

You can access the rule editor UI by selecting CONFIGURATIONS → ROUTING RULES from the top menu

Rule list view

  1. Create new -button

  2. List on rules

    • Enabled / disabled - indicator

    • View -button

    • Edit -button

    • Collapse

      • Rule version list

        • View

        • Edit

        • Set As Current

      • Import. For importing a rule in a json format.

Single rule view

By clicking the View button from the list of rules, you are able to open a single rule for viewing.

Actions

  • Export - Export the rule in json format.
  • Clone - Create a new rule using the current rule as a template.
  • Edit

Rule version list

  • Displays the list of different rule versions present

  • Action
    • Describes what happens once the conditions of the rule are matched.
      • DROP
        • If drop is selected, the inbound message is not routed further. All rules with drop action are always handled before any other rules, i.e. if a drop rule is matched to an inbound message, no other rules will be matched.
      • ROUTE
        • If route is selected, the the inbound message is routed to defined target system as the defined target entity type.
  • Iterate
    • Describes how many outbound messages are created as a result of the rule being matched. 
      • No
        • One message is sent out
      • By each attachment
        • As many outbound messages are created, as are attachments in the inbound message.
      • By multivalue element (TBA)
  • Source endpoint and entity type

    • This defines to what inbound messages the rule applies to
  • Target endpoint and entity type

    • This defines the endpoint and entity type that will be created after the execution of the rule
  • Message types (Optional)

    • Some API's require message types to be used. These message types are pre-defined by Service-Flow Operations.

By clicking Edit from the action buttons, you are able to edit the rule.

Name and priority are defined in general information and source and target systems, source and target endpoints and target message types are defined in Route Information.

Conditions

Rule is executed if all defined conditions are met (Logical AND function)

  • Target conditions (Apply rule for)

    • Create - Condition is matched if the sources ticket id is not seen before in the target.

    • Update - Condition is matched if the sources ticket id is seen before in the target

    • All messages - Rule applies for all inbound messages

    • Response messages to CREATE message - With this condition, a message can be sent to the originating system from the synchronous response
      • Different rules for Error & Success need to ne defined
    • Response messages to UPDATE message - With this condition, a message can be sent to the originating system from the synchronous response
      • Different rules for Error & Success need to ne defined
  • Attribute Conditions

    • Inbound conditions

      • Condition depending on an inbound attribute value
    • Conversation conditions
      • Condition depending on a conversation attribute value


Note!

By default, the comparison is done against the string value inserted in Value(s) column. You can also compare against either another inbound attribute value or a conversation attribute value. Comparing inbound message attribute to another inbound message attribute is possible with an expression on the value side. Here's an example that will make the condition match when emailAddress1 equals to emailAddress2:


  • Time delay
    • The rule execution can be set to be pending to a defined period of time
  • Delay conditions

    • The rule execution can be set to be pending until a defined value is present. The value can be ether a ticket id, or a conversation attribute value.

  • Attachment condition
    • Inbound message has to have one or more attachments


Attribute mappings


    • Single mapping
      • Source

        • Attribute

          • Defines the attribute from where the value is taken.

          • Default value

            • If the source attribute is not present in the inbound message, or the inbound attribute has no value, a default value can be set
        • Text template

          • This can be used to define a fixed value to the target attribute. Inbound attributes can be concatenated to it by using the expression ${inbound/virtual/conversation attribute}
      • Target
        • Target attribute in the outbound message
      • Formatters
        • Formatters can be used to manipulate the values passed from source to target. The following formatters are available

          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.

          Truncate

          For truncating message to given max length. 

          Some systems cannot handle fields with more than 255 characters

          Lowercase

          Characters to lowercase

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

          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. 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
            • toFormat specifies 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 Supported languages.
    • Table mapping

      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)

        • Define attributes as source. Attributes can be inbound, virtual or conversation attributes.
        • As 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 attribute} 

Virtual attribute mappings

With Virtual Attributes, 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 same kind of configuration many times. Virtual Attributes 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 virtual attributes are evaluated before any other mappings, i.e. they are available to be used in both Attribute mappings and in Conversation attribute mappings. Currently, virtual attributes cannot be used in Mapping Conditions.

Notice the usage of sf:virtual: prefix in the attribute name. This needs to be used everywhere in the mappings. This is to distinguish them from normal attributes in the source message.


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

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


Reset counter

There are some cases when we want to reset counter That was incremented with Increment counter mapping. This can be done with a Reset counter mapping. The next example resets counter myCounter (important: counter should start with "sf:conversation:counter:" prefix) to zero:

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

It is possible to store attachments from the source message to the conversation. This function is enabled once the selection Store source attachments to conversation is set to ON.

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.

  • Map Source Attachments
    • With ON selection, all inbound attachments are added to the outbound message.
  • Map Conversation Attachments
    • With ON selection, all attachments from 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 are done before the removal. 

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

OptionValuesDescription
extensionBlacklist
An array of file extensions.Any attachments that have a matching file extensions will be filtered out
filterFilesWithoutExtension

Boolean

If true, any attachments that don't have file extension will be filtered out. Default is false
maxNumberOfAttachments
NumberSpecifies 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


Saving the rule

With every update, you are required to type in a description of the change. You can either save rule to be set as current later, or save and set current immediately.