Running the ALE Module

When processing application events, the ALE Module receives events that the SAP application pushes to the connector. When processing requests, the ALE Module receives business object requests from the integration broker and sends them to the SAP application.

Initialization and termination

The init() method opens an RFC connection to the SAP 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 performs the following tasks:

  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, the process terminates the connector.

Because the connector supports multi-threading, when the ALE Module processes requests from the integration broker, it uses SAP's Java Connector (SAPJCo) connection pool of such handles.

Important:
When you use the ALE 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.

Processing business objects

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

When business object data is returned from SAP's Java Connector (SAPJCo) 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 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.

Processing events in the MQSeries queue

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

Figure 51. 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:
  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.

    For a large object, the connector breaks up the object into multiple messages so as to enable more efficient processing. For details about how to enable this support, see Event processing components and Table 20.

  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 that will convert the data in the message body to business objects for posting to the integration broker.
  8. The connector attempts to post each business object to the integration broker. If the integration broker is WebSphere Interchange Server, the connector first checks if there are subscriptions for the business object. After processing all the business objects in the message body, the message's IDocProcessingStatus and BOProcessingStatus are updated and the message is moved to the queue specified by the SAPALE_Archive_Queue property. For more information on IDocProcessingStatus see, "Creating archive messages" and on BOProcessingStatus see, "Structure of JMS-MQ message for event and archive processing".

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.

Resubmitting events

Events that have been placed in the SAPALE_Unsubscribed_Queue and the SAPALE_Error_Queue can be resubmitted using a command line utility (BIA_AleEventUtil.bat for Windows, and BIA_AleEventUtil.sh for Unix) located in the following directory: ProductDir/connectors/SAP/utilities/ALEEventUtil/, where ProductDir represents the directory where the connector is installed. For more information, see ALE Module Queue Management utility for event processing.

Structure of JMS-MQ message for event and archive processing

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

Table 20. Structure of JMS-MQ message for event and archive processing

JMS Message Header Property Description
CorrelationId The connector sets the value of this property from the Transaction ID (TID) sent by SAP.

When breaking up a large IDoc into smaller message parts, this property identifies to which larger message the part pertains. The connector sets this value to the JMSMessageID of the first part in the set. Note that the CorrelationID of the first part is always that of the first JMS-MQ message associated with the large IDoc. For details about breaking up an IDoc into smaller message parts, see Event processing components.

JMSMessageID The unique ID of the message. When breaking up a large IDoc into smaller message parts, the connector sets the value of this property for all parts other than the first one to the JMSMessageID of the first part. For details about breaking up an IDoc into smaller message parts, see Event processing components.
MutliPartMessage When breaking up a large IDoc into smaller message parts, the connector uses this property to identify the message with the appropriate part of the larger message. For example, assuming the original larger IDoc message is partitioned into 8 JMS-MQ messages, then the value of the MultiPartMessage property of each part is 1 of 8, 2 of 8, and so on for each message. For details about breaking up an IDoc into smaller message parts, see Event processing components.
TidStatus Maintains the status of the TID.
IDocProcessStatus Maintains the status of the IDoc object during event processing.
BOProcessingStatus Maintains the status of all IDocs in the message using the format, <CID> :: <IDoc sequence number><Status symbol>. Possible status symbols are S for Success, F for fail and U for unsubscribed. For example "<CID> :: 0S, 1F, 2U" means the first IDoc was successful, second failed, and third was unsubscribed for CorrelationId = <CID>.

Table 21 describes the possible values for the IDocProcessStatus property after an event is moved to the Archive queue.

Table 21. Archive queue values for the IDocProcessStatus message property

IDocProcessStatus property value Event status Description
success Success All business objects in the message have been posted with no errors.
partial Partial success One or more but not all business objects in the message have been posted with an error. If the integration broker is WebSphere Interchange Server, one or more but not all business objects in the message have been posted with an error or are unsubscribed.
unsubscribed Unsubscribed If the integration broker is WebSphere Interchange Server, all business objects in the message are unsubscribed.
fail Fail All business objects in the message have been posted with an error.

Creating archive messages

When the message is moved from the Event queue to the Archive queue, the IDocProcessingStatus and BOProcessingStatus are updated. The message body remains unchanged.

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 22:

Table 22. 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 The IDocProcessStatus is updated to success and the BOProcessingStatus is <CID> :: 0S
Fails to transform the second IDoc into a business object The IDocProcessStatus is updated to partial and the BOProcessingStatus is <CID> :: 0S, 1F
Successfully transforms the third IDoc, and posts the business object to the integration broker The IDocProcessStatus is set to partial and the BOProcessingStatus is <CID> :: 0S, 1F, 2S
Successfully transforms the fourth IDoc, but the business object created is not subscribed in the integration broker
  • The IDocProcessStatus is set to partial and the BOProcessingStatus is <CID> :: 0S, 1F, 2S, 3U
  • After processing the last IDoc, moves the message from the Event queue to the Archive queue and gives it IDocProcessStatus of partial and BOProcessingStatus of <CID> :: 0S, 1F, 2S, 3U

Supporting multiple message types for event processing

You can use the same instance of the connector for different message types that refer to the same IDoc type, however a different business object definition is required for each message type. To create a different business object definition, copy and rename the business object definition of the IDoc type. Make sure you configure the correct MsgType in the verb ASI of the appropriate verb.

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 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:

ALE Module Queue Management utility for event processing

Use this command-line utility for maintenance of MQ queues used by the WebSphere Business Integration adapter for mySAP.com's (v. 5.3.2) ALE Module. The utility resubmits event messages, dumps event messages to a file system for viewing, and archives messages to a file system.

An IDoc is processed in a unit of work called a transaction. An SAP transaction containing more than one IDoc is called a transaction packet. The adapter processes transactions and transaction packets by using an MQ message to hold the IDoc or IDocs. The adapter converts the IDoc into its corresponding business object. The ALE Module handles processing of IDocs in a two-step process: SAP to the adapter, then the adapter to the broker. Exceptions are handled differently for each step.

For more information about MQ messages, see the WebSphere Business Integration Library: http://www.ibm.com/software/integration/wmq/library/.

Processing IDocs from SAP to the adapter

If the adapter detects unsubscribed or unsupported business objects or raises any exceptions during IDoc transmission, the adapter will fail the SAP transaction. Failed transactions can be viewed and resubmitted from SAP transaction SM58. Before resubmitting the transaction, address the exception:

Once this step executes successfully, the transaction with SAP is complete.

Important:
To prevent duplicate event delivery, do not resubmit a corrected IDoc transaction or individual IDoc within a transaction packet.

Processing IDocs from the adapter to the broker

If an MQ message contains a single business object and is unsubscribed, the MQ message will be moved to the unsubscribed queue. Each unsubscribed business object within a transaction packet will persist as its own MQ message on the unsubscribed queue. The original MQ message remains intact and contains the processing status of the individual IDocs. Once the transaction packet for the MQ message is completely processed, it is moved to the archive queue.

Before resubmitting the transaction, address the exception:

After you complete the correction, use the command utility AleEventUtil to move the MQ message back to the event queue, resubmitting the event.

When an IDoc contains malformed data or contains 'nodata', the IDoc is moved to the Error Queue as its own message.

Installing and configuring the ALE Module Queue utility

The ALE Module Queue utility is packaged with the SAP adapter. When installed, it has the following directory structure:

\Connectors\SAP\BIA_AleEventUtil.jar

\Connectors\SAP\BIA_AleEventUtil.bat

\Connectors\SAP\BIA_AleEventUtil_readme.txt

Modify the start script file, BIA_AleEventUtil.bat, to capture the following parameters. To access local queue managers, you need only configure MQQueueManager.

Variable Description Comments
MQQueueManager Name of the Queue Manager Required parameter.
MQChannel Server connection channel name Required for accessing remote queue manager.
MQPort Port on which the channel is listening Required for accessing remote queue manager.
MQHost Host name or IP address on which the Queue Manager is running Required for accessing remote queue manager.
MQUser Valid username on MQHost Required for accessing remote queue manager.
MQPassword User password Required for accessing remote queue manager. Value not encrypted.

Running the MQ management utility

After installing and configuring the utility, navigate to the directory where the ALE Module Queue Management Utility is installed. Valid commands for the utility are:

-c <choice> (valid options are [move, archive, dump, replicate])

-i <inputq>

-o <outputq>

-f <outputfile>

-d <date>

-u <unique message ID>

-n <replication count>

Note:
When there is an existing file with the same name, the archive command will raise an exception but the dump command will overwrite the file.

To dump the contents of a message to a file, from a command prompt change to the directory where the utility is installed and run the following command:

BIA_AleEventUtil -cdump -i<QueueName> -f<OutputFileName>

To move messages from one queue to another, run the following command. This command will move all the messages in the queue:

BIA_AleEventUtil -cmove -i<FromQueue> -o<ToQueue>

To move a single message, use the additional parameter of MessageIdByte corresponding to the message ID of the desired message:

BIA_AleEventUtil -cmove -i<FromQueue> -o<ToQueue> -u<MessageIdByte>

To move all the messages equal to or earlier than a specified date, add the Date parameter:

BIA_AleEventUtil -cmove -i<FromQueue> -o<ToQueue> -d<date(YYYYMMDD)>

To archive messages from a queue to a file, removing all messages equal to or earlier than a specified date, use this command:

BIA_AleEventUtil -carchive -i<QueueName> -f<ArchiveFileName> -d<date(YYYYMMDD)>

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 metadata 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. A value in this attribute causes the connector to manage TIDs when processing service call requests. If you do not want TID management for request processing, do not set a value for this attribute. For more information, see Parent wrapper business object.
Note:
The value of the TransactionId attribute must be a unique identifier. The value is not the equivalent of a TID in the SAP application. These values are stored in a table within the JMS_MQ message in the queue specified by the SAPtid_Queue configuration property.

If the TransactionId attribute does not have a value, the ALE Module sends the request directly to SAP. If the TransactionId attribute has a value, the ALE Module does the following:

  1. The connector checks whether the JMS-MQ message in the queue specified by the SAPtid_Queue configuration property has this value.
  2. The connector converts the business object to RFC tables and makes an RFC call to SAP.
  3. After SAP acknowledges receipt of the RFC call, the connector removes the key from the table, archives the key, and returns a success status to the integration broker.

Archiving

After successfully processing a service call request, the corresponding entry in the table of the JMS-MQ message in the SAPtid_Queue is removed and archived to a directory. A file is created in the \ale\request subdirectory for WINNT or /ale/request for Unix systems. The ale subdirectory is located in the directory where the adapter is started. The entry that has been removed from the table will be used to create the new file. The file name will have the following format: <ObjectID>_<TID><timestamp>.executed where ObjectID is the value from the TransactionId attribute, TID is the transaction ID from SAP, and timestamp is the time stamp of when the file was created.

The adapter itself manages the deletion of these archive files using the connector configuration property ArchiveDays. The value in the connector configuration property, ArchiveDays, determines the amount of days these archived files will persist in the ale\request sub-directory. Any files older than the number of days specified in ArchiveDays will be deleted. If this property is not configured, the default value for ArchiveDays is seven days. These archive files can also managed manually by deleting the files yourself.

Resubmitting failed requests

For all failed requests indicated by the integration broker, check whether an archive file has been created for the request. If the archive file exists for the Object ID in the request then do not resubmit the request from the integration broker. Resubmit the request if there is no archive file for that ObjectID. Ensure the ArchiveDays connector configuration property is set to a value that will allow for verification of resubmitted requests.

Columns in the table of the JMS MQSeries message for request processing

Table 23 describes the columns of the JMS-MQSeries message that the connector gets from the SAPtid_Queue:

Table 23. Columns of JMS-MQ message for request processing

Column name Description
ObjectID The value that is in the TransactionID attribute of the requested business object. This value is used as the key for the table
TID The transaction ID obtained from SAP
TidStatus Status of the transaction

Supporting multiple message types for request processing

For event processing, you can use the following mechanisms:

Copyright IBM Corp. 1997, 2004