Routers
Routers are components that route messages using user-defined rules. They can be used to route messages based on the message content or headers.
Each router consists of one or more rules that consist of a rule name, a Groovy script that specifies the condition, and a flow of components to execute if the rule evaluates to true.
The Routers page is where you can view and add your routers. Use rules to route to different things.
On the Routers page, view the list of routers.
Search for a router
On the Routers page, you can search for a specific router using the default search fields.
In the top right corner of the page, select New Router.
In the Create New Router dialog box, enter the initial router information, and select Next.
Continue entering the additional router information and then selecting Next until you reach the final step.
Select Create Router. The Router Details page displays as a draft version of the router.
In the top right corner of the page, select Approve > Yes to approve the draft.
If the Peer Review feature is enabled in General Settings, the processor must be approved by a peer with the Manager role or higher before it can be activated.
The router has the name you gave it and an ID that X1 automatically assigned to it, based on the name.
The ID is lowercase and replaces spaces with dashes, and it's also permanent and can't be edited.
Note
If you want to delete the draft before approving it, select
.
See the "New Router Field Descriptions" below for more information about the router fields.
New Router Field Descriptions
Field | Description |
|---|---|
Name | Enter a relevant name for the router. |
Type |
|
Adapter | The adapter the router runs in. |
Request Document Type | The document type the router expects to receive. |
Response Document Type | The document type the router will return. Can be NONE if the router does not return a document. |
Note
After you create the router, its details page displays where you can add additional information about the router.
See the procedures below for more information about creating each type of router.
Create a Content Based router
Refer to the table below for guidance after you've completed the initial steps in the Create a router procedure above.
Field and tab | Description |
|---|---|
ID | The ID that X1 automatically assigned to the router, based on the name. The ID is lowercase and replaces spaces with dashes. The ID is permanent and can't be edited. |
Type | The type you assigned to the router when you created it. The type is permanent and can't be edited. |
Name | The name you assigned to the router when you created it. |
Adapter | The adapter you assigned to the router when you created it. |
Request Document Type | The request document type you assigned to the router when you created it. |
Response Document Type | The response document type you assigned to the router when you created it. |
Is Undeliverable? | How to handle undeliverable messages. Can be set to Error or Dead Letter. |
Is Multicast? | If true, the router sends the message to multiple destinations. |
Rules tab | Displays all the rules for this router. Double-select a rule to view its details. Router rule scripts are executed against the message body and have available the body and headers variables. The body variable contains the message body, and the headers variable contains the message headers. Normally, the body consists of an X1 envelope, which contains a document and a header. |
Add Router Rule | Displays the Flow Designer for the router rule where you can specify a rule name. Approve the draft for the changes to take effect. Each router must have a default rule that's executed if no other rule evaluates to true. The default rule is a special rule that's always evaluated last. It doesn't have a condition, but it does have a flow of components to execute if no other rule evaluates to true. There can be only one default rule for a router. Router Rule Scripts Router rule scripts are written in Groovy and return a boolean value. If the script returns true, the rule passes. If the script returns false, the rule fails. Here are some examples: Router Rule Example 1: Route based on a document property The following router rule script routes messages based on the value of a property in the message body. If the scac property in the message body is either "CNWY" or "XPOL", the rule evaluates to true. body.document.scac == "CNWY" || body.document.scac == "XPOL" Router Rule Example 2: Route based on a header value The following router rule script routes messages based on the value of a header in the message. If the X-My-Header header is set to "value", the rule evaluates to true. headers['X-My-Header'] == "value" |
Import Router Rule | Import individual router rules and all of the components used in the rule. |
Export Router Rule | Export individual router rules, all of the components used in the rule, and document types used by the components.
|
Flows tab | Displays all the integrations and integration flows that use this router. Double-select a flow to view its details. |
Options tab | |
Log Message Headers | You can log the message headers of the message for any events that the router logs. If yes, you can enter an optional "Include Headers" regular expression to specify which headers to include in the flow run event. All headers are logged if you don't provide the regular expression. NoteLogging message headers can be helpful in troubleshooting, but be aware that this can expose sensitive information in the flow run events. |
Create an Error router
An error router is a custom error handler that you can create to handle errors in a message flow. Error Routers enable you to script routing rules and flows of components that further process the error.
Like content based routers, error routers route messages by evaluating router rules. Router rules are Groovy scripts that evaluate to true or false.
Router rules have available to them the following variables:
Header - A map of the headers that are available in the message. Headers are key-value pairs that are set by components in the message flow. Headers can store information about the message that's being processed, such as the message type, the sender, the receiver, and the document type. Headers also include an `error` property that contains the error object that was thrown when the error occurred.
Body - The message payload that's being processed.
The message body (`body`) is passed to the error router, and the rules depend on the type of error. If the error includes a response body, as with HTTP errors, the response body is set as the message body and is available to the error router rules as the `body` variable. Otherwise, the message body is set to the document that was sent to the component that threw the error. In either case, the payload is wrapped in an X1 envelope.
If the message body is set to the response body of the error (as is the case with HTTP errors), the original document is made available in the `original_document` message header. This allows you to access the original document that was being processed when the error occurred.
Refer to the table below for guidance after you've completed the initial steps in the Create a router procedure above.
Field and tab | Description |
|---|---|
ID | The ID that X1 automatically assigned to the router, based on the name. The ID is lowercase and replaces spaces with dashes. The ID is permanent and can't be edited. |
Type | The type you assigned to the router when you created it. The type is permanent and can't be edited. |
Name | The name you assigned to the router when you created it. |
Adapter | The adapter you assigned to the router when you created it. |
Request Document Type | The request document type you assigned to the router when you created it. |
Response Document Type | The response document type you assigned to the router when you created it. |
Rules tab | Displays all the rules for this router. Double-select a rule to view its details. Router rule scripts are executed against the message body and have available the body and headers variables. The body variable contains the message body, and the headers variable contains the message headers. Normally, the body consists of an X1 envelope, which contains a document and a header. |
Add Router Rule | Displays the Flow Designer for the router rule where you can specify a rule name. Approve the draft for the changes to take effect. Each router must have a default rule that's executed if no other rule evaluates to true. The default rule is a special rule that's always evaluated last. It doesn't have a condition, but it does have a flow of components to execute if no other rule evaluates to true. There can be only one default rule for a router. Router Rule Scripts Router rule scripts are written in Groovy and return a boolean value. If the script returns true, the rule passes. If the script returns false, the rule fails. Here are some examples: Router Rule Example 1: Route based on a document property The following router rule script routes messages based on the value of a property in the message body. If the scac property in the message body is either "CNWY" or "XPOL", the rule evaluates to true. body.document.scac == "CNWY" || body.document.scac == "XPOL" Router Rule Example 2: Route based on a header value The following router rule script routes messages based on the value of a header in the message. If the X-My-Header header is set to "value", the rule evaluates to true. headers['X-My-Header'] == "value" |
Import Router Rule | Import individual router rules and all of the components used in the rule. |
Export Router Rule | Export individual router rules, all of the components used in the rule, and document types used by the components.
|
Implementing Components tab | Displays all the integrations and integration flows that use this router. Double-select a flow to view its details. |
Options tab | |
Log Message Headers | You can log the message headers of the message for any events that the router logs. If yes, you can enter an optional "Include Headers" regular expression to specify which headers to include in the flow run event. All headers are logged if you don't provide the regular expression. NoteLogging message headers can be helpful in troubleshooting, but be aware that this can expose sensitive information in the flow run events. |
Payload tab | |
Is Unwrap? | If Yes, a message that X1 sends to an external system is unwrapped from its envelope. |
In the Routers table, do one of the following:
Next to a router, select
. The Router Details page displays the Rules tab by default.Select a router's ID, Name, or Type. The Router Details page displays the Rules tab by default.
In the top right corner of the page, select New Draft.
Note
If you want to delete the draft before saving it, select
.Edit the router information.
In the top right corner of the page, select Save > Approve.
Note
When you select Save, your edits are saved as an unapproved draft.
At this point, you can leave the saved draft unapproved if you want to come back to it later to do more editing.
When you want to edit the component again, in the top right corner of the page, select Show Draft to access its unapproved draft.
When you select Approve, the unapproved draft is deployed as the current version.
In the top right corner of the page, you can select the drop-down arrow to revert to a previous version.
To the left of the drop-down list, you can select
to view when the page was last modified.
Next to a router, select
. The Confirm Export dialog box displays.Select Yes.
In the Routers table, do one of the following:
Next to a router, select
. The Router Details page displays the Rules tab by default.Select a router's ID, Name, or Type. The Router Details page displays the Rules tab by default.
In the top right corner of the page, select Restart. The Confirm Restart dialog box displays.
Select Yes.
Next to a router, select
. The Delete Router dialog box displays.Select Delete.