Event notification refers to the collection of processes that notify the connector of SAP application object events. Notification includes, but is not limited to the type of the event (object and verb) and the data key required for the external system to retrieve the associated data.
Figure 7 illustrates the event notification process, which uses the pollForEvents() method.
Figure 7. Event
notification process
Event notification for the connector consists of two functions:
Event polling consists of three functions that are carried out by the pollForEvents() method:
Event request is the process of polling and retrieving events from the event table in the SAP application. The event request mechanism of the Java component has a counterpart function module in the SAP application, /CWLD/RFC_EVENT_REQUEST. This function retrieves events from the connector's ABAP event table, /CWLD/EVT_CUR.
Every triggered event enters the event table with an initial status of prequeued (status marked as P in the event table) and a default event priority of zero. Before an event can be processed, its status must be changed to queued (Q in the event table). The priority of an event must be zero before the connector retrieves the full object that it represents. For more information on event priority, see ***.
The status of an event changes from prequeued to queued if there are no database locks for the combination of the user who created the event and the event's key. After the event has been retrieved from the event table the status of the event is updated to event retrieved (R in the event table. If locks exist, the status of the event is set to locked (L in the event table) and the event is requeued. An ABAP constant, C_MAXIMUM_REQUEUE, defines of the number of times that an event can be requeued. If the maximum number (defaulted to 100) is attained, then the event is archived to the event archive table.
After preprocessing all prequeued events, the ABAP function module /CWLD/RFC_EVENT_REQUEST selects the events to return to the event request method in the Java component of the connector module (only events with a status of queued can be selected). The connector-specific configuration property PollQuantity (defaulted to 20) determines the maximum number of events returned for a single poll. For more information, see Installing and configuring the connector.
The event request mechanism performs the event selection process in two steps:
Events are dedicated to a specific integration broker in the event distribution table (/CWLD/EVT_DIS). The name of the integration broker specified in this table must match the name specified in the shortcut that starts the connector. For example, the standard shortcut for an SAP connector running on Windows has the format:
...\start_SAP.bat SAPconnectorName integrationBrokerName -cConfigFileName
When a message broker is the integration broker, the WebSphere business integration system identifies the integration broker specified in the event distribution table by getting values from the connector's startup command:
For example, if the connector-specific configuration property PollQuantity is kept at 20 and there are 8 events dedicated to the specific connector and the integration broker, the mechanism selects 12 additional events.
When a message broker is the integration broker and only one Queue Manager has been configured, the names of the queues must be unique for each instance of the integration broker. When a message broker is the integration broker and a cluster has been configured, the names of the queues must be unique for each integration broker within the cluster.
If desired, you can incorporate the name of the broker (as specified in the integrationBrokerName parameter of the startup command) or the name of the connector into the names of the queues. For example, if two brokers are named WMQI1 and WMQI2, their respective ADMINOUTQUEUEs might be named ADMINOUTQUEUE_MQI1 and ADMINOUTQUEUE_MQI2, respectively.
The event request function produces an array of events to be processed from the /CWLD/EVT_CUR event table. It passes these events to the event processing function, which handles them one at a time in the following manner:
If an event is not in the subscription list, sets the status of the event to not subscribed.
After each event is processed by event request, it is returned to the SAP application using function module /CWLD/RFC_EVENT_RETURN. This function module makes a copy of the processed event, adds it to the event archive table (/CWLD/EVT_ARC), and then deletes the original entry from the event table.
Archived events include successfully processed events, events that were processed but terminated in an error, and unsubscribed events. Each event has a status that can indicate one of the following conditions:
Use the IBM CrossWorlds Station tool in the SAP application to administer the event archive table. IBM CrossWorlds Station enables an administrator to display and truncate the archive table and to resubmit events for processing. For more information about maintaining the archive table and setting up log truncation, see Managing the ABAP Extension module.
The connector is event-driven. In order to get events out of the SAP application, you need to implement an event triggering mechanism for each IBM WebSphere-supported business object. Event triggering for the connector comprises three functions:
Event detection is the process of identifying that an event was generated in the SAP application. Typically, connectors use database triggers to detect an event. However, because the SAP application is tightly integrated with the SAP database, SAP allows very limited access for direct modifications to its database. Therefore, the event detection mechanisms are implemented in the application transaction layer above the database.
The IBM WebSphere Business Integration Adapter for mySAP.com commonly uses four mechanisms to detect an event in the SAP application:
All of these event detection mechanisms support real-time triggering and retrieval of objects. In addition, code enhancements and batch programs provide functionality to delay the retrieval of events. An event whose retrieval is delayed is called a future event. For more information on triggering future events, see Event triggering.
Keep in mind that these are only a few examples of event detection mechanisms. There are many different ways to detect events.
Once an event is identified by one of the event detection mechanisms, it is triggered using one of the adapter-delivered event triggers.
If the event will be triggered in real-time, then /CWLD/ADD_TO_QUEUE commits the event to the current event table (/CWLD/EVT_CUR). Specifically, it adds a row of data for the object name, verb, and key that represents the event.
Figure 8 illustrates events triggered by /CWLD/ADD_TO_QUEUE.
If an event needs to be processed at a future date, then /CWLD/ADD_TO_QUEUE_IN_FUTURE commits the event to the future event table (/CWLD/EVT_FUT). Specifically, it adds a row of data for the object name, verb, and key that represents the event. In addition, it adds a Date row which is read by the adapter-delivered batch program /CWLD/SUBMIT_FUTURE_EVENTS. This batch program can be scheduled to retrieve events from the future event table. Once it retrieves an event, it calls /CWLD/ADD_TO_QUEUE to trigger the event to the current event table.
Figure 9 illustrates events triggered by /CWLD/ADD_TO_QUEUE_IN_FUTURE.
Figure 9.
/CWLD/ADD_TO_QUEUE_IN_FUTURE
For more information on triggering events for the future event table, see Developing event detection for the ABAP Extension module.
All events are added to the current event table using /CWLD/ADD_TO_QUEUE. In addition to adding a row of data to the current event table, /CWLD/ADD_TO_QUEUE can be set up for:
Event filtering, event distribution, and event priority are executed as part of the event trigger and by no other program. They result in either the event's restriction (filtering), or modification (event distribution and event prioritization).
Attention: If you are using multiple connectors to poll, you must dedicate every subscribed event to a specific connector. Failure to do so may result in duplicate events delivered. You must guarantee that there is no dependency between objects dedicated to different connectors, because this may result in events being delivered out of sequence.
For example, assume you have a single integration broker named CrossWorlds1 that subscribes to two different business objects, BO_A and BO_B. The BO_A business object is small and can be retrieved quickly whereas BO_B is large and takes much longer to retrieve. With two connectors polling, SAP1connector and SAP2connector, you can set up the event distribution table so that SAP1connector retrieves BO_A and SAP2connector retrieves BO_B. SAP1connector can continuously poll small objects of type A, while SAP2connector focuses on the larger type B objects.
By default, all events are given a priority of zero. An object's priority is configured in the same ABAP table as event distribution.
Figure 10 illustrates the event triggering functionality inside the SAP application. The events E1, E2, and E3 are received by the event trigger /CWLD/ADD_TO_QUEUE. E1 represents a Customer event and E3 represents an Order event. Event distribution is set up so that all Customer objects are handled by SAP1connector and all Order objects are handled by SAP2connector. In this environment, both connectors use the same integration broker. Because E1 is a Customer object, it is polled by SAP1connector and because E3 is an Order object, it is polled by SAP2connector. E2 is an Inventory object that is filtered out by code in the restriction program /CWLD/TRIGGERING_RESTRICTIONS that restricts inventory objects to a specific warehouse.
Figure 10. Event
priority with function module /CWLD/ADD_TO_QUEUE
Once the event trigger inserts an event into the event table, the event is committed to the database with its event distribution and event priority values set. At this time, only polling can modify the event. When the event polling processes is completed, meaning the event was retrieved from the SAP application and processed by the Java component of the connector, a copy of the processed event is added to the event archive table (/CWLD/EVT_ARC). The original event is then deleted from the event table.