Overview of the Adapter

There are two ways in which the Adapter for Siebel can connect to your Siebel Server:

• Siebel Java Connection: This type of adapter connection uses Siebel's Java Data Bean Business Object Interface (BOI) API to communicate with the Siebel Server. This connection requires that your Windows or UNIX platform supports a JVM that the Data Bean supports. For information about the supported versions, see Installing, Upgrading, and Uninstalling the Adapter for Siebel.
• Siebel Windows Thin Connection: This type of adapter connection uses Siebel's COM Data Control client to communicate with the Siebel Server's Object Manager.

Both connection types use .srf files used by the Siebel Server.

The Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. All adapter services use connection pooling.

A connection pool is a collection of connections with the same set of attributes. The Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections instead of opening new connections.

Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.

Another built-in service, pub.art.service:setAdapterServiceNodeConnection, enables you to change the connection associated with an adapter service. For more information, see Changing the Connection Associated With an Adapter Service at Design Time.

For more information about available services, see the IBM webMethods Integration Server Built-In Services Reference for your release.

From a given business component, it is possible to "walk along" the relationships defined for that component to another component. The path you use to traverse component relationships is called the navigation path. For example, you might want to obtain all addresses for a particular account. In this case, you can traverse the parent/child relationship between Account and Address to obtain those addresses. By using navigation paths, it is possible to traverse nearly all of the business component relationships defined in the Siebel system.

You can navigate from a top-level business component to any other related component. This defines the navigation path that will be taken to reach the selected component. All operations performed by the adapter will traverse this path prior to performing the selected operation. For example, if you want to select account addresses, select Account as the business object in the tree view. From there, navigate to the Address sub-component by expanding the Account view and selecting the Business Address Multi-Valued Link. By choosing this navigation path, you perform an operation on the Address component for a particular Account.

Because a business component represents all records in a particular database table, it is necessary to identify the particular record or records on which you want to perform an operation when moving down the navigation path. You accomplish this by specifying search criteria at each level of the navigation path. For example, you might want to select the addresses for the Account named Acct1. With the Adapter for Siebel, you accomplish this by defining search expressions when you configure the adapter services for your integration.

Occasionally, to properly select the business component instances that will be affected by a given operation, you might need to specify constraints on business components that are not defined along the navigation path (for example, components that exist under the same business object as the selected component, but for which no explicit Multi-Valued Link field relationships exist). You can accomplish this by selecting additional business components under a selected business object. You then can specify search criteria constraints on these components. However, you should almost never need to specify additional business components to add the proper search criteria constraints to your operation. This option is provided for added flexibility. Typically, the use of the navigation path alone should be sufficient.

Adapter services are based on adapter service templates, which are provided with the Adapter for Siebel. Each template represents a specific technique for doing work on a resource. For example, you use the Query template to retrieve specified information from a Siebel business component. An adapter service template contains all of the code necessary for interacting with the resource but without the data specifications. You provide these specifications when you configure a new adapter service.

To configure a new service, you use Designer. First, you assign the service an adapter connection. Then, you select the adapter service template and supply the data specifications using Designer. Some familiarity with using Designer is required. For more information, see the IBM webMethods Service Development Help for your release.

The Adapter for Siebel provides the following adapter service templates:

When creating a Query, Insert, Update, or Delete service, you can select a multi-valued link (MVL) to a child record if the business component you are using is contained in any MVL relationships. The child fields are in a multi-value group (MVG) business component. When a service returns an MVG business component field value, it returns only one value for the field. Siebel recognizes this value as the primary value. This primary value is always stored in the parent business component.

For example, suppose you want to query the primary business address of a particular account. To do this, you configure a query that uses a multi-valued link to navigate from the Account business component to its child business component, Business Address.

MVL relationships are part of a chain; each business component determines which links are available from it. Not all business components have MVL relationships. The MVL relationships between business components are defined within Siebel and cannot be changed using the adapter.

Integration Server provides a built-in service that you can use at design time to change the connection associated with an adapter service. This built-in service, named setAdapterServiceNodeConnection, is provided in the WmART package's pub.art.service folder. Using this service, you can change the specific connection associated with an adapter service at design time so that you do not need to create and maintain multiple adapter services.

For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Other built-in services enable you to control connections. For more information, see Built-In Services For Connections.

Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar backend resources.

For example, a service can be defined to use a default connection that interacts with the Siebel Business Object Interface of Siebel Server. However, at run time you can override the default connection and instead use another connection to interact with the Siebel Business Object Interface of another Siebel Server.

For more information about overriding a service's default connection at run time, see Dynamically Changing a Service's Connection at Run Time.

With versions of the Adapter for Siebel prior to 6.0 SP3, you must configure a connection for each user connecting to the Siebel Server by providing individual user name and password credentials for each connection. For example, if multiple users needed to connect to the same Siebel Server, you were required to configure one connection for each user at design time.

With Adapter for Siebel 6.0 SP3, you can dynamically provide the user name and password credentials associated with a specific adapter service at run time. This capability enables you to override the connection that was associated with the adapter service at design time. If you provide the user name and password credentials in an adapter service at run time, the Adapter for Siebel connects to the Siebel Server using the new credentials, along with the other connection parameters associated with the service's associated connection. If you do not provide any user credentials at run time, the adapter service is invoked using the user credentials provided at design time.

A Query service performs a Siebel Query operation. It retrieves business component records based on one or more fields.

To configure Query services, see Configuring Query, Insert, Update, and Delete Services.

An Insert service performs a Siebel Insert operation. It inserts a business component record with values specified for one or more fields.

To configure Insert services, see Configuring Query, Insert, Update, and Delete Services.

An Update service performs a Siebel Update operation. It updates business component records based on the value of one or more fields. It can update one or more record fields.

To configure Update services, see Configuring Query, Insert, Update, and Delete Services.

A Delete service performs a Siebel Delete operation. It deletes business component records based on the value of one or more fields.

To configure Delete services, see Configuring Query, Insert, Update, and Delete Services.

An Associate service performs a Siebel Associate operation. This service establishes relationships among multi-value group (MVG) business component records.

These associations have a many-to-many relationship. For example, if you are creating orders, and you want to associate line items with the multi-valued link field in the orders, you would associate the line items with the order.

Each level in the navigation path must return a single record. You can associate only those component records that are linked by an association relationship in Siebel.

To configure Associate services, see Configuring Associate Services.

An Attachment service creates an attachment file in a business component record, updates an existing attachment, or obtains an attachment. To do this, at run time you specify that the Attachment service invokes one of the following Siebel methods: CreateFile, PutFile, or GetFile, respectively.

To configure Attachment services, see Configuring Attachment Services.

A Business Service service invokes a Siebel business service on your Siebel Server.

Siebel business services are reusable code modules that perform specified functions while running in the Siebel Object Manager. For example, a business service might perform a tax calculation function. Siebel provides several predefined business services. Alternatively, you can write your own business services using Siebel VB or Siebel eScript.

You can trigger or invoke business services from various contexts within the Siebel environment, including user interface events, Siebel Workflow actions, inbound message requests, and from external applications.

Note the following:

• The data that the Integration Server passes to the Siebel business service must be of the data type String. This data must not be nested. If you need to pass nested data, add the webMethods docToString flow service to your adapter service to convert the nested data into a single string before passing the data. To recreate the nested data in Siebel, add the appropriate logic to your Siebel business service.
• The output that the Siebel business service returns cannot contain nested data. If you need to pass nested data to the Integration Server, use appropriate logic in the Siebel business service to convert the data into a single string before returning the data to the Integration Server. When the adapter service receives the data, use the webMethods stringToDoc flow service to recreate the original nested data structure.

To configure Business Service services, see Configuring Services That Invoke Siebel Business Services.

An Invoke Business Component Method service invokes a Siebel business component method on your Siebel Server.

To configure Invoke Business Component Method services, see Configuring Services That Invoke Business Component Methods.