How the connector works

This section describes how meta-data enhances the connector's flexibility, and presents a high-level description of business object processing and event notification.

The connector and meta-data

The connector is meta-data-driven. Meta-data is application-specific data that is stored in business objects and that assists the connector in its interaction with the application. A meta-data-driven connector handles each business object that it supports based on meta-data encoded in the business object definition rather than on instructions hardcoded in the connector. A business object corresponds to a Siebel business component. For more information about business objects, see Using business services

Business object meta-data includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific information. Because the connector is meta-data driven, it can handle new or modified business objects without requiring modifications to the connector code.

Business object processing

This section provides an overview of how the connector processes integration broker requests and application events.

Processing integration broker requests

When the connector receives a request from a business object to perform an application operation, the connector processes hierarchical business objects recursively; that is, it performs the same steps for each child business object until it has processed all individual business objects.

Note:
The term hierarchical business object refers to a complete business object, including all the child business objects that it contains at any level. The term individual business object refers to a single business object, independent of any child business objects it might contain or that contain it. The term top-level business object refers to the individual business object at the top of the hierarchy that does not itself have a parent business object.
Business object retrieval

When an integration broker asks the connector to retrieve a hierarchical business object from the Siebel application, the connector attempts to return a business object to the integration broker that exactly matches the current representation of a Siebel business component instance. In other words, all simple attributes of each individual business object returned to the integration broker match the value of the corresponding field in the Siebel business components.

To retrieve the complete business component, the connector uses the primary key values in the top-level business object received from the integration broker to recursively descend through the corresponding data in the database.

Business object RetrievalByContent

When an integration broker asks the connector to retrieve a hierarchical business object based on values in non-key attributes in the top-level business object, the connector uses the value of all non-null attributes as the criteria for retrieving the data.

Business object creation

When an integration broker asks the connector to create a hierarchical business object in the Siebel application, the connector creates all the children of the top-level business object prior to creating the parent. An exception to this rule is when the relationship between the parent and child is a multi-value link in Siebel and the link is inactive. In this case, the child is created after the parent, and the keys are generated by the Siebel application.

Business object modification

Business object modification, or updating, involves comparing the retrieved after image of the business object from Siebel with the inbound business object. The process involves setting the correct verb on the child objects. If the keys are set on the parent and all other attributes are set to CxIgnore, the parent update is skipped.

The default behavior is to compare the after image from the Siebel applications with the inbound business object, then change the verbs on the child container objects. This process ensures that all the children in the Siebel application are made the same as the inbound business object. If the verb is not set on the children, the default is set to Update.

Important:
If some of the children need to be retained, the inbound object verb must be set to DeltaUpdate, and verbs must be set on each one of the child container objects. In this case, only these objects in the Siebel application are processed while the others are left untouched.
Business object deletion

When an integration broker asks the connector to delete a record, the record is removed from the underlying database. Only the parent needs to be deleted because the Siebel DeleteCascade feature deletes all of the children. If any of the required attributes are missing from the inbound business object, the delete fails.

Exists verb

The primary business component name is typically the same business object name in Siebel. If the ObjectName and ComponentName application specific information match, the keys are set on this business component and the query is executed. If the record exists, it returns True; if the record does not exist, it returns False.

Processing application events

Components

The event notification requires the creation of event and archive tables in the Siebel database. You must create CW Event and CW Archive, two new Siebel business components corresponding to these tables.

Triggering

The creation, update, or delete of any record in the Siebel eBusiness application can be treated as an event. Siebel supports Visual Basic scripts and Siebel eScripts embedded in the Siebel business component event handlers to populate the event table. On a call to pollForEvents, these event records are obtained and processed. The Event business component stores information about the event, as listed in Table 1

Note:
The information in Table 1 is used by the connector during event subscription to build corresponding business objects and to send those objects to the connector framework for further processing.

Table 1. Events business component structure
Fields Description
Object Key The unique identifier that identifies the business object row for which the event was created
Object Name Siebel business object for which the event was deleted
Object Verb Verb for the event
Priority Event priority
Status Event Status Initially, this is set to READY_FOR_POLLOther status values include:IN_PROGRESS=1 -- The event has been picked up and is sent to the connector framework. The connector changes the status of the event to IN_PROGRESS after it picks the event for processing. UNSUBSCRIBED=2 -- The event has not been subscribed for. The connector sets the status to UNSUBSCRIBED if the isSubscribed call returns a False. SUCCESS=3 -- The event was successfully processed by the connector framework. The connector sets the status to SUCCESS if the event is processed successfully by the connector framework.ERROR_PROCESSING_EVENT=-1 -- There was an error processing the event. This status is set if there was an error while processing the event. ERROR_POSTING_EVENT=-2 -- There was an error posting the event to the connector framework. This status is set if the call to gotApplEvent fails in pollForEvents. ERROR_OBJECT_NOT_FOUND=-3 -- The object for which the event was created could not be found. This status is set if the doVerbFor call could not find the object in pollForEvents.
Description Any comment associated with the event
Event Id Id of the event row
ConnectorId Identifies the connector in a multiple connector configuration
Event Ts Event creation timestamp
Create notification

When the connector encounters a Create event, it creates a business object of the type specified by the event, sets the key values for the business object (using the object key specified in the CW Event business component), and retrieves the business object from the Siebel application. After it retrieves the business object, the connector sends it with the Create verb to the integration broker.

Update notification

When the connector encounters an Update event, it creates a business object of the type specified by the event, sets the key values for the business object (using the object key specified in the CW Event business component), and retrieves the business object from the database. After it retrieves the business object, the connector sends it with the Update verb to the integration broker.

Delete notification

When the connector encounters a Delete event, it creates a business object of the type specified by the event, sets the key values for the business object (using the object key specified in the CW Event business component), and sends it with the Delete verb to the integration broker. All values other than the key values are set to CxIgnore.

Retrieving business objects for event processing

Retrieval of objects for event processing is based on both key and non-key attributes. It is mandatory that the business object support the RetrieveByContent verb.

Event management

The connector's event detection mechanism uses a CW Event business component and a CW Archive business component. Because there are potential failure points associated with the processing of events, the event management process does not delete an event from the CW Event business component until it has been inserted it into the CW Archive business component.

The connector polls the CW Event business component at a regular, configurable interval, retrieves the events, and processes the events first by priority and then sequentially. When the connector has processed an event, the event's status is updated appropriately.

The setting of its ArchiveProcessed property determines whether the connector archives an event into the CW Archive business component after updating its status. For more information on the ArchiveProcessed property, see Configuring the connector

Table 2 illustrates the archiving behavior depending on the setting of the ArchiveProcessed property.

Table 2. Archiving behavior
Archive processed setting Event processing status Connector behavior
true or no value Successful Event is deleted from the CW Events business component and archived with status of Success
Unsuccessful Archived with status of Error
No subscription for business object Event is deleted from the CW Events business component and archived with one of the following statuses:Error Processing Event Error Posting Event Error Object Not Found
false Successful Not archived and remains in the CW Events business component with a status of Success
Unsuccessful Event is not archived and remains in the CW Events business component with one of the following statuses:Error Processing Event Error Posting Event Error Object Not Found
No subscription for business object Remains in event table with status of Unsubscribed

Smart filtering

Duplicate events are not saved in the event store. Before storing a new event as a record in the event store, the VB Script or eScript needs to query the event store for existing events that match the new event. The event detection mechanism does not generate a record for a new event in the following cases:

Handling lost connections to the Siebel application

The connector terminates when an error message specified in the ConnectErrors connector property is detected. The text from ConnectErrors in compared with the Siebel error message. If a match is found, the connector returns AppResponseTimeOut, which terminates the connector.

The ConnectErrors message can be returned by the Siebel application if the connection is lost and the connector tries to:

Processing locale-dependent data

The connector has been internationalized so that it can support double-byte character sets, and deliver message text in the specified language. When the connector transfers data from a location that uses one character code set to a location that uses a different code set, it performs character conversion to preserve the meaning of the data. The Java runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the WebSphere business integration system are written in Java. Therefore, when data is transferred between most Server Access components, there is no need for character conversion. To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on these properties, see Appendix A. Standard configuration properties for connectors

Copyright IBM Corp. 1997, 2003