Export (0) Print
Expand All

Microsoft BizTalk Adapters for Siebel

Large companies today are filled with disparate systems containing overlapping functionality. Companies frequently support separate systems to handle manufacturing, financials, human resources (HR), and customers. Those companies that are disciplined enough to run on a single vendor’s line of business (LOB) applications are not necessarily better off than those running on applications from multiple vendors. It is likely that the vendor gained the application suite through acquisitions, and supports only custom integration between the individual applications.

Even companies that run on a single Enterprise Resource Planning (ERP) system that also handles HR and Customer Relationship Management (CRM) data are rarely able to handle the custom requirements of each organization. The result is that millions of dollars are spent on customizing the LOB application or developing an entirely separate application (a satellite system) to handle the custom functionality. (The advantage of creating a satellite system is that it is significantly easier than dealing with the LOB version upgrade problems that accompany the modification of source code in an LOB application.) Regardless—whether a company has multiple LOB applications, a plethora of satellite systems, or both—the data between systems needs to be sourced from a single master and synchronized across each application. Otherwise, the data becomes stale and worthless. Data synchronization is one of the problems that Microsoft® BizTalk® Server is designed to address, and with the addition of the LOB adapters in BizTalk Server 2006, applications such as PeopleSoft, JD Edwards, and Siebel can be smoothly integrated.

ERP Systems

ERP systems are a type of LOB system. In their early form, they were sold as a “magic bullet” solution to integrating an enterprise’s business, people, and processes. ERP systems were popularized in the 1980s and 1990s with the intention of integrating multiple business functions into a single application platform. Built by the likes of Oracle, PeopleSoft, JD Edwards, Siebel, SAP, and Baan, these ERP systems created application silos bounded by each vendor’s proprietary application technology. Inevitably there was a need to integrate ERP systems with each other or with other systems that provided additional functionality.

Figure 1: Typical LOB system integration scenario (partial integration)
Bb820919.c1cd4677-1e4f-4de4-b0a0-41cbe4746fa1(en-US,BTS.10).gif

Figure 1 depicts typical scenarios in which LOB system integration occurs with seemingly ad-hoc integration links needed to keep data synchronized. These include mergers and acquisitions that result in two companies, running two different ERP systems that must share data through synchronization or real-time exchange. Another scenario where such integration occurs is when new systems are introduced with functionality not available within the ERP systems. For example, the implementation of a custom e-commerce system introduces the need for the customer to enter a sales order into the corporate Order Management System (OMS) in near-real time. Still another example is when there is no centralized organizational application strategy (due perhaps to “political boundaries” or to improper management), resulting in departments within the same company using different systems.

Integration and Interoperability

The need for integration prompted the need for external, or integration-based, APIs from ERP vendors. However, the APIs produced were clunky, proprietary, and required very specialized skill sets. The need for standards-based adapters based on a common pattern was apparent, and several vendors went to work to create adapter frameworks that would allow a developer to learn a single API for creating software to integrate with multiple ERP platforms. Some adapter vendors took this a step further to create adapters that were ready to use with integration platforms such as BizTalk Server 2006.

Figure 2: Typical integration scenario designed by using BizTalk Server and LOB adapters
Bb820919.35466ec2-2a36-4684-b982-a14cdc0b2a61(en-US,BTS.10).gif

This allows BizTalk Server to be used as a centralized integration broker, as shown in Figure 2, reducing the need for point-to-point or custom integrations between two systems. BizTalk Server 2006 provides a diverse set of LOB adapters to facilitate the exchange of information between a variety of ERP systems, and other external data repositories, through the use of a common technology. We will summarize important high-level technical points about the LOB adapters throughout this white paper.

Purpose and Advantages

The purpose of the LOB adapters is to enable companies to leverage their existing investments in their enterprise application infrastructure while mitigating risks inherent to integrating business systems. The following paragraphs discuss some advantages of using the adapters.

Reuse of Existing Business Logic

A common integration challenge faced by companies today is that much of their investment in the design and development of business logic cannot be leveraged when interfacing directly with the underlying databases. Use of a data transformation utility such as Data Transformation Services (DTS) or SQL Server™ Integration Services (SSIS) can often lead to data exchanges that violate critical business rules because these rules are implemented in application logic, and not in the databases. This also undermines the investment made in the LOB system’s business logic. By communicating directly with the LOB system at the database level, it is possible to introduce data that will be misinterpreted by the LOB system.

“Application adapters” allow integration platforms to interface with the “business logic layer” of the LOB system using each system’s proprietary interface mechanisms. By using application adapters, IT departments can create integrations that will exchange data while still adhering to the critical business rules that have been programmed into the business logic layer.

Specifically with BizTalk Server 2006, the Adapters for Enterprise Applications (the “LOB adapters”) enable run-time application integration while also providing key design-time functionality. BizTalk Server ports are configurable for connections to multiple instances of the LOB systems. “Wizards” are used in the Microsoft Visual Studio® .NET development environment to browse business object metadata and generate XSD schemas and orchestrations that can be consumed as part of the BizTalk Server development cycle.

Reduced Development Cost

Because the BizTalk Server LOB adapters communicate directly with the existing business logic layer on the LOB system, additional components that would otherwise be duplicated as part of an integration effort are not needed. Companies can avoid having to develop components for their integration projects that mimic the logic that already exists on the LOB systems.

Lower Change Management Risk

Eliminating the need for duplicated business logic greatly reduces the risks associated with managing changes to the LOB systems and any dependent systems. For example, if you have seven different processes all using distinct versions of the same business logic, a change in one could necessitate a change in all. However, it is possible that not all seven processes would be modified correctly or at all. Even if the changes were properly completed, imagine the resources expended in making the same change repeatedly or inaccurately.

This section provides information about the architecture.

Component/Package View of LOB Adapters

The LOB adapters consist of several components. You will find many of these processes running in Task Manager as you use the design-time and run-time components of the adapters:

  • Adapter Framework – The adapters are built on the BizTalk Server Adapter Framework. The Adapter Framework is a set of extensible APIs that enable developers to take advantage of relevant services of BizTalk Server when building adapters and connectors that integrate third-party applications. For more information, see How the Adapter Is Designed: The Adapter Framework.
  • Java Runtime – The Adapter Framework, which is used by the LOB adapters, is dependent upon the Java Runtime (version 1.4.3 or later).
  • Browser Agent – This process is used by the Adapter Framework and invoked by Visual Studio .NET. It retrieves and formats metadata from the LOB systems into XSD files that the BizTalk Server development environment can then consume and use. After five minutes of inactivity, it automatically shuts down to release any resources, such as memory, that may have been used. This process appears in Task Manager as browsingagent.exe.
  • Runtime Agent – This process is used by the Adapter Framework and is invoked by the BizTalk Server runtime (BtsNtSvc.exe) to call business functions on the LOB systems. Unlike the Browser Agent, the Runtime Agent does not shut down after a period of inactivity. This process appears in Task Manager as runtimeagent.exe.
  • Connectors, JAR files – JAR files contain the set of Java classes specific to the LOB system. The Adapter Framework exposes these classes as Java interfaces, which are used to communicate with the BizTalk Server design-time and run-time executables.
Figure 3: LOB adapter process flow
Bb820919.ef291557-9aaf-462c-87f8-0ff148f9bcb2(en-US,BTS.10).gif

Figure 3 shows the high-level architecture of both the design-time and run-time components and how they interface with the LOB adapters and the LOB system.

The Siebel adapter closely follows the general architecture of Figure 4. However, there are multiple integration points into the Siebel architecture that should be considered when designing your integration infrastructure.

Siebel Architecture

Siebel supports a client/server architecture. As such, it is available through many different types of clients, including thin clients such as ActiveX®, Java, and the Web browser (see Figure 5).

Figure 4: Siebel client/server architecture
Bb820919.b600f851-6e23-408d-af35-bcfe8ee4d061(en-US,BTS.10).gif

Because Siebel supports a client/server architecture that includes an application server running on top of the database, the best location for an integration point is the Siebel application server, preferably through the gateway server. As discussed earlier, this enables business logic and validation to be communicated directly to the underlying database, thereby enhancing security and data integrity.

Figure 5: Siebel integration points
Bb820919.f4e17372-4461-499a-947a-37b76e7e769c(en-US,BTS.10).gif

The integration architecture offered into the application server layer offers several connection mechanisms as shown in Figure 5. Except for perhaps CORBA and Java Beans, most of these mechanisms are readily available from BizTalk Server 2006. And, by using the Siebel adapter, Java Beans can also be added to the list.

The Siebel LOB Adapter

By using the Siebel LOB adapter, you can use Siebel Business Objects and Business Services. As shown in Figure 6, Business Objects are entities that consist of one or more Siebel Business Components. Each Business Component can provide access to columns from multiple tables from within a single container. This is very similar to a data recordset. Siebel Tools allow you to define how data is inserted, updated, selected, and deleted from the associated tables. These options are defined in further detail later in this document (see Business Components – Standard Methods). Business Services provide access to business-layer or user-defined methods for use during integration.

Figure 6: Business object hierarchy
Bb820919.2763929a-e87f-4968-af0b-fbec808fbeb4(en-US,BTS.10).gif

As is the case with the general BizTalk LOB adapter process flow, the Siebel LOB adapter connects BizTalk Server to the LOB application servers by using Java DataBean classes (see Figure 7). Furthermore, the Siebel Internet SessioN API (SISNAPI) protocol is used to communicate with the Siebel Object Manager. SISNAPI is a session-based remote procedure call (RPC). The result is a Siebel connection from BizTalk Server using that standard integration LOB development paradigm, which can generate the API schemas and use them within BizTalk Server 2006 mapping and orchestration facilities at design time and run time.

For more information, see Architecture of BizTalk Adapter for Siebel eBusiness Applications.

Figure 7: BizTalk Server 2006 Siebel LOB adapter process flow
Bb820919.ba8e7c84-43ec-4fa7-a7c4-b75f8fd49f88(en-US,BTS.10).gif

At design time, the Siebel LOB adapter crawls through the exposed Business Objects and Business Services and then exposes a listing of APIs within the BizTalk Server 2006 Add Adapter Wizard (see Figure 8).

Figure 8: Generating Siebel schema by using the Add Adapter wizard
Bb820919.83732a7c-6b1c-40b2-940f-7ed5894faed3(en-US,BTS.10).gif

It is important to realize that although BizTalk Server 2006 is built on the Microsoft .NET Framework, the connection of the Siebel LOB adapter into the Siebel application uses Java. This is especially evident when configuring the port because it is necessary to reference several JAR file locations in addition to the Siebel connection information.

Figure 9: Siebel LOB adapter architecture
Bb820919.fb47f23f-c8b7-424f-b985-891d1c696c62(en-US,BTS.10).gif

A key item to note in the Siebel LOB adapter architecture (see Figure 9) is that it facilitates calls into Siebel only – send handlers. It does not also receive notifications directly out of Siebel into BizTalk Server – receive handlers. However, the adapter supports scenarios that are initiated from outside the Siebel application, even when those scenarios are retrieving data. As long as the calling application has the necessary lookup information when calling the corresponding API, the Siebel LOB adapter is well suited for requesting data from Siebel.

Unfortunately, the adapter is not suited for notifications out of the Siebel application. There simply is not a receive handler within the Siebel LOB adapter. As a result, if a customer signs into the eCommerce layer of Siebel and updates their account information, the Siebel LOB adapter cannot receive a callback from Siebel and push the updated information into another system. The infrastructure for solving this problem does not rely on the Siebel LOB adapter, but rather is provided through one of the other connection mechanisms shown in Figure 5 – namely MSMQ, CORBA, COM (DCOM), HTTP, MQSeries, or the Windows® file system.

Alternatively, a connection could be set up directly with the database by using staging tables that are populated from the Siebel application tables through the use of triggers. The important thing to note is that only a read-only view of the Siebel tables is needed, thereby avoiding the negative impact of not going through the Siebel application server and circumventing any data integrity. Unfortunately, this may not sufficiently handle data security concerns, forcing custom Siebel code to be implemented instead. Further discussion of a Siebel receive handler appears later in this paper.

Integration Strategies

The goal is to communicate with the Siebel application. As with many ERP systems, it is necessary for data to flow bi-directionally. Options for importing data into, as well as exporting data out of, Siebel are provided below.

Design Pattern: Receive Handler - from Siebel to BizTalk Server

The Siebel LOB adapter does not provide an option to extract data directly out of Siebel through the standard receive port process, so the use of an alternate adapter is required. Fortunately, BizTalk Server offers a variety of “out-of-the-box” and LOB adapters that can assist in this process, including file-based adapters, database adapters, and Web service adapters. While the Siebel LOB adapter does not handle retrieving data from Siebel directly, the send handler can be used to initiate a request for information provided that the appropriate requesting parameters are available.

File-Based Integration

Siebel offers automated processes that generate flat-file documents of various content and format. The EAI Siebel adapter can execute the necessary Business Service that produces an XML document, which is passed to the EAI file transport to be written to a specific directory. A Siebel developer will be required to assist in the setup and scheduling of this effort. After the files are generated, either the BizTalk File or FTP adapter can be used to monitor for the existence of these messages. Additionally, the Siebel File System Manager component allows Web clients to upload or download files directly.

Figure 10: Receiving Siebel files
Bb820919.149829c3-f92d-435b-98f0-f295c6a3325e(en-US,BTS.10).gif
Database-Level Integration

Siebel can be installed on a variety of database servers: Oracle, IBM DB2, Microsoft SQL Server, and Sybase. BizTalk Server comes with several adapters that can communicate with many of these DBMS platforms, and third-party adapters are available for others.

The BizTalk Server Oracle Database, Host Integration Server DB2, and SQL Server adapters provide options to execute SQL statements, call stored procedures, or monitor tables for specific changes. One of the advantages of this option is that developers are commonly familiar with database structures regardless of their platform. This familiarity can reduce the reliance on the availability of a Siebel developer. However, there are some security concerns to keep in mind when using this approach. It is recommended that a limited-access database account be created specifically for integration. This database account should only have access to those tables and objects necessary for integration. While read-only access is preferred, it is often impractical due to the requirement to change the state of the data to reflect integration.

Figure 11: Database extraction
Bb820919.97537c25-2a68-47cb-864b-07477cf49676(en-US,BTS.10).gif
Web Services-Based Integration

Siebel provides the ability to expose Business Services as Web services that can be used to assist in the integration process. By using the BizTalk HTTP or SOAP adapter, BizTalk Server can communicate with a variety of Siebel Business Services. To establish a receive handler using Web services, a Siebel developer will be required to create code that calls out to BizTalk Server.

Figure 12: Receiving Web service requests
Bb820919.8c3cf899-d207-48aa-ac8c-70f7095eafb4(en-US,BTS.10).gif

Design Pattern: Send Handler – from BizTalk Server to Siebel

In contrast to receiving data from Siebel, the BizTalk Siebel LOB adapter does allow you to push data to the Siebel application server. While this may be the most practical approach, it is not the only option available. As referenced above, there are many options for importing data into Siebel. BizTalk Server provides a variety of adapters to facilitate the use of these integration points.

Siebel LOB Adapter

BizTalk Server provides the Siebel LOB adapter specifically for communicating with the Siebel server. Through the use of the Siebel LOB adapter, developers can execute many of the Siebel Business Objects and Business Services. This allows interaction directly with the Siebel application servers while requiring minimal involvement from a Siebel developer. After the Siebel server has been properly configured for BizTalk Server, you are ready to begin integration development. See Adapter Configuration and Interface Development for more information about how to configure your send port.

Figure 13: Use of Business Objects
Bb820919.812a9fd4-99d6-49c6-9d4a-e4bda2cebcf7(en-US,BTS.10).gif
File-Based Integration

This is probably the most basic method of integration. The EAI Siebel adapter accepts properly formed XML files. By using the BizTalk File and/or FTP adapters, you can transport files in the predefined format for integration. Siebel receives the XML message and processes it through the EAI XML converter, which transforms the XML to a valid Siebel message to be sent to the EAI Siebel adapter. A Siebel developer will be required to assist in the setup and scheduling of this effort. By harnessing the power of BizTalk Server message manipulation, BizTalk Server can easily extract data from an external system, convert it to the predefined format, and send it to Siebel for processing.

Figure 14: Use of the application engine
Bb820919.747b961f-a4d1-49c3-8f49-a1a9924e602e(en-US,BTS.10).gif
Web Services-Based Integration

As mentioned above, Web services can be used for publishing data to Siebel. The BizTalk HTTP or SOAP adapters can easily be configured to communicate with Siebel in this fashion. Once again, the assistance of a Siebel developer may be required.

Figure 15: Use of Web services
Bb820919.a258eb79-b155-49d0-bb23-7d961ffae135(en-US,BTS.10).gif
Database-Level Integration

Similar to extracting data from Siebel, you can use the BizTalk database adapters to insert or update data directly on the Siebel database server. Again, it is recommended you use a database account created specifically for integration. However, unlike data extraction, you will be modifying the data directly. This option should be looked at very closely because there are many dependencies associated with relational databases. Simply inserting an employee record may seem to be a trivial step, while in reality; Siebel creates multiple records across multiple tables to perform this process. Developers should take this approach only as a last resort and should use extreme caution when altering the underlying data directly.

Figure 16: Database connection in to Siebel
Bb820919.362da929-a0c1-435d-9bc4-e81ba3f8a2fd(en-US,BTS.10).gif

This section provides development-oriented instructions for configuring the Siebel adapter and generating the schema for the send port.

Send Port Configuration

To use the BizTalk Siebel LOB adapter, you must have a properly configured send port. The send port contains various configuration properties that determine how messages are processed to successfully connect to the target system—in this case Siebel. Although several properties are common across all send ports; some are uniquely defined based on the type of adapter being used. For the Siebel LOB adapter, it is necessary to configure the transport properties as well as the pipelines before the adapter will work either at design time or at run time.

Transport Properties

The adapter uses transport properties (see Figure 17) to connect to Siebel. One important characteristic to note about these transport settings is that the values are case sensitive. Take care when specifying the properties.

Figure 17: Send port transport properties
Bb820919.f814f0bf-f02d-416d-b5f2-51dfad358790(en-US,BTS.10).gif

The following table describes the transport properties that the adapter requires.

Transport Property Description / Example

Application Server

The name of the server where Siebel is installed. The application server contains all of the metadata for the Siebel eBusiness Applications system. This is the metadata that defines the Business Services and Business Components within the Business Objects.

Example: SiebelSrv

This is required only for versions prior to 7.7.

Gateway

The name of the computer hosting the Siebel Gateway. The port number can be provided to further define the gateway, but this value is not required. The default port is 2320.

Example: SiebGateway or SiebGateway:2320

The gateway knows the name of the server and manages user authentication.

JAVA_HOME

The location where the JDK was installed.

Example: C:\j2sdk1.4.2_10.

This value is required only if you do not include this value in your PATH environment variable. For instructions on this process, see Updating Environment Variables in the appendix.

Object Manager

The name of Siebel’s Object Management server.

Example: SiebObjMgr

Password

The user’s password used to access the Siebel system. The characters do not appear but are represented by asterisks (*).

This is required only if you are not using Enterprise Single Sign-On (SSO).

Repository Name

The name of the Siebel Repository to be accessed.

Example: Siebel Repository

The Siebel Repository contains information about the Business Objects and Business Services.

Siebel JAR Files

The location of the Siebel JAR files.

Example: c:\Jars\SiebelJI_enu.jar; c:\Jars\SiebelJI_Common.jar; c:\Jars\SiebelJAccess.jar;

Two of the JAR files are specific to the Siebel version and are located on the Siebel server. The SiebelJAccess.jar file is located in the location where the BizTalk Enterprise Adapters were installed (i.e. C:\Program Files\Microsoft BizTalk Adapters for Enterprise Applications\Siebel eBusiness Applications\Classes\SiebelJAccess.jar).

However, if you updated your CLASSPATH environment variables with the location of the JAR files, this step is optional. For instructions on this process, see Updating Environment Variables in the appendix.

Siebel Version

The version of the Siebel eBusiness Application server. Current versions supported include: 7.0.x, 7.5.x, and 7.7.x.

Siebel’s Enterprise Server Name

The name of the enterprise server. This is a logical entity that represents the Siebel server(s) and Gateway server.

Example: Siebel

User Name

The user’s login name used to access the Siebel system.

This is only required if you are not using SSO.

In addition to the required parameters, there are several other transport type options that you can modify based on your communication needs. Some are specific to the Siebel adapter while others are common to BizTalk send ports.

Transport Property Description / Example

Max Concurrent Calls

This value specifies the maximum number of concurrent calls that can be made on this send port. If the number of calls exceeds this value, the additional requests will become dehydrated until processing threads become available. –1 indicates an unlimited number of calls.
To prevent exceeding the processing capacity of the Siebel server, it is recommended this value be set between 1 and 10.

Connection Timeout

This value specifies how long, in minutes, the adapter will wait for a response from the Siebel server. The main purpose of this property is to prevent deadlocked processes. The default value is 30, but must be set between 10 and 300. A higher value should be chosen if your network has a high load.

Login Timeout – This value specifies how long, in seconds, the adapter will wait when attempting to log on to the Siebel server. The default value is 20, but can be set anywhere between 1 and 300.

Event Log Level

This is the level of events that are to be recorded as they are encountered. The default value is Error. Possible values are Info, Warning, and Error.

Refresh Agent

When Yes is selected, the runtimeagent.exe and the browsingagent.exe processes will be restarted automatically as required

Affiliate Application

This value is created by Enterprise Single Sign-On tools and is used to represent an external application. The user credentials are stored in the SSO Credential database.

Use SSO – This value determines whether SSO is to be used or not.

Setting Pipelines

The Siebel adapter requires that the send and receive pipelines use the default XML pipelines of XML Transmit and XML Receive respectively.

Business Components - Standard Methods

The Siebel LOB adapter contains a set of standard methods used to communicate with the Siebel Business Components. The methods are Delete, DeleteEx, Insert, InsertEx, Query, QueryEx, QueryEx2, QueryWithViewMode, Update, and UpdateEx. The *Ex methods activate all of the fields and the QueryEx2 method allows you to turn on or off the activate feature.

Delete and DeleteEx

The Delete and DeleteEx methods allow you to delete a list of records based on a set of record IDs. The syntaxes for these methods are Delete(rowIDList) and DeleteEx(rowIDList, viewMode, preLoad).

  • rowIDList: This value is represented by an array of strings. Each record ID is a string.
  • viewMode: If the Business Component is not assigned to the user performing the requested action, the action will fail. The viewMode can override the permission roles. The viewMode can be set by the Siebel administrator for each Business Component. Siebel provides four levels of views for Business Components:
    • 0 – Sales Rep
    • 1 – Manager
    • 2 – Personnel
    • 3 – All
  • preLoad: This is a sequence of records that are to be loaded before the execution of the method. This value is optional. If values exist, the records will be loaded in sequential order. At times, Business Component records are linked to other Business Component records. These linked records must be loaded in order to reference some of the “parent” values.
    The preloaded values are stored in a structure called preLoadStructType. The preLoadStructType consists of the following fields:
    • preLoadCompName – This is a string.
    • preLoadSearchExp – This is a string. If more than one record is returned based on the preLoadSearchExp, the first record will be used.
    • activateFieldName – This is a sequence of fields to be activated.

Insert and InsertEx

The Insert and InsertEx methods allow you to create a new record within a Business Component. A set of record IDs are returned upon a successful execution. The syntaxes for these methods are Insert(recordset) and InsertEx(recordset, viewMode, preLoad).

  • recordset: This is a set of records to be inserted.
  • viewMode and preLoad act as described above.

Query, QueryEx, QueryEx2, and QueryWithViewMode

The Query, QueryEx, QueryEx2, and QueryWithViewMode methods are used to retrieve records based on the provided search criteria. The syntaxes for these methods are Query(searchExpression, sortExpression), QueryEx(searchExpression, sortExpression, viewMode, preLoad), QueryEx2(searchExpression, sortExpression, viewMode, preload, activateField) or QueryWithViewMode(searchExpression, sortExpression, viewMode).

  • searchExpression: This is a value used to find the specified records. This is very similar to an SQL WHERE clause. For example: [Name] like “Acme*” would return a set of records where the name begins with “Acme”. It may also be necessary to use escape sequences when using special characters such as \\ and \”. See your Siebel documentation for further details.
  • sortExpression: This is a comma-separated list of columns to determine how the data will be returned. By default, the records will be sorted in ascending order. For example: State, City.
  • viewMode and preLoad act similarly as described above.
  • activateField: This is a string value that identifies those fields required for the query.

Update and UpdateEx

The Update and UpdateEx methods allow you to update records within a Business Component. The syntaxes for these methods are Update(recordset) and UpdateEx(recordset, viewMode, preLoad).

  • recordset: This is a set of records to be updated.
  • viewMode and preLoad act similarly as described above.

Metadata Generation

After a Siebel LOB adapter send port has been created and configured, and the necessary Siebel Business Objects and/or Business Services have been identified, you can use the Add Adapter Wizard to add the necessary schema(s) to your BizTalk project. Metadata defines the structure in which data will be interfaced with Siebel. The Add Adapter Wizard generates the XML schema for a given Siebel Business Object or Business Service.

From within your BizTalk project, you can access the Add Adapter Metadata Wizard by clicking Add Generated Items on the Project menu. From here, you select the Add Adapter Metadata schema files node on the left side of the dialog box (Figure 18) and the Add Adapter Metadata option on the right side of the dialog box. After you are prompted with the Add Adapter Wizard screen (Figure 19), you will select the Siebel eBusiness Applications adapter from the list provided. The SQL Server and Database values are specific to your BizTalk Server configuration. The Port list displays only a list of ports configured to use the registered adapter you selected, in this case the Siebel eBusiness Applications adapter, which only appears after configuring the send port as described in the previous section.

Figure 18: Add Generated Items
Bb820919.b1231fd4-23c7-468b-998a-976d61c2eae8(en-US,BTS.10).gif

If you determine you need to alter (or add) the configuration of the send port, you must exit the wizard before the applied changes will take effect.

Figure 19: Add Adapter Wizard – adapter selection
Bb820919.1795c185-cc9e-47b6-bd3e-fffefce8667d(en-US,BTS.10).gif

After you have selected the necessary adapter and port information, you will be presented with a list of Siebel Business Objects and Business Services. The Add Adapter Wizard refers to the Siebel Business Objects and Business Services as “services” because this wizard is used for multiple LOB adapters. You can select as many Siebel Business Components, upon expanding the list of Business Objects, and Business Services as necessary, but at least one Siebel Business Component or Business Service must be selected to continue successfully.

Figure 20: Add Adapter Wizard - Business Object and Business Service selection
Bb820919.2c9c671e-7f56-4e82-bbf7-365a0f30cbf3(en-US,BTS.10).gif

After you have selected the Siebel Business Components and/or Business Services, the Add Adapter Metadata Wizard begins generating XML schemas that define the format for data interchange.

Typically, four schema files are generated for each Siebel Business Component: Business Object, Service, Object Level, and API definitions. Two schema files are typically generated for each Business Service: Object Level and API definitions.

  • Business Object definition XSD (e.g., EmployeeService_Business_Objects.xsd) – This schema contains the definitions for the Query, Insert, Update, etc. requests and responses used by the primary schema. This schema is referenced in the “Imports” collection of the primary schema.
    Figure 21: Business object definition schema
    Bb820919.c2588417-e8e0-4a8a-8bc3-3da6d6fc219a(en-US,BTS.10).gif

  • Service definition XSD (e.g., EmployeeService.xsd) – This schema contains the definitions for the Query, Insert, Update, etc. requests and responses used by the primary schema. This schema is referenced in the “Imports” collection of the primary schema.
    Figure 22: Service definition schema
    Bb820919.5192f3a9-1a0b-46cb-a25d-5288a6250f99(en-US,BTS.10).gif

  • Object level definition XSD (e.g., EmployeeService_obj.xsd) – This schema contains any object-level definitions and is referenced in the “Imports” collection of the primary schema.
    Figure 23: Object level definition schema
    Bb820919.2273135d-a7b3-40cf-8408-3b4ee1a1ea80(en-US,BTS.10).gif

  • API metadata definition XSD (e.g., EmployeeService_Employee_x5d.xsd) – This is the primary schema for the Siebel Business Component and/or Business Service and contains multiple root-level nodes that expose the various APIs and methods available to the Siebel Business Component and/or Business Service.
    Figure 24: API metadata schema
    Bb820919.49e1fc48-fefc-4b4e-97ec-30d4d3a2168c(en-US,BTS.10).gif

Orchestrations vs. Content-Based Routing

Due to the nature of the Siebel Business Components and Business Services, it is common for multiple synchronous transactions to be executed for a single integration. For best performance, it is recommended to use Content-Based Routing (CBR) to avoid the overhead produced by orchestrations. CBR allows you to transmit messages based solely on the properties of the messages or ports. However, when using CBR it becomes difficult to encapsulate the complete integration inside a single transaction. Without the use of transaction-based integration, you lose a level of error handling that is required to ensure data is properly sent and received, possibly multiple times, during the interface. By using orchestrations, you can better control the flow of data and easily capture and handle any errors that may occur. Orchestrations also provide the ability to use a Scope shape, which simulates a try/catch block. As shown in Figure 25, scopes can have multiple exception handlers that allow you to take a specific course of action based on the error encountered.

Figure 25: Sample orchestration with multiple exception handlers
Bb820919.63bf8452-6e29-4a49-a2a0-bfbae1dae145(en-US,BTS.10).gif

Integration Example

This example attempts to demonstrate a simple process that uses the Siebel LOB adapter to update a user’s profile. This process is roughly outlined in Figure 26.

The Business Component utilized is Siebel’s Employee Business Component under the Account Business Object. In this example, the orchestration receives a Siebel employee ID and updated e-mail address in the form of an XML file. The orchestration transforms the inbound message to a valid Update request and sends it to a send port configured for the Siebel LOB adapter. The send port will execute the request and return a response from the method. The response message will then be written to an archive file. If any errors occur during the process, they will be written to a file and the process is stopped.

Figure 26: Process flow chart
Bb820919.692c7f38-e6ad-4eab-8d1a-a538a00c3296(en-US,BTS.10).gif

This example requires the use of an orchestration in order to properly handle any errors which may occur. By implementing a Scope shape, we can catch and manage any exceptions. If a failure occurs along the Siebel send port, errors can be reported using a Fault message. In this example, the errors will be written to an error file.

Figure 27: Sample orchestration
Bb820919.f22160e1-7c1a-436d-8452-05e80071be9a(en-US,BTS.10).gif

Sample Input [Good Data]:

<ns0:Root xmlns:ns0="http://SiebelWP.Schemas.UserInfo">
    <User Id="1-3ZSN9" EmailAddress="test@test.test" />
</ns0:Root>

Sample Update Request:

<ns0:Update xmlns:ns0="http://schemas.microsoft.com/[Siebel://Business Objects/Account/Employee]"     xmlns:exposed="http://schemas.microsoft.com"    xmlns:Business_Objects="http://schemas.microsoft.com/Business_Objects">
    <ns0:EmployeeUpdateRecordSet>
        <Business_Objects:EmployeeUpdateRecord>
            <Business_Objects:Id>1-3ZSN9</Business_Objects:Id>
            <Business_Objects:EMail_Addr>test@test.test</Business_Objects:EMail_Addr>
        </Business_Objects:EmployeeUpdateRecord>
    </ns0:EmployeeUpdateRecordSet>
</ns0:Update>

Sample Update Response:

<Employee:UpdateResponse xsi_2001:nil="1" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:exposed="http://schemas.microsoft.com" xmlns:xsi_2001="http://www.w3.org/2001/XMLSchema-instance" xmlns:Employee="http://schemas.microsoft.com/[Siebel://Business Objects/Account/Employee]" /> 

Sample Input [Bad Data]:

<ns0:Root xmlns:ns0="http://SiebelWP.Schemas.UserInfo">
    <User Id="" EmailAddress="test@test.test" />
</ns0:Root>

Sample Fault Message:

<?xml version="1.0" ?> 
<string>Microsoft.XLANGs.Core.XlangSoapException: An error occurred while processing the message, refer to the details section for more information Message ID: {A25AAB9B-C987-4087-90E4-63AD958DF406} Instance ID: {85736D9A-329A-40C1-A003-D5E54CF1253E} Error Description: Error transmitting message: <SOAP-ENV:Fault xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>SOAP-ENV:Server</faultcode><faultstring>Request ID: Unknown Exception Type: System defined exception Exception Info: Exception occurred: Source: Siebel Error Code: 65537 (0x10001) Cause: Siebel://exception=SBLException (Unique ID &lt;none&gt;) E-SBL0041: Call to business component Update failed- Check record at index 1- Siebel error msg- The value of the Id Value is null ID field values missing in records to be updated. The update operation failed at index 1- Siebel error code- 65537 Exception data: struct SBLExceptionType = StringType SBLErrorMessage = "The value of the Id Value is null ID field values missing in records to be updated. The update operation failed at index 1" Signed32 SBLErrorCode = 65537 Signed32 SBLRecordIndex = 1</faultstring><detail><exposed:SBLException xmlns:exposed="http://schemas.microsoft.com"><exposed:SBLErrorMessage> The value of the Id Value is null ID field values missing in records to be updated. The update operation failed at index 1</exposed:SBLErrorMessage><exposed:SBLErrorCode>65537</exposed:SBLErrorCode><exposed:SBLRecordIndex>1</exposed:SBLRecordIndex></exposed:SBLException></detail></SOAP-ENV:Fault> at Microsoft.BizTalk.XLANGs.BTXEngine.BTXPortBase.VerifyTransport(Envelope env, Int32 operationId, Context ctx) at Microsoft.XLANGs.Core.Subscription.Receive(Segment s, Context ctx, Envelope& env, Boolean topOnly) at Microsoft.XLANGs.Core.PortBase.GetMessageId(Subscription subscription, Segment currentSegment, Context cxt, Envelope& env, CachedObject location) at SiebelWP.UpdateEmployee.segment2(StopConditions stopOn) at Microsoft.XLANGs.Core.SegmentScheduler.RunASegment(Segment s, StopConditions stopCond, Exception& exp)</string> 

Integration with and between ERP systems is commonplace in today’s businesses, especially with the proliferation of acquisitions. The power of BizTalk Server can be harnessed to accomplish this task.

Throughout the course of this white paper we have discussed various topics from general ERP system integration practices to a specific integration solution using the Siebel LOB adapter. The Siebel ERP system provides multiple integration points that are available via BizTalk Server, including File, FTP, HTTP, SOAP, Database, and of course the Siebel LOB adapter. The benefits of using the Siebel LOB adapter include direct communication with the Siebel application server, execution of the Business Components or Business Services, and limited dependency on an LOB expert. When choosing an integration strategy, it is important not to force a common solution onto all scenarios regardless of requirements. Some integrations are better suited for the “out-of-the-box” adapters while others require the Siebel LOB adapter. In some cases, you will use a combination of these adapters. Furthermore, a majority of integrations will require the use of transactional processes. In these cases, the use of an orchestration is necessary. However, in the rare event that a transaction is not needed, CBR can be used.

For more information about using the Siebel LOB adapter, see Siebel eBusiness Applications Adapter on the MSDN® Web site.

Glossary of Terms

Term Definition

Line of Business (LOB) System

An application used in business.

Enterprise Resource Planning (ERP) System

A software package used by a company to manage important parts of its business. An ERP system can be considered a type of LOB system.

Content Based Routing (CBR)

CBR is a mechanism for routing messages based solely on their properties. By using this publish/subscribe model, messages can be delivered to any number of send ports without requiring the additional overhead and resources used by orchestrations.

Common Errors

The following table lists common errors in Microsoft® BizTalk® Adapter v1.0 for Siebel eBusiness Applications.

Error Number and Message (in Event Log) Resolution

E-SBL0016 – Siebel Java Data Bean jars are missing.

Failed to instantiate Siebel Java

Data Bean on thread -742484740

Verify that your CLASSPATH settings have the complete path and name of the required JAR files.

See Updating Environment Variables in the appendix.

E-SBL0030 – Wrong Enterprise, app server,

gateway server, Object manager.

Error Message: Call to Login failed.

Verify your Siebel connection parameters. The parameters are case-sensitive.

The Siebel Gateway server is down.

The Gateway (the name of the server) is used by Siebel to authenticate the user.

E-SBL0030 – Wrong Repository - Business

Services: Call to GetBusinessServices failed.

Verify your repository setting.

Bb820919.note(en-US,BTS.10).gifNote
These values are case-sensitive.

E-SBL0030 – Wrong Repository - Business

Objects: Call to GetBusinessObjects failed.

Verify your repository setting.

Bb820919.note(en-US,BTS.10).gifNote
These values are case-sensitive.

E-SBL0030 – Wrong User or Password - Call to Login failed.

You have entered an invalid set of logon parameters.

Re-enter your logon parameters. The parameters are case-sensitive.

E-SBL0030 – Adapter is connected and logged into a Siebel system then loses this connection by a network fault. The adapter returns a failure condition until the login times out. The default is 30 minutes.

End the runtimagent.exe process by using Task Manager.

Note that this does not occur with the Siebel.jar file provided with version 7.7.

E-SBL0039 – Siebel Java Data Bean jars are Missing

Thread task failed while trying to log on.

E-SBL0039 – Wrong Enterprise, app server, gateway server, Object manager.

Thread task failed while trying to do log on. Error Message: Call to Login failed.

Verify your Siebel connection parameters. The parameters are case-sensitive.

E-SBL0039 – Wrong Repository - Business

Services: Thread task failed while trying to retrieve business services.

Verify your repository setting.

E-SBL0039 – Wrong Repository - Business

Objects: Thread task failed while trying to retrieve business objects.

Verify your repository setting.

E-SBL0039 – Wrong User or Password.

Thread task failed while trying to

log on.

Re-enter your logon parameters.

The parameters are case-sensitive.

The force activate flag and the No update settings are not correct in Siebel Tools.

The UpdateEx (all the Ex methods) activates all the fields. The

UpdateEx2 has the capability of turning on/off the activate feature.

Using Siebel Tools:

  • Check that the force activate flag is set.
  • Check that No Update is not selected.

Limitations

  • The APIs associated to the Siebel Business Components and Business Services provide limited functionality and often require multiple API calls to perform even basic data transactions.
  • It is not likely that a BizTalk Server expert would also be proficient in Siebel. Therefore, you will find that to successfully communicate and integrate with Siebel, a Siebel system developer and/or administrator will be required.

Known Issues

It is important to note that the Siebel LOB adapter can only retrieve metadata for Business Components and Business Services from the Siebel Repository. Custom Business Services created using the Siebel Web client are stored in the Siebel database. To access custom Business Services by using the Siebel LOB adapter, Siebel Tools must be used for custom Business Service creation.

Another item to be wary of is that table definitions can be modified directly by Siebel developers and/or administrators. If not done properly, it is possible for data in the database to exceed the bounds of the Siebel Business Component. Since the schemas are generated using the Business Component definitions it is possible for schema validation errors to occur, rendering the Business Component unusable. Consult with a Siebel developer or administrator to resolve this issue.

Updating Environment Variables

Use the following procedure to update your environment variables on Windows XP or Windows 2000.

To update your Environment Variables
  1. Open Control Panel.

  2. Click the System icon.

  3. Click the Advanced tab.

  4. Click Environment Variables.

  5. To update the Path variable:

    1. Find the Path variable in the list of System Variables.
    2. Click Edit.
    3. Append the desired value to the existing Variable value, separating values by a semicolon (;):
      Example: C:\j2sdk1.4.2_08
  6. To update the CLASSPATH variable:

    1. Find the CLASSPATH variable in the list of System Variables.
    2. Click Edit.
    3. Append the desired value to the existing Variable value, separating values by a semicolon (;):
      Example: c:\Jars\SiebelJI_enu.jar;c:\Jars\SiebelJI_Common.jar; c:\Jars\SiebelJAccess.jar;

Brian Jones is a solutions architect for HCL EAI Services, Inc. He holds a BS in Computer Information Systems from Troy University. Brian has been in the Information Technology industry for 12 years and has been working with BizTalk Server 2004 and 2006 since the beginning.

Jay Lee is a Partner and Chief Technologist at Anaheim-based eBI Solutions, LLC where he and his team help customers succeed in their business and IT initiatives in Enterprise Application Integration (EAI), Business-to-Business Integration (B2Bi), Business Process Management (BPM), and Business Intelligence. Jay holds a BA in Physics from UCLA and is pursuing an MBA at the Marshall School of Business at USC. He is a member of the Microsoft BizTalk Virtual Technical Specialist team. He speaks, writes, and trains regularly on topics related to BizTalk Server architecture, development, and administration. Jay lives with his wife Emily in Orange County, CA.

Mark Michaelis is the owner of intelliTechture, a small business dedicated to training and consulting in Microsoft technologies and the IDesign architect specializing in WCF and VSTS. Mark was recognized by Microsoft as a Microsoft MVP for Visual Studio Team System and he wrote the official courseware for VSTS for Microsoft. Mark holds an MS in Computer Science from the Illinois Institute of Technology and he serves on several Microsoft Software Design Review teams including WCF, C#, and VSTS. Mark speaks at developer conferences both nationally and internationally and has written several articles and books, in addition to maintaining a blog (http://mark.michaelis.net/blog). His recent book is Essential C# 2.0 (Addison-Wesley, 2006).

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft