Message Processor

Message Processor can be described as a kernel of the IFS Connect framework. It is responsible for processing of all Application Messages.

Contents

• General
• Application Message Flow
• States
• Execution Steps
• Address Processing
• Actions on Application Message
• Message Bodies
• Transaction isolation

General

Message Processor is a central part of the IFS Connect framework responsible for processing of Application Messages.
The process can involve both synchronous calls and background processing of messages, both inbound and outbound. Message Processor can be called from Batch Processor, Connect Reader framework and SOAP Gateway.

Message Processor will route the incoming application message if not already routed. A message is assumed to be routed if there are address lines on it. Message Processor will execute an outbound BizAPI, if defined, and process all address lines.

Application Message Flow

A new Application Message is created with state ‘Released’. As soon as the message has been picked up for processing the state is changed to 'Processing'. It can be done by the Message Processor, but for outbound messages created in an In-Parallel queue the state is changed already in the PL/SQL logic. Message Processor will only process messages in 'Released' or 'Processing' state.
A successfully executed message will get its state changed to 'Finished' (or ‘Waiting’ for scheduled job – see Scheduled Tasks). All address lines on such message will then get state 'Transferred'.

Execution of an address line can fail in two ways: temporary or definitive failure.

A temporary failure sets address state to 'Retry', sets a retry counter on the address line to the value specified on corresponding Connect Sender configuration (on first failure) or decreases with one, creates a one-time scheduled task that will change message state to 'Released' after a period of time specified on the Connect Sender configuration and finally sets the state of the entire message to 'Waiting'. If there are several address lines ending up in state ‘Retry’, only one scheduled task will be created with the closest execution time. The creation of the task can be affected by the background job definition – see Scheduled Tasks.

A permanent failure sets address state to 'Failed' and will cause the state of message to be eventually set to 'Failed' as well, but the logic will first try to resolve all address lines before setting the final state. No one-time scheduled task will be created for messages ending up in state ‘Failed’.

With other words as long as there are address lines with state 'Retry', the state of message will be 'Waiting'. If at least one address line will be in state 'Failed', the entire message will eventually also be marked as 'Failed'.

States

Application Message

An Application Message can have following states:

• Released – the initial state
• Processing – message has been picked up by the trigger (or Batch Processor for restricted messages)
• Finished – message has been successfully processed
• Waiting – address execution has temporarily failed and be retried or there is a scheduled task that will trig more executions.
• Failed – message/address execution has permanently failed
• Canceled – message execution manually cancelled
• Suspended – message execution suspended

State ‘Canceled’ can only be entered manually in the client application.
A message created in a stopped queue will get state ‘Suspended’. It is also possible to temporarily suspend a message manually in the client application. Starting a stopped queue will automatically release all suspended messages in this queue.

Address Line

An address line (Address Label) can have following states:

• Released – initial state
• Transferred – successfully processed address line
• Retry – address execution has temporarily failed and be retried
• Failed – address execution has permanently failed

Execution Steps

Message processing can be trigged in the background from the Batch Processor or directly, from SOAP Gateway or Connect Reader framework. In the first case the message to be processed is already in state 'Processing' while in the second and third case the massage has not been persisted yet and is still in state 'Released'.

Note: for In-Order and In-Sequence queues the application message picked up by the Batch Processor is in state 'Released', but Batch Processor will change the state to 'Processing' before calling Message Processor. The state change is performed in a separate transaction. See also handling of Restricted Messages.

Message Processor performs following steps on an Application Message:

1. If there is a BizAPI defined, execute the BizAPI (outbound messages). It will be done in a separate thread and in separate transaction.
2. If there are no address lines, call the Message Router.
3. In a loop process over all address lines in state ‘Released’ if the process has been initiated by the Batch Processor (message in state 'Processing') or if it is a synchronous message (message in state 'Released' called from SOAP Gateway or Connect Reader framework).
4. If necessary create a one-time scheduled task (if any of address lines ended in state ‘Retry’, there are no failed address lines and there is no other scheduled task that would execute before this one).
5. Set the final message state, which can be one of ‘Finished’, ‘Failed’ or ‘Waiting’.
6. As of patch 145612: if it is an outbound synchronous message invoked using the algorithm based on Oracle AQ, send a Response AQ JMS Message (read about the new handling of synchronous invocation from PLSQL Access Provider).
7. Save the message (read about persisting synchronous messages)
8. If the message has been routed, but no addresses have been processed (inbound, asynchronous), create a non-persistent Message Body with the information about queue the message has been saved into to or an error message on failure. This reply can be utilized by the Connect Reader framework to create a Response Message.

There are two types of messages: inbound and outbound. Message Processor doesn't make any difference between these two types. The only reason why the Application Message is stamped with the type flag is because of grouping of routing rules per type. On the other hand Routing Addresses can be treated as Inbound (BizAPI or PL/SQL), i.e. saving incoming data to the IFS Applications database, or Outbound (remaining types), i.e. sending the message outside of the IFS Applications.

Address Processing

Processing of a single address line consists of the following steps (see also How to create Destination Address):

1. Find a Request Envelope that matches the incoming data. The incoming data is the response data form main address in the previous address chain link or, for the first chain link, it is just the initial request or function result (see Understanding an Application Message). Request Envelope can be one of the predefined envelopes or UNKNOWN_XML or NONE_XML.
2. If any transformer is defined, the transformation will be applied on the enveloped data. For UNKNOWN_XML and NONE_XML the entire message data will be taken.
   

   Note that for binary data only transformation using binary Java transformers is possible.

3. If an output envelope is defined (envelope define on the Routing Address), the data will be put in to the specified envelope. Note that it is not possible to envelope binary data. Trying to do so will result in an error.
4. If the processed data is binary and is about to be send to a BizAPI or a PL/SQL method (a BizAPI or PL/SQL address), the data will be encapsulated within a special document with name BinaryParameter (see BizAPI with Binary Data).
5. If the message is supposed to be compressed and the actual sender is supporting compression, the data will be zipped.
6. The data will be send to the destination using actual sender's native protocol. It will be done in a separate thread. Furthermore BizAPI and PL/SQL addresses will be called in a separate transaction.

   Note that a failure during data sending will not guarantee data consistency - Message Processor doesn't implement two-phase commit and consequently doesn't know if the data at the receiving part has been processed correctly or not.

7. If the actual sender defines a BizAPI or PL/SQL address and the response data is an instance of the special document BinaryParameter, the response binary data will be extracted from this document.
8. The type of the response message data will be detected.
9. If the data is not binary and not encoded in UTF-8, it will be re-coded to UTF-8.
   

   Note that internally all type of text data (plain text or XML) is always encoded in UTF-8 character encoding. Re-coding from/to another character set is done, if necessary, in Readers, when reading messages and Senders, when sending messages.

10. If the response message is XML and output envelope is defined and also the envelope defines response for outbound messages, the framework will make an attempt to extract the data from its envelope. Otherwise the entire response message will be used in the remaining steps. See also how to work with envelopes.
    

    Note that if the output envelope defines the identification pattern for the response and the pattern will be found in the message, unsuccessful attempt to extract the body will lead to an error.

11. If any response transformer is defined, the data will be transformed (binary data can only be transformed using binary Java transformers).
12. If the response should be enveloped and is not binary, it will be enveloped according to the definition of response envelope in the actual Request Envelope (step 1 above). If the Request Envelope is UNKNOWN_XML or NONE_XML, the response will be enveloped in a simple, basic SOAP envelope (only text data, i.e. plain text or XML).
13. A new Message Body with the response data will be created and saved to the database.
14. If this is a main address, the response data will be passed as input to all addresses in the next address chain link or returned to the caller if there are no more chain links and this is a synchronous message.

Actions on Application Message

Following actions can be performed on an Application Message in the client application:

• Reroute – removes all address lines with corresponding reply message bodies and creates new ones by rerouting the message and changes state to ‘Released’; can only be executed on messages in state ‘Failed’
• Restart all – sets state of all address lines and the message itself to 'Released' and removes all reply message bodies; can be executed on messages in states ‘Failed’ and ‘Canceled’
• Restart failed – sets state of failed address lines and the message itself to 'Released'; can be executed on messages in states ‘Failed’ and ‘Canceled’
• Duplicate & Release – duplicates a finished message without its address lines and reply message bodies; can only be executed on messages in state ‘Finished’
• Resume – changes message state from ‘Suspended’ to ‘Released’
• Suspend – sets message state to ‘Suspended’; can only be executed on messages in state ‘Waiting’
• Cancel – sets message state to ‘Canceled’; can be executed on messages in states ‘Failed’, ‘Waiting’ and ‘Suspended’.

Message Bodies

Typically an Application Messages has one message body with input data. Processing of address lines will cause creation of a new message body for each successfully executed address line with response from the corresponding Connect Sender (a reply body). Attribute AddressSeqNo on Message Body points out the corresponding address line (AddressLabel.SeqNo).

In some circumstances, for example some messages created from the printing framework, the message can contain several bodies with input data, but only one body is the “main” one. The other bodies are collected as “attachments” to the corresponding Connect Sender that can handle such, typically Mail Sender.

Note: In the rare situation when the message contains several input bodies, only the main body is used for routing and is, if necessary, re-coded to UTF-8, processed through an outbound BizAPI, transformed and enveloped. The other bodies remain untouched.

Transaction isolation

BizAPI and PL/SQL addresses are executed in a separate transaction. Also outbound BizAPIs are called in a separate transaction.