IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > Adapter Toolkit > Implementing code from the IBM WebSphere Adapter Toolkit > Inbound event notification > Implementing an event store in the EIS

Event records

There are no hard and fast rules governing the structure or content of an event record in the event store. The goal is to provide enough information for the EventStore interface implementation to successfully generate a business object that represents the event.

Common event record fields
Field Description
Event Identifier (ID) A unique identifier for the event
Object Key The application-specific data that uniquely identifies the entity that occasioned the event.
Business Object Name The type of the business object that maps to the entity.
Verb The operation that triggered this event: create, update, delete, and so on.
Timestamp The time at which the application generated the event.
Status The status of the event. This is used by the Foundation Classes to track which events are new, in process, or processed.
XID The transaction ID.


Event Identifier (ID)

Each event requires a unique identifier for tracking purposes. This identifier can be a number generated by the application or a number generated by a scheme that your adapter uses. The event might generate a sequential identifier, such as 00123, to which the adapter adds its name. In such an event ID numbering scheme, the resulting object event ID is MyAdapterName_00123. Another technique might generate a timestamp to identify an event, producing an identifier such as MyAdapterName_06139833001005.


Object Key

Each event should contain enough key information to enable the adapter event-retrieval mechanism to locate and retrieve the full entity in the EIS for which this event was originally recorded. The structure and content of this key is up to you.

For reference, a key is typically consists of easily-parsed values such as name-value pairs.

For example, Customer_ID=123 or, for a composite key, Model=Widget;Color=CanaryYellow.


Business Object Name

Since the EIS entity identified in each event is converted to a business object instance, the type of the business object must either be specified or derivable at run time by the event-retrieval mechanism.

The most straightforward approach is to include the business object name value in the event record. Specifically, the business object graph type should be included; for example, CustomerBG or OrderBG.

The namespace, which is also required for business object creation, need not be included in the event; the namespace is user-defined and should be retrieved by the adapter from the adapter ActivationSpecWithXid instance.

If, as an adapter developer, you choose to derive the business object graph type, you are strongly advised against mandating any specific EIS entity name to business object type mapping schemes. Business object properties and names are unreliable because they can be modified by users. To avoid such problems, adapters should always process business objects using metadata.


Verb

The verb should reflect the operation that this event represents.

For example, if this event reflects the creation of an entity in the application, the verb would be Create. This value should be one of the standard verbs used by adapters (including Create, Retrieve, Update, Delete) and specified in the business object generated for the event. When properly specified in the business object, the verb allows consumers of the business object event to determine what action to take on the event.

The default function selector implementation (WBIFunctionSelector) uses the verb passed in the event business object to determine the appropriate SCA EIS import operation. Be sure that verbs used here correspond to the operations defined by your adapter enterprise metadata discovery implementation.


Timestamp

The Foundation classes use the timestamp to ensure proper ordering of events.

For example, use of a timestamp prevents an event describing the deletion of an Order from being published before an event describing the creation of that same Order. The timestamp should provide detail sufficient to distinguish events occurring close in time.


Status

The event status is used to track the state of an event. It allows the Foundation Classes to distinguish among events that are new from those in process or ineligible.

The adapter must support five different event status values as described in the table below. All events generated by the event detection mechanism in the EIS should be in the initial state of New. Only the Foundation Classes, through the EventStore.updateEventStatus method, change event status.

Possible Event Statuses
Event Status Description Foundation Class Constant
New The event is ready to be processed. NEWEVENT
In Progress The adapter is processing this event. If that an event in this state may or may not yet be delivered. INPROGRESS
Processed The adapter successfully processed and delivered the event. PROCESSED
Failed The adapter was unable to process this event due to one or more problems. FAILED
Unsubscribed The adapter processed the event but found no interested subscribers UNSUBSCRIBED


XID

The XAResource uses this string field to track transaction IDs in the event table. The adapter queries and updates that XID field. During recovery, WebSphere Application Server calls the resource adapter, queries it for XAResources, and then performs transaction recovery based on the XID.

Implementing an event store in the EIS