External Business Components

The external business component feature provides a way to access data that resides in a non-Siebel table or view, using a Siebel business component.

This chapter consists of the following topics:

Before continuing with configuring and implementing external business components (EBCs), review the following books on the Siebel Bookshelf:

Configuring Siebel Business Applications
Siebel Developer's Reference
Siebel Tools Online Help
Using Siebel Tools

Process of Configuring External Business Components

Before proceeding, review Configuring the External Business Component. To configure EBCs, you perform the following high-level tasks:

Creating the External Table Definition.
Import the external table definition into Siebel Tools using the External Table Schema Import Wizard.
This wizard creates a new Table object definition in the Siebel Repository, based upon the contents of a DDL (data definition language) file, or from an Open Database Connectivity (ODBC) data source.
Mapping External Columns to Siebel CRM System Fields.
Map columns in the external table or view to Siebel CRM system fields.

Note: One column in the external table or view must be mapped to the Id system field by setting the System Field Mapping property for the column.
Specifying the Data Source Object.
Configure the table definition and specify the data source object.
The Data Source object is a child object of the Table Object in Siebel Tools and will have to be exposed in the Object Explorer if not already visible. For information on exposing objects in the Object Explorer of Siebel Tools, see Using Siebel Tools.
This object tells the object manager which data source to use to access the object.
Specifying Any Optional Table Properties.
When the table is imported, specify additional table properties for the corresponding external table.
Configuring the External Business Component.
Configure the EBC and specify the data source object. This data source name will be the same as that specified for the Table object.
Specifying Run-Time Parameters.
After the data source definition is named in Siebel Tools, specify the run-time parameters by completing the following:
- Configure the data source definition.
- Update the server component definition.

Creating the External Table Definition

You use Siebel Tools and the External Table Schema Import Wizard to import your external table definition into the Siebel Repository.

You can create the table definition in one of two ways:

For more information about using Siebel Tools, see Using Siebel Tools.

This task is a step in Process of Configuring External Business Components.

Creating the External Table Definition from a DDL File

You can use the External Table Schema Import Wizard to create the table definition from a data definition language (DDL) file.

It is possible to import an external view definition rather than a table definition. When a view rather than a table definition is imported, it is necessary to amend the Type property of the created Table definition to reflect External View.

Note: You can import a database view definition as well as a table definition here. While no difference exists in the resulting Siebel Table object, if it references an external database view, only read access from the Siebel Application is supported.

To create the external table definition from a DDL file

In Siebel Tools, check out and lock the appropriate project.
From the File menu, choose New Object to display the New Object Wizards dialog box.
Click the General tab, then double-click External Table Schema Import.
In the External Table Schema Import Wizard, specify the following values, then click Next:
1. Choose the project with which the new Table object definition will be associated.
2. Specify DDL/Analytics as the schema source type.
3. Choose the three-digit group code for table name generation. For example, if you choose AXA, then the format of the table names generated will be:
```
EX_AXA_00000001
```
In the Import External Schema - DDL dialog box, specify the following, then click Next:
1. Specify the database where the external table resides. The value specified must correspond to the database used by the Siebel schema, for example, Oracle Server Enterprise Edition.
2. Provide the full path for the location of the SQL/DDL file that contains the external table definition.
Confirm the entries, then click Finish to import the DDL file.
A Table object definition is added to the Siebel Repository, corresponding to the external table.
Repeat Step 2 through Step 6 for every external table definition you want to import.

Creating the External Table Definition from an ODBC Data Source

You can use the External Table Schema Import Wizard to create the table definition from an Open Database Connectivity (ODBC) data source.

To create the external table definition from an ODBC data source

In Siebel Tools, check out and lock the appropriate project.
From the File menu, choose New Object to display the New Object Wizards dialog box.
Click the General tab, then double-click External Table Schema Import.
In the External Table Schema Import Wizard, specify the following values, then click Next:
1. Choose the project with which the new Table object definition will be associated.
2. Specify ODBC as the schema source type.
3. Choose the three-digit group code for table name generation. For example, if you choose AXA, then the format of the table names generated will be:
```
EX_AXA_00000001
```
In the next dialog box, click Select Data Source.
The Select Data Source dialog box appears.
Click the Machine Data Source tab, select the appropriate data source name, and then click OK.
In the Connect to Database Type dialog box, on the Login tab enter the database user ID and password, then click OK.
Enter the table owner for the data source, then click Next.
Select the tables to import, then click Next.
Confirm the entries, then click Finish.
A Table object definition is added to the Siebel Repository for each external table selected.

About Data Type Mappings for Importing Table Definitions

When importing table definitions, certain data type mappings are supported for use with the Siebel application. The following table contains the data type mappings you can use when importing table definitions.

Table Supported Data Type Mappings by Product

Supported Data Type	Siebel Data Type
Microsoft SQL Server Data Types
int	Numeric with scale of 0
bigint	Numeric with scale of 0
smallint	Numeric with scale of 0
tinyint	Numeric with scale of 0
float	Numeric
real	Numeric
decimal	Numeric
money	Numeric
smallmoney	Numeric
bit	Numeric with a value of 0 or 1
char	Character
nchar	Character
varchar	Varchar
nvarchar	Varchar
text	Long
ntext	Long
datetime	Date Time
smalldatetime	Date Time
IBM DB2 UDB Data Types
UINT	Numeric with scale of 0
BIGUINT	Numeric with scale of 0
SMALLUINT	Numeric with scale of 0
FLOAT	Numeric
REAL	Numeric
DECIMAL	Numeric
NUMERIC	Numeric
CHAR	Character
VARGRAPHIC	Varchar
LONG VARGRAPHIC	Long
CLOB	CLOB
DATE	Datetime
TIME	Datetime
TIMESTAMP	Datetime
Oracle Database Data Types
Number	Numeric
TIMESTAMP WITH TIME ZONE	Numeric
TIMESTAMP WITH LOCAL TIME ZONE	Numeric
Char	Character
Nchar	Character
varchar2	Varchar
nvarchar2	Varchar
Long	Long
CLOB	CLOB
date	Datetime
Oracle Business Intelligence (BI) Server Data Types
Integer	Numeric with scale of 0
Smallint	Numeric with scale of 0
Tinyint	Numeric with scale of 0
Float	Numeric
Double	Numeric
Bit	Character (1)
Boolean	Character (1)
Char	Character
Varchar	Varchar
Longvarchar	Long
Datetime	Datetime
Date	Datetime
Time	Datetime

The following table contains the data types that are not supported for importing table definitions.

Table Unsupported Data Type Mappings by Product

Database	Unsupported Data Types
Microsoft SQL Server	timestamp
	varbinary
	binary
	image
	cursor
	uniqueidentifier
IBM DB2 UDB	DBCLOB
IBM DB2 UDB	BLOB
Oracle Database	TIMESTAMP
	NCLOB
	BLOB
	BFILE
	ROWID
	UROWID
	RAW
	LONG RAW
	INTERVAL YEAR TO MONTH
	INTERVAL DAY TO SECOND
Oracle BI Server	Timestamp
	Varbinary
	Longvarbinary
	Binary
	Object
	Unknown

About the New Imported Table Definition

After the table definition is imported using the External Table Schema Import Wizard, the external table and the external column names are generated.

The external table name is stored in the Table object’s Alias property. This external table name consists of the following:

An EX prefix (for external table)
A three-digit batch code specified in the External Table Schema Import Wizard
An automatically generated seven-digit number

An example of the Table name is EX_ABC_0000001.

The external column name is stored in the Column child object’s Alias property. An X is added as the prefix and a four-digit number is added as the suffix for the external column name, for example, X_ABC_0000001_0001.

The Table object’s Type property is set to External or External View (if a view was imported). This column denotes that the table resides outside of the Siebel database.

Mapping External Columns to Siebel CRM System Fields

This task is a step in Process of Configuring External Business Components.

When the EBC is defined, you must map the Siebel CRM system fields to the corresponding external table column. System field mapping is accomplished at the column level, rather than using business component user properties. Specify the System Field Mapping column attribute if you want to map a Siebel system field to a column.

Note: At a minimum, the Id field must be mapped to a unique column defined in the external table and in the Table object definition, which is specified in the business component’s Table property.

By default, the Siebel CRM system fields are not included in the generated SQL for external tables.

System Field Mapping is used to specify the mapping between table columns and Siebel CRM system fields. The following is a list of the system fields that can be mapped to external table columns:

Conflict Id. (Optional).
Created. (Optional) Datetime corresponding to when the record was created.
Created By. (Optional) String containing the user name of the person and the system that created the records.
Extension Parent Id. (Optional).
Mod Id. (Optional).
Non-system. (Optional).
Updated. (Optional) Datetime corresponding to when the record was last updated.
Updated By. (Optional) String containing the user name of the person and system that last updated the record.
Id. Mandatory. The single column unique identifier of the record. A column in the external table must be mapped to the Id field.

Note: The System Field Mapping property must be used in conjunction with external tables only.

Specifying the Data Source Object

This task is a step in Process of Configuring External Business Components.

When the external table has been defined, specify the data source for the corresponding external table. The Data Source child object of the Table object specifies the data source for the corresponding external table:

The Data Source child object corresponds to a data source defined in the application configuration file (.cfg) or in the Application - Server Configuration screen, Profile Configuration view.
The Data Source child object instructs the Application Object Manager to use the data source for a specific table. If a Data Source child object is not specified, then the default data source for the application will be used.

Note: The Data Source child object is specified for external tables only.

For more information about the Data Source child object, see Siebel Tools Online Help.

Specifying Any Optional Table Properties

When the table is imported, you can specify additional table properties for the corresponding external table:

External API Write. Allows you to perform reads directly from the database and have write operations processed by way of a script.
A Boolean property is used to indicate whether or not inserts, updates, or deletes to external tables will be handled by an external API. If this property is set to TRUE, then add scripts to the BusComp_PreWriteRecord and BusComp_PreDeleteRecord events to publish the insert, update, or delete operation to an external API.
Key Generation Business Service. Allows a business service to generate a primary key (Id field) for a business component. If this is not specified, then the Siebel application will generate a row_id value for the column that corresponds to the Id system field.
Key Generation Service Method. Allows a business service method to be called when generating a primary key for a business component.
This method returns a property with the name set to the external table's key column name, and the value set to the generated key:
```
Outputs.SetProperty(<my_external_key_column_name>, <generated_key>);
```

For more information about these table properties, see Siebel Tools Online Help.

This task is a step in Process of Configuring External Business Components.

Configuring the External Business Component

When a Table object definition corresponding to the external table exists in the repository, you can configure a business component to use the new Table object definition.

In general, configuring an EBC is similar to configuring a standard business component with the following exceptions:

Data Source business component property. Specify the Data Source business component property. Set the value for this property to the name of the corresponding Table Data Source.
Log Changes property. Set the Log Changes property to False (unchecked). This will prevent Siebel Remote or Replication transactions from being created. (The default is true.)
Intersection table. When configuring a many-to-many relationship, the intersection table resides in the same database instance as the child table.
CSSBusComp class. It is recommended that all EBCs use the CSSBusComp class.

Note: Substituting a Siebel-provided table with an external table can result in significant downstream configuration work, and in some cases can restrict or prevent the use of standard functionality provided for the Siebel Business Applications.

This task is a step in Process of Configuring External Business Components.

Specifying Run-Time Parameters

After the data source definition is named in Siebel Tools, you specify the run-time parameters by configuring the data source definition, and updating the server component definition.

If you are testing by using the Siebel Developer Web Client, then add a [DataSource] section to the client .cfg file.

This task is a step in Process of Configuring External Business Components.

Configuring the Data Source Definition

As part of specifying the run-time parameters, configure the data source definition.

To configure the data source definition

Navigate to the Administration - Server Configuration screen, Enterprises view, then Profile Configuration.
Copy an existing InfraDatasources named subsystem type.
Change the Profile and Alias properties to the Data Source name configured in Siebel Tools.
Update the profile parameters to correspond to the external RDBMS:
- DSConnectString = data source connect string
  - For Microsoft SQL Server or IBM DB2, create an ODBC or equivalent connection and input the name of this in the parameter.
  - For Oracle Database, this value must specify the TNS name associated with the database and not an ODBC or other entry.
- DSSQLStyle = database SQL type
  See the following table for a listing of the supported SQL types.
- DSDLLName = DLL or library name corresponding to the SQL type
  See the following table for a listing of the supported connector Dynamic Link Library (DLL, Windows) or library (shared object, UNIX) names and SQL styles.
- DSTableOwner = data source table owner
- DSUsername = default username used for connections (Optional)
- DSPassword = default password used for connections (Optional)
Note: The DSUsername and the DSPassword parameters are optional. However, to avoid receiving a login prompt when accessing the external data source, specify DSUsername and DSPassword. If specified, they will override the default username and password.

The DSUsername and the DSPassword parameters are activated only when using the Database Security Adapter. For more information, see Configuring a User in LDAP or ADSI Security Adapter To Access EBCs.

Configuring a User in LDAP or ADSI Security Adapter To Access EBCs

You do not typically use Lightweight Directory Access Protocol (LDAP) or Microsoft Active Directory Service Interfaces (ADSI) to retrieve the database username and password to be used for the EBC. Instead, you specify a common DSUsername and DSPassword as described in Configuring the Data Source Definition.

Note: You do not need to configure LDAP or ADSI authentication unless you need different database users for the EBC (more than one for all users), for example, to have all call center users access the EBC data source with a specific database user, or to be able to set a specific database user for one or more Siebel login IDs.

When LDAP or ADSI authentication is used, the username and password values for the external data source are provided in the ADSI SharedCredentialsDN parameter and the CredentialAttributeType attribute.

Note: The CredentialAttributeType attribute must be able to hold multiple values, for example, url. It cannot be single-value, such as mail.

For example, the name of your external data source is MyExtDataSrc, and your ADSI is configured with the following parameters:

SharedCredentialsDN= cn=sharedcred,ou=people,dc=siebel,dc=com
CredentialAttributeType = url

In your ADSI server modify the url attribute for the following entry:

cn=sharedcred,ou=people,dc=siebel,dc=com

Before modifying, one value must already exist (assuming sadmin and db2 are the user name and password for the ServerDataSrc data source, which is the primary data source):

type=ServerDataSrc username=sadmin password=db2

Add additional values to the url attribute (assuming mmay and mmay are the user name and password for the MyExtDataSrc data source, which is the external data source):

type=MyExtDataSrc username=mmay password=mmay

After adding the new value for the external data source to the url attribute, you are able to access EBCs.

Configuring the Data Source Definition for the Siebel Developer Web Client

If testing using the Siebel Developer Web Client, then add a [DataSource] section to the client .cfg file for the data source definition named in Siebel Tools. In this example, WindyCity is the data source being added.

To configure the data source definition in the Siebel Developer Web Client

Add the data source definition named in Siebel Tools. In this example, the data source definition named is WindyCity:
```
[DataSources]
Local = Local
Sample = Sample
ServerDataSrc = Server
GatewayDataSrc = Gateway
WindyCity = WindyCity
```

In the data source section of the application’s .cfg file, add the following parameters (for the supported SQL types and connector DLL names, see the following table):

[WindyCity]
Docked = TRUE
ConnectString = data source connect string
SqlStyle = database SQL type
TableOwner = data source table owner
DLL = DLL Name corresponding to the SQL type
DSUsername = user id (Optional)
DSPassword = password (Optional)

Supported Connector Names and SQL Styles

When defining the DLL (Windows) or library (UNIX) and SQL files for importing the external schema, the external database being used might not be the same as the Siebel database. The following table contains the supported connector DLL and library names and their corresponding SQL styles. The extension for the DLL or library name is optional.

Table Supported Connector DLL and Library Names and SQL Styles

External Database	DLL Name (Windows)	Library Name (UNIX)	SQL Style
IBM DB2	sscddcli.dll	sscddcli.so	DB2
Microsoft SQL Server	sscdms80.dll	Not supported	MSSqlServer
Oracle Database	sscdo90.dll	sscdo90.so	OracleCBO

Updating the Server Component to Use the New Data Source

As part of specifying the run-time parameters, update the server component to use the new data source.

To update the server component to use the new data source

Navigate to the Administration - Server Configuration screen, Enterprises view, then Component Definitions.
In the Component Definitions list applet, select your Application Object Manager Component. For example, select the Call Center Object Manager (ENU).
Choose Start Reconfiguration from the Menu drop-down list on the Component Definitions list applet.
The Definition State of the component will be set to Reconfiguring. Reselect your application component after selecting the Start Reconfiguring menu item.
In the Component Parameters list applet, query for OM - Named Data Source name, and update the Value by adding the alias name of the data source specified in Specifying Run-Time Parameters.
The format of the OM - Named Data Source name parameter is a comma-delimited list of data source aliases. It is recommended that you do not modify the default values, and that you add their new data sources to the preexisting list.
After the parameter values are reconfigured, commit the new configuration by selecting Commit Reconfiguration from the Menu drop-down list on the Component Definitions list applet.
The new parameter values are merged at the enterprise level.
To cancel the reconfiguration before it has been committed, select Cancel Reconfiguration from the Menu drop-down list on the Component Definitions list applet.

Using Specialized Business Component Methods for EBCs

The following are the specialized business component methods that are supported for use with EBCs:

IsNewRecordPending
GetOldFieldValue
SetRequeryOnWriteFlag (PreWriteRecord event)
SetRequeryOnWriteFlag (WriteRecord event)

IsNewRecordPending Business Component Method

This method can be called by using a script in the PreWriteRecord event to determine if the current record is newly created. If the record is a new record, then this method returns the value TRUE.

An example script for the use of this method follows:

var    isNewRecord = this.InvokeMethod("IsNewRecordPending");

GetOldFieldValue Business Component Method

This method can be called by using a script in the PreWriteRecord event to retrieve an old field value if needed. This method takes an input parameter, which must be a valid field name, and returns a string containing the old field value.

An example script for the use of this method follows:

var    oldLoc = this.InvokeMethod("GetOldFieldValue", "Location");

SetRequeryOnWriteFlag (PreWriteRecord event) Business Component Method

In the PreWriteRecord event, this method can be used to put the business component into a mode where the current record refreshes from the data source after the write operation. EBCs typically use this method to refresh database sequencing column values on new record operations. This method takes an input parameter of TRUE or FALSE.

An example script for the use of this method follows:

var    requery = this.InvokeMethod("SetRequeryOnWriteFlag", "TRUE");

SetRequeryOnWriteFlag (WriteRecord event) Business Component Method

In the WriteRecord event, this method informs the object manager that the write operation to the data source is processed by using a script rather than a database connector. At the end of the operation, the business component method, SetRequeryOnWriteFlag, can be called again with the FALSE parameter to reset the requery on write mode, if needed.

An example script for the use of this method follows:

var    extWrite = this.InvokeMethod("SetRequeryOnWriteFlag", "TRUE");
// insert script here to commit the record via an mechanism channel
var    resetWrite = this.InvokeMethod("SetRequeryOnWriteFlag", "FALSE");

Usage and Restrictions for External Business Components

The following usage guidelines and restrictions apply to EBCs:

Creating and populating the external table is the responsibility of the customer. Consult your database administrator for the appropriate method to use.
EBCs cannot be docked, so they do not apply to mobile users on the Siebel Mobile Web Client. Siebel Remote is not supported.
EBCs support many-to-many relationships with the limitation that for such relationships the intersection table must be from the same data source as the child business component.
EBCs cannot be loaded using the Enterprise Integration Manager.
EBCs rely on the Business Object Layer of the Siebel Architecture. Therefore, EBCs are used only in Siebel Server components using this layer such as the Application Object Manager (for example, the Call Center Object Manager), Workflow Process Manager, and so on. EBCs are not used on components not using this layer, such as Workflow Policies (the Workflow Monitor agent) and Assignment Manager.
The Id field must be mapped to an underlying column in the external table to support insert, update, delete, and query operations.
Using the Oracle Sequence Object to populate the Id system field is not supported. The value of the Id system field has to be known by the object manager at the record commit time, while the Oracle Sequence Object value is populated by the database server when the change is being processed inside the database.
If the column that was mapped to the Id system field has Primary Key checked, then row ID values are generated by the object manager. Otherwise, a user-entered row ID value is assumed, and the object manager does not generate a row ID value for it.
However, in either configuration, the Primary Key column must not use the Oracle Sequence Object.
EBCs with non-English data require the Siebel S_APP_VER and S_SYS_PREF tables to be present in the external database.
Siebel Business Applications use the UNICD_DATATYPS_FLG column of the S_APP_VER table to indicate whether the database is a Unicode database. A value of 8 means UTF-8, and Y means UTF-16. For Non-Unicode databases, the Enterprise DB Server Code Page system preference is also required to have the correct setting.
For help with creating and populating these tables, contact your Oracle sales representative for Oracle Advanced Customer Services to request assistance from Oracle’s Application Expert Services.
For EBCs that contain multivalue groups, if a primary join is enabled, then both the parent and the child business components must be from the same data source. Multivalue groups are also supported as long as such configuration does not require that a distributed join or a subquery be performed.
Siebel visibility control (for example, ViewMode) is not supported for EBCs.
An external join alias must have the same name as the name used for the external table.
EBCs based on Database views can be used for queries only; updates are not supported.
For EBCs that have a parent-child relationship, their related external tables must not have a foreign key constraint set between them on the external database. If they do have a foreign key constraint, then Copy and Deep Copy functionality will not work.

Note: Significant configuration effort and changes might be required if you choose to reconfigure a standard Siebel business component on an external table. For example, existing join and link definitions are unlikely to function, because the source fields and underlying columns might not exist in the external table.

About Using External Business Components with the Siebel Web Clients

If EBCs are used with the Siebel Web or Mobile Web Clients, then new data sources corresponding to the data sources specified for the external tables must be added to the specific Siebel application configuration file. If the user name and password for the external data source are different from the current data source, then a log-in window appears to initiate logging into the external data source.

About Overriding Connection Pooling Parameters for the Data Source

Overriding the connection pooling parameters for the data source is supported. If connection pooling is enabled for the component but not for the data source, then set to zero (0) the following:

DB Multiplex - Max Number of Shared DB Connections (DSMaxSharedDbConns)
DB Multiplex - Min Number of Shared DB Connections (DSMinSharedDbConns)
DB Multiplex - Min Number of Dedicated DB Connections (DSMinTrxDbConns) parameters for the data source

About Joins to Tables in External Data Sources

Joins from business components, based on the default data source to a table in an external data source, are supported in the Siebel application.

Like other joined fields, the fields based on the join to the EBC are read-only.

The limitations for joining business components to tables in an external data source are as follows:

The source field for the join must be based on a table in the default data source.
The destination column of the join must be the column mapped to System Field Id.
Multiple single join specifications are not supported for the join to the external table.
Reverse navigation (for example, a call to go to the last record) is not supported when fields from multiple data sources are active.

Join Constraints are supported. Joins to more than one external table might be specified. However, increasing the number of external joined data sources can cause degradation in performance.

Searching and Sorting on Fields Joined to External Tables

Fields based on a join to an external table can be searched and sorted. However, limitations do exist. The limitations for searching and sorting on fields joined to an external table follow:

All fields in the sort specification must either be based on columns in the same external table, or be based on columns in the default data source.
Named search specifications cannot be set on fields from an external data source.

For information on named search specifications, see the topic on the SetNamedSearch method in Siebel Object Interfaces Reference.

Performance tests are recommended if searching and sorting are permitted on fields based on joins to the external tables. The Siebel application does not have information on the data shape in the external tables. The Siebel application follows a rule-based approach to decide the order in which to query the external tables.

For example, consider the case where there are search and sort specifications on the fields in the Siebel Data Source but none on the fields from the external data source. The Siebel application decides to query the Siebel tables first. Only the rows matching the query specification in the current workset are retrieved from the external data source. As more rows are retrieved from the tables in the Siebel Data Source, the rows from the external data source are also retrieved.

The rules become complex when Search and Sort Specifications are applied to multiple data sources. The rules followed are based on the following requirements:

Retrieving the first few rows quickly
Shipping the least amount of data between the Siebel and external data sources
Eliminating a sort step

Step 2 and Step 3 might produce competing results. In that case, Step 2 takes precedence.

If, as result of the search and sort specifications in effect, then the external table on which the Sort is based is not the driving table, the Siebel application raises an error if more than 1000 rows are retrieved. Refine the query specification in the event of this error.

Directives specified using the Business Component User property External DataSource Field Priority On Search to allow hinting of the order in which the tables in the data sources will be queried are supported. These directives can be applied based on a knowledge of the data shape in the Siebel and external tables.

For example, using the following property values:

Property	Value
External DataSource Field Priority On Search: FieldA	1
External DataSource Field Priority On Search: FieldB	2

A query on Field A is likely to be selective. If there is a search specification on Field A, then the table that field A is based on is considered the driving table.

A query on Field B is likely to be selective. If there is a search specification on Field B and none on Field A, then the table that field B is based on is considered the driving table.

About Distributed Joins

Just as join objects can be configured in Siebel Tools and represent a 1:1 relationship between tables resident within the Siebel data model, join objects can be configured to represent a 1:1 relationship with tables external to the Siebel database. A distributed join is a 1:1 relationship between tables that spans two relational data sources. This allows a single, logical record to span multiple data sources. In using distributed joins, the join fields are read-only, and the join specification can consist only of a single field. This federated field support provides the ability for the Object Manager to perform the cross-database join.

Distributed joins are configured the same as standard joins. The query is distributed when the Data Source child object of the table provides a hint to the Object Manager (OM) to federate the query.

Configuring Distributed Joins and Federated Fields

To configure distributed joins, you perform the following high-level tasks:

Implement the external data source (similar to what was done for EBCs).
The Datasource child object of the Table provides a hint to the object manager to federate the query.
Create the Join.
Add the fields to the business component.

To configure distributed joins and federated fields

Create the Join point to your external table.
Create the Join Specification.
This is similar to what you do when creating a standard Siebel join.
Add Field to Business Component.
Add the fields from the external table to the business component using the join specified.

Usage and Restrictions for Distributed Joins

The following usage guidelines and restrictions apply to distributed joins:

The source field for the distributed join must be based on a table in the business component’s data source.
The destination column of the distributed join must be a column mapped to the Id System Field.
Multiple join specifications are not supported for a distributed join. However, join constraints are supported.
Inner join is not supported for a distributed join.
Reverse navigation (for example, a call to go to the last record) is not supported when the fields from multiple data sources are active.
All fields in the sort specification must be from the same data source.
All fields in the named search specifications must be from the default data source.

Troubleshooting External Business Components

As you create EBCs, it is recommended that you consider the following steps:

Configure EBCs for read and make sure that the data is displayed correctly in the application.
If the development team feels that some fields require script in order to display correctly then defer the implementation of these fields until testing is complete for a simple read.
Add any data transformation script or configuration required in order to provide read access to the more complex fields for display.
Configure EBCs for update and make sure that the data is stored correctly in the external database(s) and displayed correctly in the Siebel application.
Do not add any validation logic to the EBC at this time.
Once testing of data update is complete, establish any data transformation configuration or script required to update the fields.
Make sure that the configuration uses script, which is preferred. However, it is recommended that any data transformation scripts be written on the Pre event.
Data manipulation configuration and scripts must be attached to Post events.

As part of the troubleshooting process associated with EBCs, increasing the tracing level for a number of component events is suggested.

To increase the tracing level of component events

Navigate to the Administration - Server Configuration screen, Servers view, Components, Events, and then select the object manager being used.
Change the Log Level for the following Event Types to a higher value (the default is 1).
Initially a value of 4 is recommended.
- Task Configuration
- DBC Log
- SQL
- Object Manager DB Connection Operation Log
- General Object Manager Log
- Object Manager Session Operation and SetErrorMsg Log
- Object Manager runtime repository Operation and SetErrorMsg Log
- Security Adapter Log

Following this change, restarting the affected components is recommended. With the increase log level, more information is stored in the relevant log files. Reset these values back to 1 when troubleshooting is completed.