How the ALE module works

When processing application events, the ALE Module acts as a server to the SAP application. In this capacity, the ALE Module receives events that the SAP application "pushes", or sends, to the connector. When processing requests, the ALE Module receives business object requests from the integration broker and sends them to the SAP application.

This section documents the following processes:

Initialization and termination

The init() method opens an RFC connection to the SAP R/3 application through the SAP Gateway. If the connector fails to initialize, it terminates the connection using the terminate() method. The connector terminates by disconnecting from the SAP Gateway.

When processing application events or business object requests, the connector's initialization process does the following:

  1. Registers with the SAP Gateway the Program ID specified in the RfcProgramId connector configuration property. For information on setting the Program ID as a TCP/IP port see "Registering the RFC Server module with the SAP Gateway".
  2. Opens an MQSeries session to the queues configured for the connector.
  3. Verifies that the required MQSeries queues for event and request processing have been created. If they have not been created, terminates the connector.

For more information, see Configuring the ALE module.

Because the connector supports multi-threading, when the ALE Module processes requests from the integration broker, it does not use the module's init() method to create a connection handle. Instead, it uses the Vision connector framework's connection pool of such handles.

Important:
When you use this module to process application events, connector polling is required to properly initialize the module (to install the RFC functions on the server), and for it to properly manage errors. Therefore, do not set the value of the PollFrequency property to key or to no. Do not allow the SAP application to trigger events to the connector until you have verified that the connector's log displays the installation of the required RFC functions.

Business object processing

The ALE Module's processing of WebSphere business objects for SAP is initiated either through event processing or request processing.

This section describes:

Note:
When business object data is returned from SAP's Java Connector (jCO) API, the ALE Module receives values for DATS and TIMS fields in the following formats: YYYY-MM-DD (the hyphens are included) for the DATS data element, and HH:mm:ss (the colons are included) for the TIMS data element. The capitalized HH denotes 24-hour time, and not 12-hour time. When processing events, the ALE Module changes these formats to fit the 8-character and 6-character maximum size of their corresponding business object attributes. The connector shortens the length of the value by removing the hyphens from the date data and the colons from the time data.

Event processing

Two RFC-enabled functions in an SAP application initiate all event processing for the ALE Module. The ALE's business object handler for event processing supports the functions idoc_inbound_asynchronous and inbound_idoc_process.

When processing events, this business object handler persistently stores the business objects in an MQSeries queue. The connector maintains the Transaction IDs (TIDs) associated with the RFC call to guarantee that each piece of data is delivered once and only once.

Important:
A single RFC call can send the data for one or more IDocs. Therefore, an MQSeries queue may contain a JMS-MQ message that represents multiple IDocs, each of which represents a business object. Each RFC call is associated with a single TID.

This section describes the following:

Processing Events in the MQSeries Queue

Figure 17 illustrates how the ALE Module processes the MQSeries queue.

Figure 17. Business object event processing


Business-object event processing for the ALE Module executes in the following manner:

  1. An RFC function pushes event data to the SAP Gateway, where a listener thread picks up events. The thread checks the TID associated with the event to determine whether a JMS-MQ message exists for the TID (that is, whether the TID has been sent previously):
  2. The listener thread instantiates the ALE event-processing business object handler, which retrieves the RFC-interface data from the SAP Gateway.
  3. The business object handler formats each transaction into a JMS-MQ message, which it stores persistently in the queue specified by the SAPALE_Wip_Queue configuration property.

    Each JMS-MQ message represents a single RFC call. Each RFC call can represent one or more business objects associated with a single TID. The connector stores the TID in the message's CorrelationID property, sets the TidStatus to CREATED, and sets the IDocProcessStatus to unknown. The connector uses the message body to store IDoc data.

  4. After each transaction completes, the connector changes the value of TidStatus and sends a confirmation back to SAP indicating that the transaction is complete. After SAP receives the confirmation, it removes the TID and its associated data from the SAP application.

    If the AleUpdateStatus configuration property evaluates to true, the connector updates the status of the IDoc in SAP. If it retrieves a packet of IDocs, it updates the status of all IDocs in the packet. For more information, see "Updating the IDoc Status in SAP".

  5. The connector moves the JMS-MQ message from the Wip queue to the queue specified by the SAPALE_Event_Queue configuration property.
  6. The ALE Module's polling thread picks up the event message from the Event queue.
  7. The connector instantiates an ALE data handler, which creates a WebSphere business object for SAP based on the message's meta-data.
  8. The connector checks for subscribed events:

The Ale Module uses FIFO (First In, First Out) to maintain the processing order when reading the messages from the Event queue.

Important:
Connector polling is required for this module to manage errors properly when it processes application events. Therefore, do not set the value of the connector's PollFrequency property to key or to no. Do not allow the SAP application to trigger events to the connector until you have verified that the connector's log displays the installation of the required RFC functions.

Creating Archive Messages

A single event message may contain multiple IDocs, each of which represents a business object. As it processes each IDoc in the event message, the connector creates corresponding messages in the Archive queue. The number and types of archive messages depends on the processing status of each IDoc.

For example, assume the connector processes an event message with four IDocs, each of which it transforms or attempts to transform into a business object, with the results illustrated in Table 16:

Table 16. Archive Message Creation

Status of IDoc or business object Resulting Archive Message
Successfully transforms the first IDoc, and posts the business object to the integration broker Creates an archive message with the same CorrelationID as the event message, and an IDocProcessStatus of success--the message contains the data in the first IDoc
Fails to transform the second IDoc into a business object
  • Creates an archive message with the same CorrelationID as the event message, and an IDocProcessStatus of fail--the message contains the data in the second IDoc
  • Changes the IDocProcessStatus of the first archive message from success to partial (because not all business objects in the event message processed successfully)

Successfully transforms the third IDoc, and posts the business object to the integration broker Writes the data from the third IDoc to the message with the IDocProcessStatus of partial
Successfully transforms the fourth IDoc, but the business object created is not subscribed in the integration broker
  • Creates an archive message with an IDocProcessStatus of unsubscribed--the message contains the data in the fourth IDoc
  • After processing the last IDoc, moves the message from the Event queue to the Archive queue and gives it IDocProcessStatus of original

The connector handles the event message from the Event queue in either of the following scenarios:

Note:
If connector goes down after processing the last IDoc in the event message but before archiving the event message, it archives the event message with an IDocProcessStatus of recovery. For more information, see "ALE module directories and files".

Structure of JMS-MQ Message for Event and Archive Processing

Table 17 describes the structure of the message that the connector sends to the Event and Archive queues.

Table 17. Structure of JMS-MQ Message for Event and Archive Processing

Property Name Description
CorrelationId The JMS message header property--the connector sets the value of this property from the Transaction ID (TID) sent by SAP
TidStatus The JMS message header property that maintains the status of the TID
IDocProcessStatus The JMS message header property that maintains the status of the IDoc object during event processing

As the connector processes each IDoc in an event message, it moves the IDoc into a message in the Archive queue. The archive message has the same CorrelationId as the event message. Depending on the processing status of each IDoc, the connector may create up to four different archive messages that correspond to the same event message.

Table 18 describes the possible values for the IDocProcessStatus property after a single business object's events are moved to the Archive queue.

Table 18. Archive Queue Values for the IDocProcessStatus Message Property

IDocProcessStatus Property Value Event Status Description
success Success When all IDocs in a single event message process successfully, the corresponding archive message contains all IDocs. In this case, there is a single archive message.
partial Success When some of the IDocs in a single event message fail processing, this archive message contains only the successfully processed IDocs. In this case, there are multiple archive messages.
unsubscribed Unsubscribed When some of the IDocs in a single event message are unsubscribed, this archive message contains all the unsubscribed IDocs. In this case, there are multiple archive messages.
original N/A
  • If any IDoc in a single event message fails processing or is unsubscribed, this archive message contains the entire original event message. The message is created even when the event message contains a single IDoc. In this case, there are multiple archive messages.
  • If the connector dies after successfully processing every IDoc in a single event message but before it moves the event message out of the event queue into the archive queue, the recovery process moves the event message to the archive queue with status of original and changes the status of the existing archive message from success to recovery. In this case, there are two archive messages: one with status original and one with status recovery.

fail Fail When any IDoc in a single event message fails processing, this archive message contains all the IDocs that failed formatting or were not sent successfully to the integration broker. In this case, there are multiple archive messages.
recovery Possible failure When event message processing does not finish properly, that is, the connector has successfully processed all IDocs in the event message but the event message has not been moved out of the event queue, the recovery process does the following:
  • changes the status of the archive message from success to recovery
  • moves the entire original event message to the archive queue with a status of original

This situation may occur if the connector dies before it moves the event message out of the event queue. In this case, there are multiple archive messages.

Updating the IDoc Status in SAP

To cause the connector to update a standard SAP status code after the ALE Module has retrieved an IDoc for event processing, you must:

If AleUpdateStatus evaluates to true, the connector sends the ALEAUD IDoc to SAP with status code information and, optionally, descriptive text. The ALEAUD IDoc calls the IDOC_INPUT_ALEAUD function module. The connector supports sending the following status codes to this function module:

In both of the cases above, the business integration system does not send further status codes that would indicate further processing.

For information on setting the connector-specific configuration properties that are required to return IDoc status, see:

For information on setting the connector-specific configuration properties that are optional to return IDoc status, see:

Request processing

The Vision connector framework uses the value of the verb AppSpecificInfo property of the top-level business object to instantiate the ALE request-processing business object handler. The doVerbFor() method in the request-processing business object handler initiates all business object requests.

The business object handler converts the business object data into two tables that represent the IDoc format and its meta-data component, the control record. Once the data is in IDoc format, the business object handler makes an RFC call to the appropriate SAP function module: either idoc_inbound_asynchronous or inbound_idoc_process. Because ALE is asynchronous, the connector does not wait for a return response.

Important:
By default, parent wrapper business objects generated by SAPODA contain a TransactionId attribute. The existence of this attribute causes the connector to manage TIDs when processing service call requests. If you do not want TID management for request processing, you must manually remove this attribute from the generated business object. For more information, see "Parent wrapper business object".
Note:
The value of the TransactionId attribute is a unique identifier populated by the integration broker. The value is not the equivalent of a TID in the SAP application.

If the TransactionId attribute does not exist, the ALE Module sends the request directly to SAP. If the TransactionId attribute exists, the ALE Module does the following:

  1. The connector checks whether the business object's TransactionId attribute has a value:
  2. The connector checks whether a JMS-MQ message with the same CorrelationID exists in the queue specified by the SAPtid_Queue configuration property.
  3. The connector converts the business object to RFC tables and makes an RFC call to SAP.
  4. After SAP acknowledges receipt of the RFC call, the connector informs SAP that it can delete the TID, and returns a success status to the integration broker.

Structure of MQSeries Message for Request Processing

Table 20 describes the structure of the JMS-MQSeries message that the connector gets from the Request queue:

Table 20. Structure of JMS-MQ Message for Request Processing

Property Name Description
CorrelationId The connector gets the value of this property from the TransactionId attribute of the request business object sent by the integration broker. If the TransactionId attribute contains no value, the connector constructs a value for this property from:BOName + BOKeyAttributes + TimeStampThe timestamp includes hour, minute, second, and millisecond of the system time. For example:sapCustomerMasterAttr1keyAttr2key150713882
TransactionId TID received from SAP. The value of this property serves as the unique identifier of the MQSeries message
TidStatus Status of the transaction

Copyright IBM Corp. 1997, 2003