Skip to content

Routing Rules and Addresses

Message routing describes queuing and dispatching to different targets a message from/to IFS Cloud. 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.

Note: This version of IFS Application is supplied with a new Router implementation. Read more about that below.

Understanding Inbound routing

  • Inbound routing is the identification of the incoming messages by using 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.
  • 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 typically based on XML nodes in the header, but it is also possible to use nodes from the document body.
  • There are two supported SOAP envelopes: SOAP_IFS and SOAP_SIMPLE.

Note: You may use any other envelope that is defined in the IFS 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 XML element name or an XML element attribute name.
  • Messages recognized as text can also be content routed, but routing such messages on content is much simpler and not that effective as routing of XML.
  • You can also use location based conditions in inbound routing. You can use the following conditions (see more in section Address databelow):

    • File Reader instance name and File Name for File Reader messages
    • FTP Reader instance name and File Path for FTP reader messages
    • SFTP Reader instance name and File Path for SFTP reader messages
    • Mail Reader instance name and Subject for Mail Reader
  • Location based conditions can also be used for Custom Readers. It will be Reader instance name and custom defined selector then.

  • An inbound message is normally routed to a REST API or a PL/SQL method 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.

Routing parameters when using SOAP_IFS XML

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

  • fndcn:TypeType of the message
  • fndcn:FunctionMessage Function
  • fndcn:SenderThe sender of the message
  • fndcn:ReceiverThe receiver of the message

Example of routing from SOAP_IFS

Routing parameters when using UNKNOWN_XML

UNKNOWN_XML is the whole 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 the whole inbound string or binary content that is not recognized as valid XML. Content based routing is not performed for binary data. If the data is any type of text, routing parameters are search strings that can be located anywhere in the incoming data.

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 by choosing a value in Location Type drop-down list:

  • File
    • File Reader
      The instance name of the File Reader by which the file was read.
    • Filename
      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
  • Sftp
    • Sftp Reader
      Instance name of the SFTP Reader that was used to get the file.
    • File Path
      File location in the SFTP Server
  • Mail
    • Mail Reader
      Instance name of the Mail reader that was used to get the message.
    • 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*.

      Note: The length of the mail subject should be less than 200 characters.

  • Custom (if present)
    • Reader
      The instance name of the custom reader that read the incoming message.
    • Selector
      Custom reader specific selector string.

Understanding Outbound routing

Outbound Routing Rules with value APPLICATION_MESSAGE in the Route From field are used for routing of outbound messages.

Routing of outbound messages is performed in two phases:

  • pre-routing at the database site
  • content based routing performed by application server

Pre-routing at the database site

The pre-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: Any arbitary name can be used for the purpose of routing
  • 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 other conditions on the rule that are not possible to check at this stage. See more details about pre-routing phase.

The mentioned fields are created differently depending on use of PL/SQL Access Provider. See more details in the two sections below.

Routing Parameters when Using PL/SQL Access Provider

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

  • MESSAGE_TYPE - Defaults to CONNECT
  • MESSAGE_FUNCTION - The input parameter message_function_
  • SENDER - The input parameter sender_
  • RECEIVER - The input parameter receiver_

Example of outbound routing when using PLSQL Access Provider

Limitations

Because of the double routing mechanism there are some limitations. Read more about routing of outbound messages.

Simplified Routing

Standard routing is a very powerful mechanism, but can be quite heavy and take time, especially in an installation with many message queues and/or many routing rules. This is because every rule has to be matched against the message. In many cases the flexibility of the standard routing is unnecessary and can be replaced with a simplified, "light", algorithm, which is very quick.

Simplified Routing can be enabled for inbound and outbound messages independently. For inbound messages only messages of type SOAP_IFS  (Route From field in Routing Rule definition) can be routed using the simplified routing. For outbound messages the type must be APPLICATION_MESSAGE.

Simplified routing uses one of the four message attributes: MESSAGE_TYPE, MESSAGE_FUNCTION, SENDER or RECEIVER.

To enable Simplified Routing go to Setup IFS Connect feature of IFS Solution Manager, choose Routing, then the appropriate type of message you want enable Simplified Routing for (INBOUND or OUTBOUND) and choose the attribute you want to use for Simplified Routing:

For inbound messages the attribute will be matched against the corresponding SOAP_IFS header parameter: fndcn:Type, fndcn:Function, fndcn:Sender or fndcn:Receiver. For outbound messages it will be the value of the corresponding attribute of the Application Message.

During the server startup all routing rules of the particular type having the chosen parameter defined as Content based condition with operation equals will be loaded to a map in the memory with the attribute value as a key.

Example rule configuration with SENDER attribute for inbound and RECEIVER for outbound messages.

On arrival the message is checked for existence of the defined attribute. If the attribute exists, the algorithm just makes a simple look up in the map with the attribute value as a key, which will typically result in one or maybe a couple of rules only. If the attribute value is not present in the map, i.e. there are no rules with appropriate Content based definition, or attribute doesn't exist in the message, the standard routing will be used instead.

Note that the map can return a rule (or a collection of rules) that have additional conditions, which are not satisfying the message. The message will then fail with error saying that no matching rules have been found, even if there can exist other rules, not used by the simplified algorithm, matching the message. Standard routing will not be used in such case.

Example

A central onshore site is configured to communicate with a number of offshore sites, each of them containing a copy of the central database. Information is replicated using IFS Connect with simplified routing.

Each site has it's own ID on form " S*<nn> ", where "<nn>" represents a two-digits site number, e.g. " S25 ". Each time an offshore site is sending a message with updated information, it is setting it's ID in the Sender* header field of the IFS_SOAP message.

The onshore site wants to have a separate Routing Rule for each offshore site, thus the configuration contains as many routing rules as there are offshore sites with the offshore site's ID specified as a Content based condition, e.g. for site 25: Search: fndcn:Sender, Op: equals, Match: S25.

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 that 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 is used, it will generate an xml file that includes the raw data extracted by the RDF file (pl/sql code that is specific to the report). The SEND_FULL_XML_TO_CONNECT logical printer will generate an xml file with all translated data and some framework added data. The SEND_PDF_TO_CONNECT logical printer generates the same pdf file that is used in previewing and printing.

In routing term 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 when 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 Application 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 the same report is ordered over and over again.

Example of report routing to an outbound PDF file

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 Destination Address

Node Solution Manager/Integration/IFS Connect/Routing Addresses will list all available destination addresses.

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

  • Transport Connector
    Define the connector to use. The available types are REST API, PL/SQL, File, Ftp, Http, JMS, Mail and Sftp. Also custom types (Custom Senders) will be available here, if present.
  • Address Name
    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.

Format

The in and outgoing files can be adjusted to this settings.
  • Envelope
    SOAP_IFS and SOAP_SIMPLE are implemented as part of the standard. It is possible to create your own envelope standards and define them in the IFS Connect configuration. They will be available in the drop down list then.

    Select the xml envelope that the message will be placed in. Envelopes are stored in the database and are administrated in the Setup IFS Connect form. Blank or None designates that no enveloping is to be performed, the message will be sent without an envelope. Read more about envelope configuration.
  • Encoding
    Gives the possibility to change the default encoding UTF-8.
  • Compress
    Message will be sent in compress data mode if the check-box is ticked.
  • Envelope Response
    If ticked and the response is not binary it will be encapsulated within a SOAP envelope. The envelope definition used here will be taken form the detected Request Envelope the incoming message is enveloped in. If the Request Envelope is of type UNKNOWN_XML or NONE_XML it will be just a simple SOAP envelope.

  • Transformers
    List of transformers for transforming the message with an xslt or java transformer, e.g. go from xCBL to IFS XML.

  • Response Transformers
    Transform the response message before returning (synchronous messages or address chaining).

Note: Transformers can be set up in a flow, e.g. first transformer for preprocessing (e.g. removing namespace), second transformer for the next stage and so on.

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

Note: Binary data can only be transformed using binary Java transformers.

Reade more about processing of a single address.

Advanced

This will open the Channel Address Data form.



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

Address data

The Address Data step of the Address Creation Wizard enables to to enter the destination address. The content of this part will depend on the Address Type.

  • Projection
    • Projection:Method
      Choose the Integration projection method to be invoked.

Note: Projection sender can be used to invoke an Unbound Action/Function of an Integration Projection. The input parameter of this action/function should be a structure.Return type of this action/function can be any Odata accepted data type.

Note: Projection Sender only accepts inputs in json format. When sending input in xml format, input xml should be transformed to a valid Json format.

  • PL/SQL
    • Package.Method
      - Choose a PL/SQL method that has to be invoked.

Note: The given PL/SQL method has to be defined as function taking CLOB as input argument and returning CLOB, e.g.:
FUNCTION Plsql_Address_Test (xml_ CLOB) RETURN CLOB;
The returned value can be null.

Note: PL/SQL methods are executed in separate thread using concept of Work Managers.

  • File
    • File Sender
      Choose sender instance from the drop-down list.
    • Output File
      Path to the output file. You can use a number of placeholders in the path specification.

      Note: %FILE_OUT% placeholder can not be used in Output File field since it will be automatically fetched from FILE SENDER configurations.

  • Ftp
    • Ftp Sender
      Choose sender instance from the drop-down list.
    • Directory
      Destination directory (OUT) at the FTP server to write the file to.
    • Output file name
      Name of the output file. The name can contain placeholders.
  • Http
    • Http Sender
      Choose sender instance from the drop-down list.
    • URL
      URL to the remote system the sender is supposed to access. You can use a number of placeholders in the URL specification, typically in the query string.
    • SOAP Action
      Value of the SOAPAction http header parameter, if required.
    • Login
      Username required by the remote system.
    • Password
      Password for the given username.
    • Additional Header Parameters
      If necessary it is possible to specify additional parameters that will be sent in the http header. Specify the parameters on form <parameter>=<value>, one parameter definition per line. You can use a number of placeholders in the header parameter specification, both in parameter name and value.

      HTTPs considerations

      If the used protocol is HTTPS (HTTP over SSL) it is also possible to specify here parameters defining key stores. Those parameters will change the behavior of the the sender and will not be added as HTTP header parameters. All those parameters must start with prefix ssl:.

      Following SSL parameters are currently supported:
      • ssl:TrustStoreFile - path to external trust store
      • ssl:TrustStorePwd - external trust store password
      • ssl:TrustStoreType - type of the external trust store, default is JKS
      • ssl:KeyStoreId - ID of keystore with client certificate
      • ssl:KeyStoreFile - path to external client keystore
      • ssl:KeyStorePwd - external client keystore password
      • ssl:KeyStoreType - type of the external client keystore, default is PKCS12

By default the HTTP Sender will use the Java default trust store, i.e. keystore with trusted certificates (see also Configure HTTP Sender for SSL), so normally you don't need to specify any external trust store.

Mutual Authentication

Some HTTPS servers may require the client (i.e. HTTP Sender) to present themselves with own certificate. If the URL above points to this type of server you have to supply the HTTP Sender with a keysore containing your client certificate.
If not already done, import your certificate to IFS Cloud using the Keystores feature in Solution Manager. Note that the certificate has to be stored with Keystore ID, not as User Certificate (User Name will be '*').
Then specify the keystore ID using the parameter ssl:KeyStoreId. If using this parameter you don't need to specify any external client key store.

Note: As passwords to external key stores are given in clear text, all above specified ssl options, except ssl:KeyStoreId, shouldn't be used in a production environment. With other words the only option that may be used in production, when server requires mutual authentication, is ssl:KeyStoreId.

  • Mail
    • Mail Sender Choose sender instance from the drop-down list.
    • To
      The receivers email-address.
    • Cc
      Carbon copy (CC) address.
    • Subject
      Mail subject
    • Attachment Name
      Optional default attachment name. Can be used if the system will not be possible to decide the name. The name can contain placeholders.
  • Sftp
    • Sender Instance
      Choose sender instance from the drop-down list.
    • Output file
      Name of the output file. The name can contain placeholders.
    • Directory
      Destination directory (OUT) at the SFTP server to write the file to.
  • REST
    • Sender Instance
      Choose sender instance from the drop-down list.
    • Rest Root End Point
      The root URL of the REST service must be given here. The exact URL of the REST service is composed using this root URL and the place holders written into this URL. Each place holder must be written within a pair of curly brackets e.g.: {parameter1}. The place holders can be anywhere in the URL. The values for the place holders must be supplied from the PL/SQL business logic using the REST_Sender_API. The URL can also contain query parameters. These can be supplied as parameters added to the root URL or it is also possible to supply the query parameters separately using the REST_Sender_API. For more details please follow this link >>.
    • Authentication Method
      Choose the authentication scheme required by the REST service. The supported authentication schemes are Basic, Bearer and Azure Shared Key..
    • Additional Header Parameters
      Header parameters that would be set to the HTTP request header can be set here. Enter the parameters in the form <parameter>=<value>. Enter one such parameter per line. The header parameter and value can be defined using place holders. The value that should be entered for the place holder has to be supplied from the PL/SQL business logic using the REST_Sender-API. It is also possible to specify HTTP header parameters straight away using the REST_Sender_API as well. More information is available here >>.
  • Custom Sender
    If you have custom senders in your system the choice will be available.


    • Instance Type
      Choose connector instance type from the drop-down list.
    • Upload File
      Upload the developed custom connector project.
    • Add Parameters
      Connector specific parameters with their values.

Placeholders

In those cases the file path or name is given it is possible to use placeholders on form %<PLACEHOLDER>%. Those are as follow (if not explicitly specified placeholder can be used by all File, Ftp, Sftp and Mail readers):

  • FILE_OUT
    Used by File Reader to determinate the output directory.
  • EXTENSION
    Used by Mail Reader to determinate attachments file extension based on the data type.
  • GUID
    Generated GUID.
  • DATE_ID
    Current time in milliseconds since midnight, January 1, 1970 UTC, represented as long number.
  • TIMESTAMP
    Current time in milliseconds since midnight, January 1, 1970 UTC, represented as string on form yyyyMMdd_HHmmss_z.

Following placeholders correspond to values of view attributes with the same names taken from the current Application Message:

  • MESSAGE_FUNCTION
  • MESSAGE_TYPE
  • SENDER
  • RECEIVER
  • SEQ_NO
    Will default to 0 if not found.
  • TAG=<attrribute_name>
    Value of the attribute/tag given by its name as <attribute_name>. The attribute is searched first in the current Application Message, then, if not found, in the output document after transformation and finally, if still not found, in the input document.

The list of available placeholders is also shown in a tool tip message for respective field.

How to create Routing Rule

If you select the node Solution Manager/Integration/IFS Connect/Routing Rules you can see a list of available rules. When you select the tab Inbound all available inbound rules will be listed. Tab Outbound will list all available outbound rules. On each rule you can select Show Details in the context menu to see the details of the selected rule.

To create a new rule select correct tab (Inbound or Outbound) and press Add button Create New. This will open assistance to create the ew Rule. Set values there as required and press Finish button to add the new rule.


Inbound Routing Rule example. The only difference between Inbound and Outbound Routing Rule form is the lack of section for Location based conditions in the second one.

  • Route From

The identification of an inbound message is done by looking at the attribute value of a node of an xml file or any string in a non xml file. The Route From defines the format of the file i.e. whether the file is an xml file, xml file with an envelop or non xml file. The default values in the drop down are

NONE\_XML - the message is identified by a string in the file, if not binary (no content based routing can be performed for binary messages).
- UNKNOWN\_XML - the message is identified by one or several xml nodes in a file that lacks an envelope.
- SOAP\_IFS - the message is identified according to the content of the IFS defined soap envelope.
- SOAP\_SIMPLE
- Additional SOAP envelopes that can be defined in the system. You may use any other envelop that is defined in the [IFS Connect configuration](../010_configure_connect/065_envelopes/index.md).


​ For outbound message 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. ​ - REPORT - used for routing the Report Designer type reports.

  • Rule Name
    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 destination addresses are called directly (synchronously). If a queue is specified, the addresses are executed asynchronously in background (by Batch Processor).
  • Enabled
    Defines whether the rule is Enabled or Disabled.
  • Customized Defines if the rule has been customized or not.

Location based conditions (inbound only)

Defines routing parameters on the values provided from the different transport connectors, e.g. file name given by the file connector, mail subject etc. See Routing from Name or Location for location base routing parameters.

Addresses

Shows a list of all Destination Addresses grouped in [address chain links](../../../../040_tailoring/300_extensibility/240_integration/060_connect/message_routing/index.md#routing-address-chaining). A Destination Address defines a destination where the message is to be sent if all of the the conditions match.

To add or remove one or more addresses to/from you rule click on the Destination Address link.

The click event will popup a dialog box with list of all available destination addresses. Just check/uncheck the check box next to address you want to add/remove to/from your rule. Addresses already present on the rule are default checked when the dialogue box pops up. Press OK when done.

Assign proper address chain link number to each address by editing in the Chain Link No column.

Example of address chain with three chain links (address groups):

  1. Incoming message is sent to Projection method.
  2. Result from call to Projection method is then sent to the Main Address.
  3. Result from call to the mail is then written to a file.

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

Routing examples

  • Routing of inbound SOAP_IFS.xml
  • Routing of inbound UNKNOWN_XML
  • Routing of NONE_XML
  • Routing of outbound message when use of PLSQL Access Provider
  • Routing of Report to an outbound PDF file
  • Destination address of a Report Designer type Report Rule

Routing of inbound SOAP_IFS xml

Routing of inbound UNKOWN_XML

Routing of inbound NONE_XML

Routing of outbound message when using PLSQL Access Provider

Routing of Report to an outbound pdf file

Destination address of a Report Designer type Report Rule