The adapter supports inbound processing (from the SAP server to the adapter) for the ALE pass-through IDoc interface.
When you are configuring a module for the ALE pass-through interface, you can indicate whether the IDocs are sent as a packet. You make this selection on the
Configuration Properties window of the external service wizard. The selection you make is reflected in the application-specific information for the IDoc wrapper business object.
Note: When you use the ALE pass-through IDoc interface, a wrapper business object contains a data stream representing the IDoc. No separate IDoc business object exists for pass-through IDocs.
The following list describes the sequence of processing actions that result from an inbound request using the ALE interface.
1. The adapter starts event listeners to the SAP server.
2. Whenever an event occurs in SAP, the event is sent to the adapter by way of the event listeners.
3. The adapter converts the event into a business object before sending it to the endpoint.
The adapter uses the event recovery mechanism to track and recover events in case of abrupt termination. The event recovery mechanism uses a data source for persisting the event state.
If you have selected split IDocs and SAP is sending packet IDocs, the adapter delivers each IDoc inside the packet as an individual event to the end point. During recovery, the SAP system has to resubmit the whole packet. The adapter only delivers IDocs which have not been delivered in previous attempts from the packet.
Note that the adapter is able to listen to and deliver events from multiple SAP systems using multiple activation specs.
The adapter is also able to deliver events to multiple endpoints. You enable delivery to multiple endpoints by configuring multiple activation specifications that exist in the same module.
v If the endpoints subscribe to the same events from the same SAP system, all properties in the individual activation specifications must be identical.
v Endpoints that subscribe to different activation specifications receive events that match the criteria for the activation specification.
Define a separate activation specification for each endpoint to which events need to be delivered, except when the adapter delivers events only to those endpoints that are active.
Note: When multiple endpoints subscribe to the same events from the same event store, the adapter assures event delivery to active endpoints only. Any endpoints that are inactive do not receive the event. If there are multiple endpoints and any one endpoint is not active, the message is skipped for that endpoint and the adapter delivers the event only to the active endpoints. If all the endpoints are inactive, the event is rolled back, and the event needs to be resubmitted from SAP.
The following table provides an overview of the differences between the ALE interface and the ALE pass-through IDoc interface for inbound processing.
Table 5. Differences between ALE interface and ALE passthrough interface
Interface When to use SplitIDoc = true
SplitIDoc = false
Parsed IDoc = true
ALE inbound This interface converts the raw incoming IDocs to business objects, which are readily consumable by the client at the endpoint.
On receiving the IDoc packet from SAP, the adapter converts the IDocs to business objects, one by one, before sending each one to the endpoint.
On receiving the IDoc packet from SAP, the adapter converts the IDocs in the packet as one business object before sending it to the endpoint. The incoming IDoc is only partially parsed (the control record of the IDoc is parsed but the data record is not). The client at the endpoint is responsible for parsing the data record.
ALE
pass-through IDoc
This interface wraps the raw incoming IDoc in a business object before delivering it to the client at the endpoint. The client is responsible for parsing the raw IDoc.
On receiving the IDoc packet from SAP, the adapter wraps each raw IDoc within a business object before sending the objects, one by one, to the endpoint.
On receiving the IDoc packet from SAP, the adapter wraps the raw IDoc packet in a business object before sending it to the endpoint. This attribute is not applicable to the ALE pass- through IDoc interface. (Neither the control record nor the data record of the IDoc is parsed.
Event error handling
WebSphere Adapter for SAP Software provides error handling for inbound ALE events by logging the errors and attempting to restart the event listener.
When the adapter detects an error condition, it performs the following actions: 1. The adapter logs the error information in the event log or trace file.
Log and trace files are in the /profiles/profile_name/logs/server_name path of the folder in which WebSphere Process Server or WebSphere Enterprise Service Bus is installed.
2. The adapter attempts to restart the existing event listeners.
The adapter uses the activation specification values for RetryLimit and RetryInterval.
v If the SAP application is not active, the adapter attempts to create new listeners every time for the number of times configured in the RetryLimit property.
v The adapter waits for the time specified in the RetryInterval parameter before creating the event listeners.
3. If all the retry attempts fail, the adapter logs the relevant message and CEI events, stops message end points and stops trying to recover the ALE event listener.
Note: You must restart the adapter or SCA application in this case.
4. If all the retry attempts fail, the adapter logs the relevant message and CEI events and stops trying to recover the ALE event listener.
Note: You must restart the adapter or SCA application in this case.
Event recovery
You can configure the adapter for ALE inbound processing so that it supports event recovery in case of abrupt termination. When event recovery is specified, the adapter persists the event state in an event recovery table that resides on a data source. Event recovery is not the default; you must specify it by enabling once-only delivery of events during adapter configuration.
Data source
Event recovery for ALE inbound processing requires that a JDBC data source be configured. You use the administrative console to configure the data source. You select a JDBC provider (for example, Derby) and then create a new data source.
Event recovery table
You can create the event recovery table manually, or you can have the adapter create the event table. The value of the EP_CreateTable configuration property determines whether the event recovery table is created automatically. The default value of this property is True (create the table automatically).
To create the table manually, use the information provided in the following table.
Table 6. Event recovery table fields
Table field name Type Description
EVNTID VARCHAR(255) Transaction ID for the tRFC (Transactional Remote Function Call) protocol.
The tRFC protocol significantly improves the reliability of the data transfer, but it does not ensure that the order of ALE transactions specified in the application is observed. Event ordering is also affected by the number of event listeners. However, at some point all ALE transactions are transferred.
EVNTSTAT INTEGER Event processing status. Possible values are: v 0 (Created)
v 1 (Executed) v 3 (In Progress) v -1 (Rollback)
XID VARCHAR(255) An XA resource keeps track of transaction IDs (XIDs) in the event recovery table. The adapter queries and updates that XID field. During recovery, WebSphere Application Server calls the resource adapter, querying it for XA resources, and then does transaction recovery on them.
Note: The XA resource is used to enable assured once delivery. Make sure the activation specification property Assured Once Delivery is set to true.
BQTOTAL INTEGER Total number of IDocs in the packet.
BQPROC INTEGER Sequence number of the IDoc in the packet that the adapter is currently processing.
Table 6. Event recovery table fields (continued)
Table field name Type Description
EVNTDATA VARCHAR(255) Not used.
To use event recovery for multiple endpoints, you must configure a separate event recovery table for each endpoint, although you can use the same data source (for example, Derby) to hold all the event recovery tables.
IDoc status updates
To monitor IDoc processing, you can configure the adapter to update the IDoc status. When the adapter configuration property ALEUpdateStatus is set to true (indicating that an audit trail is required for all message types), the adapter updates the IDoc status of ALE business objects that are retrieved from the SAP server. After the event is sent to the message endpoint, the adapter updates the status of the IDoc in SAP to indicate whether the processing succeeded or failed. Monitoring of IDocs applies only to inbound processing (when the IDoc is sent from the SAP server to the adapter).
The adapter updates a status IDoc (ALEAUD) and sends it to the SAP server.
An IDoc that is not successfully sent to the endpoint is considered a failure, and the IDoc status is updated by the adapter. Similarly, an IDoc that reaches the endpoint is considered successfully processed, and the status of the IDoc is updated.
The status codes and their associated text are configurable properties of the adapter, as specified in the activation specification properties and shown in the following list:
v Success Code v Failure Code v Success Text v Failure Text
Perform the following tasks to ensure that the adapter updates the standard SAP status code after it retrieves an IDoc:
v Set the AleUpdateStatus configuration property to true and set values for the AleSuccessCode and AleFailureCode configuration properties.
v Configure the inbound parameters of the partner profile of the logical system in SAP to receive the ALEAUD message type. Set the following properties to the specified values:
Table 7. Inbound properties of the logical system partner profile
SAP property Value
Basic Type ALEAUD01
Logical Message Type ALEAUD
Function module IDOC_INPUT_ALEAUD