Message Routing

Message routing describes queuing and dispatching to different targets a message from/to IFS Applications. This will be based on the message type and/or the content of the message. This page describes the different ways a message may be routed and how to configure message routing rules and addresses.

About Message Routing
Understanding Inbound routing
Understanding Outbound routing
Understanding routing rules for Reports
How to create a destination address
How to create an inbound routing rule
How to create an outbound routing rule
How to test destination addresses and route rules
Examples

Understanding Inbound routing

Inbound routing is the identification of the incoming messages by using either content based conditions and/or location based conditions and routing the message to the correct destination(s).
For inbound messages, the use of an envelope is recommended for performance reasons.
The principle of an envelope is that a separate header contains address information and a second part, the body, contains the data.
Routing parameters for inbound messages with envelopes are always based on XML nodes in the header.
There are two supported SOAP envelopes: SOAP_IFS and SOAP_SIMPLE.

Note: You may use any other envelope that is defined in the connect configuration.

XML messages that don't have a known envelope type are classified as UNKNOWN_XML.
Messages that don't contain valid XML are classified as NONE_XML.
Content based condition can be an element name or an attribute name in the header of the message.
You can also use location based conditions in inbound routing. You can use the following conditions:
- File Reader instance name and File Name for File Reader messages
- FTP Reader instance name and File Path for FTP reader messages
- Url and query string value for Name for Http
- Mail address and Subject for Mail Reader
- MQSeries Reader instance name and Queue for MQSeries messages

An inbound XML message is normally routed to a BizApi but can also be routed to Transport Connectors, e.g. to the File Transport Connector for archiving a copy of a transformed file in a specific folder.
A flag Store in original format will control if the message is stored in original format or not.
If this flag is false then will the message be transformed before the store to the queue.
This will be useful when inbound message is NONE_XML and it must be stored in XML format for editing purposes.

Routing parameters when using SOAP_IFS XML

Routing parameters are always located in the SOAP header and it's recommended to use :

fndcn:Type Type of the message
fndcn:Function Message Function (normally the BizApi name)
fndcn:Sender The sender of the message
fndcn:Receiver The receiver of the message

Example of routing from SOAP_IFS

Routing parameters when using UNKNOWN_XML

UNKNOWN_XML is all inbound XML strings that can't be recognized by IFS Connect as having a known envelope. Routing parameters can be located in any element or attribute in the XML string.

Example of routing from UNKNOWN_XML

Routing parameters when using NONE_XML

NONE_XML is all inbound strings that are not recognized as valid XML. Routing parameters are search strings that can be located anywhere in the incoming string.

Note: This should only be used when a java-transformer is implemented (Transformation must be done from the incoming format to IFS XML).

Example of routing from NONE_XML

Routing from Name or Location

The location based routing uses Name and Location parameters with information provided by the different Transport Connectors. This type of routing is very useful when there is no way to solely use the content for uniquely identifying a message. Please notice that these routing parameters only apply to the Connector that is receiving the message. A file Name parameter is for example ignored if the message is received as a mail.

The following rules can be used:

File

File Reader - The instance name of the File Reader by which the file was read.
File Name - The name of the file, one wild card '*' could be used in the file name, some examples, *.xml, test.*, test*.xml but not *test*.xml.

FTP

FTP Reader - Instance name of the FTP Reader that was used to get the file.
File Path - File location in the FTP Server

Mail

Mail Address - The inbox that the Mail reader is reading from, example someone@company.com
Subject - The subject of the email, one wild card '*' could be used in the subject name, some examples if the subject is Test, Tes*, *est but not *es*.

Http

Url - The URL of the http listener, http://host/ifs/webServices
Name - A parameter named NAME could be added to the URL http://host/ifs/webServices?NAME=Test, in this case NAME = Test, only an exact match is valid, no wild cards are accepted.

MQSeries

MQSeries Reader - The instance name of the MQSeries reader that read the incoming message.
Queue - The name of the queue, MyQueue

Understanding Outbound routing

Routing of outbound messages is performed in two steps:

simplified routing at the database site
content based routing performed by application server

Simplified routing at the database site

The routing is performed in the PL/SQL code. The only goal of this stage is to find out the name of the queue the message should be put into. At this point only the following application message header fields are used:

MESSAGE_TYPE : The type of the message
MESSAGE_FUNCTION : Normally the BizApi name
SENDER : The sender of the message
RECEIVER : The receiver of the message

The algorithm is trying to find a rule that matches most conditions, even if there are conditions on the rule that are not satisfied. If any rule can not be found at this point or the found rule doesn’t define any queue, the message will be placed in the default ‘OUT1’ queue

Note: When routing monitoring messages of the connect framework (J2EE server) and the batch server only the first three parameters are used.

The mentioned fields are created differently depending on use of PLSQL Access Provider or use of existing messages in the Connectivity outbox. See more details in the two sections below.

Routing Parameters when Using PLSQL Access Provider

The routing parameters are created in the call to Post_Outbound_BizAPI with the following mapping.

MESSAGE_TYPE - Is fixed to CONNECT
MESSAGE_FUNCTION - The input parameter bizapi_name
SENDER - The input parameter sender_
RECEIVER - The input parameter receiver_

Example of outbound routing when using PLSQL Access Provider

Routing Parameters when Using Existing Messages in Connectivity Outbox

Examples of this are Internet Transaction Services (ITS) that publish existing IFS Applications EDI messages to XML.
The routing parameters are fetched from the Connectivity outbox header with the following mappings.

MESSAGE_TYPE - Media_Code from the Connectivity header eg INET_TRANS
MESSAGE_FUNCTION - The BizApi Name
SENDER - Sender from the Connectivity header
RECEIVER - Receiver from the Connectivity header

Note: The connection between Class_Id and BizApi name is done in background job definition

Example of outbound routing for Internet Transaction Services.

Content based routing performed by application server

The content based routing will take place after the message has been executed. The data for routing is parsed in the following order:

application message attributes
XML document with output data from the BizAPI execution
XML document with the BizAPI’s input data

When parsing application message all existing simple attributes, i.e. neither aggregates nor arrays, are taken with exception of the OBJ_VERSION attribute.

Content based conditions are used only once, i.e. only the first occurrence of an attribute or element (XML tag) matching a given condition in all three data sources will be taken. And this is independently if the condition will be satisfied or not. Therefore it is not recommended to use elements that can occur in more then one data source. The similar is valid if there are several occurrences of the same element in one data source.

If there are nested elements matching the same condition in an XML document, the most inner one will be taken. But if a condition defines an XML tag attribute, for nested tags matching the same condition the most outer one will be taken instead.

Limitations

Because of the double routing mechanism there is a limitation. The rule chosen in the first step will be not necessary the same as the one chosen for the final routing in the second step. The first one does not necessary fully satisfy the source. There will be no problem as long as both rules are defined for the same queue.

Understanding routing rules for Reports

Outbound routing rules that has the value REPORT as Route From field will be used in routing the Report Designer type reports. There are three main attributes which can be used on routing an ordered Report Designer type report data.

MESSAGE_TYPE
MESSAGE_FUNCTION
SENDER

MESSAGE_TYPE

Message Type define the content of the data that is generated. The content will vary with the logical printer that will be used in ordering the report. There are three main type of logical printers

SEND_XML_TO_CONNECT
SEND_FULL_XML_TO_CONNECT
SEND_PDF_TO_CONNECT

When the SEND_XML_TO_CONNECT logical printer use, it will generate a xml file that include the raw data extracted by the RDF file (plsql code that is specific to the report). The SEND_FULL_XML_TO_CONNECT logical printer will generate a xml file with all translated data and some framework added data. The SEND_PDF_TO_CONNECT logical printer generate the same pdf file that is used in previewing and printing.

In routing them you can use the logical printer name as the content based condition to separately identify the content type.

Example of routing a full xml file.

MESSAGE_FUNCTION

There is a unique id for each and every report which is an UPPERCASE name ending with _REP (e.g. PURCHASE_ORDER_PRINT_REP). You can use this report id in routing the report. For this you have to define the routing rule with MESSAGE_FUNCTION equals to the report id.

SENDER

When a report is sent to connect its result key will be set in the Sender field of the message. So you can use a routing rule that looks for the SENDER of a given value in routing. The result key is a unique number when a new report is generated. It has the same value when one orders the same report over and over again.

Destination Address when Routing Report Designer type Reports

In general the destination address contains a separate section to be used in formatting the in and out going messages. This section describes the attributes like Envelope, Encoding and Transformers. To keep the original format of the PDF files that are routing, the destination address should not have any of the above format attributes. Otherwise it will affect the file format of the original PDF file and the end result may be a corrupted file.

Destination address of a Report Designer type Report Rule

How to create a destination address

Node Routing Addresses under Configuration/Integration of IFS Solution Manager will list all available destination addresses.

You can create a new address or edit an existing address from here. Click Create New to create a new destination address. You can set the destination parameter values there.

Destination Type:
Define the connector to use. The available types are BizAPI, File, Ftp, Http, MQSeries, Mail, SMS, ShellCommand, SocketMessage and WindowsPopup.
Description:
Description of the address.

Note: It's important to give the destination a unique description so you can see what it is. Many destinations may be defined in an operational system and this method of documenting them is very important.

Address data

The right hand side of the window enable you to enter the destination address. The content of this part will depend on the Destination Type.
BizApi: interface and operation
File: File Sender Instance, File path
FTP: Sender Instance, FTP Directory connect to and the output file name
Http: Sender Instance, Url, SOAP Action, Authentication parameters and any header parameters e.g authentication parameters in base64 encoding, SOAP action etc.
MQSeries: Instance and the Queue Name
Mail: Sender Instance, the receivers email-address, carbon copy and name of attachment.
SMS: Sender Instance, the phone number where the message will be sent
Shell Command: Sender Instance, the command to be executed, the input filename and the response from the called function or program in the outfile name.
SocketMessage: Sender Instance, Hostname and the port number where the message will be sent.
WindowsPopup: Sender Instance, Host name where the net message send.

Above example shows the address data for the BizAPI connector.

Note: When the Destination Type is BizApi the BizApi Address has an LOV containing all BizApi's installed in the application server. It is possible to call other interfaces in the application server. Enter the operation in the format <handler>:<operation>. The BizApi LOAD_INBOX_MESSAGES in the 2004 release has been removed but the functionality is still present. Enter the operation ConnectivityProcessingHandler:LoadInboxMessage.

Format

The in and outgoing files can be adjusted to this settings.

Envelope:
SOAP_IFS and SOAP_SIMPLE is implemented as part of the standard. It is possible to create your own envelope standards and define then in the connect configuration. Then they will be available in the drop down list.

Select the xml envelope that the message will be placed in. Envelopes are stored in the database and are administrated in the F1 Configuration. Blank or None designates that no enveloping is to be performed, the message will be sent without an envelope.
e.g. SOAF_IFS envelope
Encoding:
Gives the possibility to change the default encoding UTF-8.
Transformer1:
For transforming the message with a xslt- or java transformer, e.g. go from xCBL to IFS XML.
Transformer2:
For transforming the message with a xslt- or java transformer

Note: Transformer1 and transformer2 can be set up in flow.
E.g transformer 1 for preprocessing (removing namespace) and transformer 2 for the final stage.

Response Transformer1:
Transform the response message when synchronous messaging is considered.
Response Transformer2:
Transform the response message when synchronous messaging is considered.

Note: Transformers are stored in the database and are administrated in the Connect configuration tool. Blank or None designates that no transformation is to be performed.

Compress:
Message will send in compress data mode if the Compress is checked.

Advanced

This will open the Channel Address Data form.

These are some optional attributes which can be used when messages send use some customized envelops.

How to create an inbound routing rule

Select the node Routing Rules under IFS Solution Manager/Configuration/Integration you can see a list of available rules. When you select the tab InBound all available inbound rules will be listed. On each rule select Show Details in the context menu to see the detail of the selected rule.

To create a new inbound rule select tab InBound and press feature toolbar button Create New. This will open up a detail form of a new rule with some default values. Set values there as required and press Save button to add the new rule.

Route From:

The identification of the message is done by looking at a attribute value of a node of a xml file or any string in a non xml file. The route from define the format of the file ie. whether a xml file, xml file with an envelop or non xml file. The default values in the drop down are

SOAP_IFS , the message is identified according to the content of the IFS defined soap envelope.

SOAP_SIMPLE,

SOAP_EPAGES,

UNKNOWN_XML, the message is identified by one or several xml-nodes in a file that lacks an envelope.

NONE_XML, the message is identified by a string in the file.

You may use any other envelop that is defined in the connect configuration.

Description:
Describes the rule.

Note: It's important to give the rule a unique description so you can see what it is. Many rules may be defined in an operational system and this method of documenting them is very important.

Queue:
Defines whether the message should be queued or not. If no queue is specified, the BizApi is called direct (synchronously). If a queue is specified, the BizApi is executed asynchronously by a background process (BatchServer).
Store in Original Format:
Will control if the message is stored in original format or not.
If this flag is false then will the message be transformed before the store to the queue.
This will be useful when inbound message is NONE_XML and it must be stored in XML format for editing purposes.
If no editing requirements as above it's recommended to set this to true.
Enabled:
Defines whether the rule is Enable or Disable.

Location based conditions

Defines routing parameters on the values provided from the different transport connectors, e.g. file name given by the file connector, the url from the Http connector etc. See Inbound Routing for location base routing parametres.

Content based conditions

Defines the search paths in the inbound message. See Inbound Routing about the routing parameters.

Addresses

Destination Address:
The destination(s) where the message is to be sent if any of the the conditions match.
Asynchronus Response Address:
Defines addresses to which any response should be sent in asynchrounus routing.

Note: By clicking on the link Destination Address or Asynchronus Response Address you can add/remove the Addresses link to the routing rule. The click event will pop up a dialogue box with list of all destination addresses available and by checking/unchecking the check box you can add/remove an address to/from a rule. The already selected addresses are default checked when the dialogue box popup.

How to create an outbound routing rule

Tab OutBound in the above route condition list feature will list all available outbound rules. To create a new outbound rule select the tab OutBound and press Create New.

Route From:

Distinguish from where the message is sent. The options in the list of values are:

APPLICATION_MESSAGE - the message is from IFS Application and is concerning for a business flow. Normally a message produced by a BizApi

REPORT -

Description:
Describes the rule.

Note: It's important to give the rule a unique description so you can see what it is. Many rules may be defined in an operational system and this method of documenting them is very important.

Queue:
Defines whether the message should be queued or not. If no queue is specified, the message destination(s) is called direct (synchronously). If a queue is specified, the message destination(s) is executed asynchronously by a background process (BatchServer).
Enable:
Defines whether the rule is Enable or Disable.

Content based conditions

Defines the search paths in the outbound message-header. See Outbound Routing about the routing parameters.

Addresses

Destination Address:
The destination(s) where the message is to be sent if any of the conditions match.
Asynchronous Response Address:
Defines addresses to which any response should be sent in asynchronous routing.

How to test destination addresses and route rules

With the message routing client, you can test route rules and destination addresses.

Test a destination address

All destination addresses other than Bizapi addresses can be tested in the detail window. Open an address and click Test toolbar button to open a test window.

Type a message or load from a file and press Send. The result status will be displayed in the bottom window.

Test an Inbound Routing Rule

Open an inbound routing rule and click Test Content Condition.

This will open an Open File Dialog to select the input message for the route rule. When a file is selected, it will be matched with the current routing rule. The result will be displayed in separate window. This functionality can be used to check whether a particular message matches a selected inbound routing rule.

Note: This test functionality doesn't match location based conditions.

Check matching Routing Rules for a message

In the overview form of Inbound/Outbound routing rules you can check whether a message matches any rule available in the system. Click Test Rules toolbar button. This will open a separate test window.

For inbound rules:

For outbound rules:

Enter the necessary details values and click Get Matching Rules. The result will be displayed in the bottom pane. If there are more than one matching rule, the selected rule will be highlighted in boldface.