How to use the Routing Rule export & import function

Introduction

Routing Rules can be exported in JSON format, edited, and imported back into ONEiO. It is possible to export and import single rules or multiple rules in bulk.

Overview

This introduces some rule functionalities not currently available in the UI, such as MultiValueToSingle and Counters. Furthermore, it gives customers the possibility to move routing rules from one subscription to another.

1. Exporting
   1. From inside the rule
   2. From the rule list view
   3. Exporting all rules
   4. Bulk exporting
2. Importing rules
   1. Importing new versions of existing rules
   2. Creating new rules by importing
   3. How to import rules
   4. Common requirements for the import file
   5. Example format

Exporting 

You can export routing rules in various ways through the UI:

1. Inside the rule itself
2. From the rule list view

1) From inside the rule

This will export the currently viewed Routing Rule in JSON format as a direct download.

2) From the rule list view

A specific version of a Routing Rule can be exported by:

1. Choose the rule in the list view, click on the three-dotted menu, and select "export into file" to export the latest version OR
2. Open the version submenu, select the version, click on the three-dotted menu, and select "export into file" to export a specific rule version.

Exporting all rules

It is possible to export all of the rules contained in the active environment. By clicking on the Export all button on the top of the Routing rules page a file containing all of the rules will be created and downloaded. It is not possible to filter which rules will be imported.

Bulk exporting

You can export multiple rules simultaneously by using the bulk export option. Just click the checkboxes next to the rules you want to export. Then, at the top-right corner of the page, then choose "Bulk Export" from the dropdown menu labeled "Bulk Actions."

Importing rules

Rules can be imported using the Import button on the top of the Routing rules page. An import can contain one or more rules. Depending on the content of the rule file, there are two main behaviors:

• Importing new versions of existing rules
• Creating new rules by importing

Importing new versions of existing rules

When a rule has been exported from ONEiO, it is possible to make edits to the JSON file and import those changes. ONEiO will detect if the rule already exists by checking the rule ID field in the file. When a matching rule ID is found, ONEiO will create a new version of the rule. If the property active is set to be true, this new version will be set as the current version of the rule.
If you would like to import changes that you do not want to take immediate effect, change the active property to false. ONEiO will then import a new version for the rule and not affect the current rule that is in use.

Creating new rules by importing

Creating new rules by importing is often used when you would like to import rules from another subscription, or when moving rules between the QA and PROD environments.

To successfully import new rules, you will need to ensure the rule ID value doesn’t match an existing rule (otherwise a new version of the imported rule will be created).

How to import rules

Select the "Import" button from the rule list view.

Either "drag & drop" the JSON file into the upload modal, or choose the file from the explorer.

The rules in your import file will either update existing rules if the IDs match, or create new rules that are set as the current version, but are inactive. If the import fails, you will receive an error notification.

Common requirements for the import file

There are some common requirements for the import file to function. The import feature currently doesn’t indicate what requirements have not been met, so please refer to the following list to ensure a successful import:

• The rules in the JSON file need to be wrapped into an array instead of a single object, i.e. the file needs to begin with an [ and end with an ]

Example format

[
{
<<"routing-rule">> 
}, 
{
<<"routing-rule">> 
} 
]

• The maximum supported filesize for import is 50MB
• Import and export support the maximum number of rules allowed within an environment (QA or PROD).
• Imported files are checked to include the following values in the document, otherwise the import will fail immediately:
  
  • name
  • action
  • active
  • ruleId
  • sourceSystemId
  • sourceEntityType
  • targetSystemId
  • targetEntityType
  • targetMessageType
• Once these checks have passed, ONEiO will further check that
  • The sourceSystemId, sourceEntityType, targetSystemId, targetEntityType and targetMessageType exist in the environment you are importing to
  • To fix the import file, edit the file you are attempting to import to match the correct Ids and entity types exactly as they are in the environment you are importing to