Near-Real Time Outgoing Messages
The following diagram illustrates the flow of near-real time messages:
The following points describe the diagram
• When an event occurs in the system, you can initiate an outgoing message by storing a
notification download staging (NDS) record. NDS records for outgoing messages have a special processing method flag of XAI.
Fastpath:
Refer to
System Conditions May Trigger Notification and Workflow for information about creating notification download staging records.
• Once a message is stored on the NDS table, the download staging receiver reads it and invokes XAI to extract data from your product. An XAI inbound service is used to retrieve the full information for the object related to the message.
• The download staging sender takes the response from the executer (the system object as XML) and continues the processing. It uses a request XSL on the route type to transform the message to a format expected by the target. It then sends the message to the target using the sender on the XAI route type.
The following diagram illustrates the process:
The responsibilities of the download staging receiver and download staging sender are provided in detail below.
• Download Receiver
• Download Staging Sender
• Asynchronous Responses to NDS Messages
Download Receiver
The download staging receiver processes records in the NDS table that have a processing method flag equal to XAI and a status of either pending or retry . It also uses the priority flag on the NDS type and the creation date/time on the NDS to process records according to their priority.
The process is referred to as "near real time" because your download staging receiver should be continuously checking for new records in the NDS table.
When it finds a record, it invokes XAI (via the executer) providing the XAI inbound service.
The following section provides more information about the NDS lifecycle.
• Lifecycle of Notification Download Staging
• Building the XML Request
Lifecycle of Notification Download Staging
The download receiver processes NDS records based on their status. The following diagram describes the lifecycle of an XAI type NDS.
The following points describe the diagram:
• Records are created in pending status. A user may transition the record to the canceled state.
• The MPL processes records in pending and retry status. While the record is being processed, it is changed to in progress.
• Based on the results of the processing, records could be transitioned to error or complete.
Note:
An NDS is set to error if there is a problem with the NDS or if any of its related XDS records are in error.
• A user may cancel a record in the error state or change the status to retry to have the MPL try again.
Building the XML Request
To build the XML request for the outgoing message, the download receiver needs the following information:
• The XML request and response schemas used to retrieve information about the record related to the request. For example, if the outgoing message is to inform an external system that a person's name has changed, the XML request schema must retrieve the appropriate person record.
The
NDS type related to the NDS defines an XAI Inbound Service that references an appropriate XML request schema.
• The data related to the request. In this example, the NDS record should be stored with the ID of the person record that changed.
The person ID is stored as NDS context, with an appropriate Context Type, like PERID.
• XPATH information to tell the system where to plug in the related data into the request schema. In this example, when building the XML request, the person id must be plugged into the appropriate location in the XML request schema prior to executing the request.
The
NDS type related to this NDS defines a collection of context types. For each context type, you define an XPATH used to indicate where to substitute the context data.
Once the request schema is build, the receiver invokes XAI (via the executer) to execute the XML request. In our example, it calls the appropriate Person service and the XML response includes the extracted person information.
Top of the Page
Download Staging Sender
This piece is somewhat confusing, because the download staging sender behaves differently than other senders. Senders are typically responsible for
• Routing a request to an appropriate target
• In the case of the upload staging sender and the staging control sender, the sender is responsible for updating the status of the appropriate table.
In the case of the download staging sender, it's responsible for processing the "response" to the XAI executer, whose task was to build the XML request.
• If there is a problem executing the request, the download staging sender updates the NDS record in error and creates an
NDS exception record.
• If the executer was successful, the "response" is an XML request in a format understood by your product. The sender must perform the following steps to help process the outgoing message:
• Transform the request to a format expected by the target system(s)
• Route the outgoing message to the target
• Create an XAI download staging record for each message sent out. (There is typically only one, but it is possible for the outgoing message to have
multiple destinations.)
If any errors are found during any of these steps, the status of the NDS record is set to error and a record is written to the
NDS exception table. If the error is related to routing the message, the XDS is created in error and a record is written to the XDS exception table.
Note:
Configuration required. The above explanation assumes that you have correctly configured your download staging receiver to reference the download staging sender.
Routing Optional. It is possible that an
NDS message does not require routing information. In this case the download staging sender simply updates the NDS record's status
The following sections provide further detail.
• Lifecycle of XAI Download Staging
• Transform the Request
• Routing the Message
• Multiple Message Destinations
• An NDS Message That Doesn't Require Routing
Lifecycle of XAI Download Staging
The following diagram illustrates the lifecycle of an XAI download staging record.
An XAI download staging record is created in one of the following ways:
• When the download staging sender continues the processing for the outgoing message, it attempts to transform and route a message for each XAI route type indicated on the notification download profile. An XDS is created to record the message sent.
• If the message was sent successfully, the XDS is created in complete status.
• If an error occurred when sending the message, the XDS is created in error status and an XAI download exception is created.
Note:
Automatic Resend. If you have configured the system for automatic resend and the system detects that the error is due to the sender being unavailable, no XDS record is created in this case.
• When the system attempts to send a message
real time but the external system is unavailable, the system may create a pending NDS and a pending XDS record.
• A user may cancel a pending or error XDS record.
If you have resolved the error for an XAI download staging record, change the status of the related NDS record to retry. When MPL processes the NDS again, it deletes all XDS records in error and attempts to send them again.
Transform the Request
The download staging sender takes the XML response with the extracted data and attempts to transform into a format accepted by the target. It needs an appropriate XSL transformation script.
The XSLT is defined on an
XAI Route Type, which is referenced on the
download profile of the service provider referenced by the notification download staging record.
Note:
The NDS context information is available to the XSL.
Routing the Message
In addition to defining the appropriate XSL transformation scripts, the XAI route type also references a sender that tells the system how to route the message, for example it may be routed using a JMS queue.
Note:
Inactive Senders. If the message is targeted to an inactive sender and you have enabled automatic resend, the message is ignored and an MPL log entry is created indicating that the message was not sent.
If the target supports synchronous communication (for example, an HTTP sender), the
route type may be configured to receive an acknowledgement. This indicates to the download staging sender to wait for a response from the sender on the route type.
The download staging sender creates an appropriate XDS record with the XML request document and with a status of complete or error based on the results of the communication with the target. If the target has sent a synchronous response, the XML response is also posted on the XDS.
Note:
Automatic Resend. If you have configured the system for automatic resend and the system detects that the error is due to the sender being unavailable, no XDS record is created in this case and the NDS remains in pending.
If the target supports synchronous communication, you may indicate that a response to the outgoing message also requires action. For example, perhaps the outgoing message to an external system causes a new record to be created in that system. The response to the message may require an update to our initiating record to post the external system's identifier for the record on their side.
To enable this logic, you must check the Post Response switch on the
route type. If this has been checked, the download staging sender creates an XAI upload staging record (and a staging control record) and it links the XDS record as a foreign key. The XUS record is processed along with other uploaded messages, to invoke an appropriate service.
Note:
XML Response. If the Post Response switch on the route type is turned on, the XML response that is captured is the XML that results after applying the Response XSL. If the Post Response switch is not turned on (i.e., the response is a simple acknowledgement), XML response is posted without applying a Response XSL. (In fact, for simple acknowledgements, there is no need for a Response XSL.)
Asynchronous Responses. Refer to
Asynchronous Responses to NDS Messages for information about processing responses to messages sent asynchronously.
Multiple Message Destinations
If your message must be sent to more than one external system, a different XAI route type is required for each system that the message must be sent to so that the sender and XSLT for each external system can be defined.
The recommended procedure for sending a message to multiple destinations is to
• Generate an NDS for each destination where each NDS defines the same NDS type but different service providers. In other words, the service provider represents the destination.
• When this NDS record is processed, the sender information defined for the XAI route type is used to route the message appropriately and an XAI download staging (XDS) record is created.
Note that it is possible for the download profile's formatting method to reference more than one XAI route type. This is perhaps another configuration that could be used to send a message to multiple destinations. In this case an XDS record is created for each XAI route type to track the XML request. However, it is not possible to track
asynchronous responses to multiple messages using this mechanism. Defining multiple route types for a download profile formatting method should only be done if you do not expect an asynchronous response.
An NDS Message That Doesn't Require Routing
If an NDS message is being sent to one of your own external systems and this system may be accessed directly, you could design your message such that XAI routing is not necessary. For this scenario, the assumption is that the application service that is invoked by the XAI inbound service completes all the necessary steps to update the external system.
If this is the case, you are not required to define an XAI Route Type on the appropriate notification download profile entry. In addition, no message sender is required for this external system.
The download staging sender's sole responsibility for a message of this type is to update the NDS status.
Top of the Page
Asynchronous Responses to NDS Messages
If you send an asynchronous NDS message and you expect a response, the response is received as an inbound message. In order to recognize that an inbound message is a response to an NDS message, there must be some handshaking. In other words our system must pass a unique identifier of our message to the external system and the external system must include that identifier in the response.
• Populating the Unique Message Identifier
• Recognizing the Inbound Message Response
Populating the Unique Message Identifier
As described in
Building the XML Request, the information that may be included in the XML request we build is information linked to the NDS record as context. Therefore, the unique identifier you want to send to the external system must be stored as a context record. (Let's call this context type Message ID). Because the notification download staging ID is a unique identifier, you may choose to populate Message ID with the NDS ID. However, it is possible that the external system requires an identifier in a different format. For example, the NDS ID is a 12-byte number. Perhaps the external system can only receive a 10-byte number for the Message ID.
It is the responsibility of the mechanism that creates the NDS record (i.e., the algorithm or user exit or database trigger) to create a context entry for Message ID with an appropriate value that is compatible with the target system.
When creating your XML request schema, if you expect a response to your message, you must include the message ID as an attribute in the XML request. Because the message id is not part of the product information that your request schema is extracting, it should be defined as a private attribute. Once the XML is created, it is the responsibility of the XSL to transform the Message ID into the target specific XML element.
Note:
Only One Route Type. Because the unique Message ID for an NDS message is linked to the NDS record via context, it is not possible for the system to handle multiple route types (and therefore multiple senders) for a single message IF an asynchronous response is expected. The reason is because all senders receive the same unique Message ID and if each sender responds, the system is not able to determine which response is received for which sender.
Recognizing the Inbound Message Response
When the external system sends an asynchronous response to your NDS message, it is received as an inbound message. This inbound message must include the Message ID that you sent so that you can recognize this as a response. In addition, the XSL transformation must populate the identifier of the external system sending the message.
The following points describe the detail related to receiving an inbound message:
• When a response comes in, the message is translated using an XSLT script. The XSLT must map the message ID, which is the unique identifier of the NDS message that this is a response to, to the XML element MessageID. It must create an attribute with the XML element ReplyToMessageSource populating the value with an appropriate external system. This value should correspond to the external system code of the service provider related to the NDS message.
• The XML request of the inbound message is processed as normal.
• The existence of the special message elements in the XSL indicates to XAI that XML response processing is required. It looks for a complete NDS with a service provider whose external id matches the ReplyToMessageSource and with a context type of Message ID whose context value matches XAI Message ID.
• When the correct NDS is found, the system finds the related XAI download staging record and populates the XML response with the XML request of the incoming message.
• If the XDS request is not associated already with a response or the latest associated response is in error status stamp the current response on the XDS request record.
• If the response came into the system as an XAI upload staging (XUS) record, the foreign key to the XDS record (NDS ID and XAI route type) to which it is responding is linked to the XUS.
• If the response did not come in as an XAI upload staging record (for example, it came in via JMS queue), an XAI upload staging record and an XAI staging control record are created in complete status as an audit and the foreign key to the XDS record is linked to the XUS.
Note:
Errors Linking the XDS. If the system has a problem finding the appropriate XDS record to link to the incoming response, the inbound message is still processed. A log entry is added to the XAI trace file reporting the error in identifying the correct XDS record.
Parent topic