6EAI Siebel Adapter Business Service
EAI Siebel Adapter Business Service
EAI Siebel Adapter is a preconfigured business service that is used with any integration process that runs through the Siebel business object layer. Integration objects are used to update data in business objects and are used when retrieving data from business objects. These integration objects are configurable and can be used during an integration process (for example, entering and retrieving data from the Siebel Business Application).
This chapter describes the functionality of the EAI Siebel Adapter business service, and the different methods and arguments you can use with it to manipulate the data in the Siebel Database. It includes:
About Using Effective Dating with Siebel EAI Adapter Business Service
About Using Language-Independent Code with the EAI Siebel Adapter Business Service
Guidelines for Using the EAI Siebel Adapter Business Service
Enabling Logging for the EAI Siebel Adapter Business Service
Configuring the EAI Siebel Adapter Business Service for Concurrency Control
About the EAI Siebel Adapter Business Service
EAI Siebel Adapter is a general-purpose integration business service that allows you to:
Read Siebel business objects from the Siebel Database into integration objects.
Note: When called locally, the EAI Siebel Adapter business service creates an additional database connection. If this second connection times out, then further transactions will not be processed. To prevent this from happening, add the TrxDbConnReconnectIntervalSeconds parameter to the [ServerDataSrc] section of the application configuration (CFG) file. A typical value is 120.Write an integration object instance whose data originates externally in a Siebel business object.
Update multiple corresponding top-level (highest-level) parent business component records with data from one XML file, for an example, see Update Method.
Note: The Siebel Message is considered to be one transaction. The transaction is committed when there is no error. If there is an error, then the transaction is aborted and rolled back.
Node Types and the EAI Siebel Adapter Business Service
In an integration object hierarchy, nodes with at least one child are called internal nodes and nodes without children are called leaf nodes. When either the insert or update method is called on the EAI Siebel Adapter business service, the adapter performs the operation on both internal nodes and leaf nodes. When the insert or update method is called on the EAI UI Data Adapter business service, the adapter performs insert on leaf nodes only.
For more information on node types, see About the EAI UI Data Adapter Business Service.
EAI Siebel Adapter Business Service Methods
The EAI Siebel Adapter supports the following methods:
About the Examples in the EAI Siebel Adapter Business Service Methods Sections
The following information is true for the examples used for the EAI Siebel Adapter methods:
The business object data is represented as integration object data in XML format.
The XML document or integration object instance might also be referred to as a Siebel Message.
Fields that contain null values are not included in the XML examples.
However, these fields might be revealed when you use EAI XML Write to File.WriteEAIMsg() to print out the XML.
Query Method
You can use a combination of input arguments when using the Query Business Service Method of the EAI Siebel Adapter. The input arguments are as follows:
Query By Example (QBE). Pass in an integration object instance represented as a property set.
Note: EAI queries on integration objects do not use a search specification for child integration components when the query obtains the parent integration component.Primary Row Id. Pass in a string to the Object Id input argument. The string can be the row_id of the primary business component of the Output Integration Object Name.
Output Integration Object Name. See the Primary Row Id for information.
Search Specification. Pass in a String expression.
The input arguments can be used in one of the following combinations:
1
2 and 3
4
3 and 4
2, 3, and 4
The EAI Siebel Adapter uses this input as criteria to query the base business object and to return a corresponding integration object instance.
For an example of using the search specification method argument to limit the scope of your query see About Using Language-Independent Code with the EAI Siebel Adapter Business Service.
When using the EAI Siebel Adapter, to query all the business component records, you are not required to specify any value in the Object Id process property of the workflow. In this case, not specifying an Object Id or a Search Specification works as a wildcard.
If you want to query Siebel data using the EAI Siebel Adapter with the Query method and an integration object instance (property set) containing a query by example (QBE) search criterion, then all the fields present in the QBE will be used in the query. To retrieve a unique record, include the fields that make up the user key for the underlying integration object component instance to ensure you retrieve a unique record. You can use an asterisk (*) as a wildcard for each one of the fields.
For example, the following is your QBE:
<?xml version = "1.0" encoding = "UTF-8"?> <?Siebel-Property-Set EscapeNames="false"?> <SiebelMessage MessageId = "1-2IOY" IntObjectName = "EAI Account" MessageType = "Integration Object" IntObjectFormat = "Siebel Hierarchical"> <ListOfAccount> <Account> <CSN>*</CSN> <HomePage>*</HomePage> <Location>H*</Location> <Name>A*</Name> <Type>*</Type> </Account> </ListOfAccount> </SiebelMessage>
You would receive all of the Accounts with names that start with A* and have locations that start with H*. The CSN, HomePage, and Type fields cannot be blank because they are used in the query.
The EAI Siebel Adapter converts the QBE into a user Search Expression of the following:
[CSN] ~ LIKE "*" AND [Home Page] ~ LIKE "*" AND [Location] ~ LIKE "H*" AND [Name] ~ LIKE "A*" AND [Type] ~ LIKE "*"
You can run this example and review the output XML generated.
When using search expressions that contain an apostrophe ('), you must use two apostrophes ('') or the search will fail.
For example, you are searching for the string LUKE’S. The following search expression will fail in the EAI Siebel Adapter:
[Account.Name] LIKE "*LUKE'S*"
Use the following search expression instead:
[Account.Name] LIKE "*LUKE''S*"
QueryPage Method
This method is useful when the search specification retrieves a large number of records at the root component. To avoid returning one huge Siebel Message, you can specify the number of records to be returned using the PageSize argument, as presented in Skipnode Operation. You can also use method arguments such as OutputIntObjectName, SearchSpec, SortSpec, ViewMode, and StartRowNum to dictate which records to return.
Even though the QueryPage returns a limited number of records, it keeps the data in the cache, which you can then retrieve by calling the EAI Siebel Adapter with a new value for the StartRowNum method argument. Note that this is only possible if the method arguments OutputIntObjectName, PageSize, SearchSpec, SortSpec, and ViewMode are not changed and the NewQuery method argument is set to False.
The QueryPage method precedes each integration object instance. It is provided through the SiebelMessage input argument when performing a query by example. Parameters such as StartRowNum, PageSize, and others are applied to each integration object instance.
For example, a Siebel database contains four account records with the Name field set to: a1, a2, b1, b2. An input SiebelMessage with two instances of the Account integration object with the first instance’s name set to "a*" and the second instance’s name set to "b*" the result for StartRowNum=0 is all four records (a1, a2, b2, b4), and for StartRowNum=1 only two records (a2 and b2). This example illustrates that the StartRowNum method argument counts records within each single integration object instance of the query by example input SiebelMessage, once for "a*" (a1, a2) and once for "b*" (b1, b2).
The following is an example of using the QueryPage() method in a business service.
var EAIService = TheApplication().GetService("EAI Siebel Adapter");
var writeSvc = TheApplication().GetService("EAI XML Write to File");
var EAIin = TheApplication().NewPropertySet();
var ResultSet= TheApplication().NewPropertySet();
var moreRecords = true;
var countOfObjects = 0;
var i = 1;
// set up input arguments, get 10 at a time
EAIin.SetProperty("OutputIntObjectName", "EAI Account");
EAIin.SetProperty("PageSize", "10");
EAIin.SetProperty("SearchSpec", "[Account.Name] LIKE '3*'");
EAIin.SetProperty("StartRowNum", i);
EAIin.SetProperty("NewQuery", "true");
// retrieve the business component data
EAIService.InvokeMethod("QueryPage", EAIin, ResultSet);
// loop through cached data
while ( (ResultSet.GetChildCount() > 0) && (moreRecords)) {
countOfObjects = countOfObjects + ResultSet.GetProperty("NumOutputObjects");
// write out first chunk of data retrieved
ResultSet.SetProperty("FileName", "d:\\temp\\EAIaccount$$.xml");
writeSvc.InvokeMethod("WriteEAIMsg", ResultSet, Outputs);
// reuse the existing input property set, except don't reissue query
EAIin.SetProperty("NewQuery", "false");
i= i+10; // get next 10 records
EAIin.SetProperty("StartRowNum", i);
ResultSet.Reset(); // clear previous result set
EAIService.InvokeMethod("QueryPage", EAIin, ResultSet);
if (ResultSet.GetProperty("LastPage") == "true")
moreRecords = false;
}
Synchronize Method
You can use the Synchronize method to make the values in a business object instance match those of an integration object instance. This operation can result in updates, insertions, or deletions in the business components. The following rules apply to the results of this method:
If a child component is not present in the integration object instance, then the corresponding child business component rows are left untouched.
If the integration object instance’s child component has an empty container, then all child records in the corresponding business component are deleted.
For a particular child component, records that exist in both the integration object instance and business component are updated. Records that exist in the integration object hierarchy and not in the business component are inserted. Records in the business component and not in the integration object instance are deleted.
Only the fields specified in the integration component instance are updated.
Example of Synchronize Method on Deleted Unmatched Children
This first example demonstrates deleting unmatched children when using the Synchronize method. This example uses data present in the sample database.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CSN>1-3JGO7</CSN>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>ENU</LanguageCode>
<Location>Test</Location>
<Name>ABC Corp</Name>
<ListOfAccount_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "Y">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>ATown</City>
<Country>USA</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>123 Main St</StreetAddress>
</Account_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "N">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>BTown</City>
<Country>USA</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>456 Oak St</StreetAddress>
</Account_BusinessAddress>
</ListOfAccount_BusinessAddress>
<ListOfContact>
<Contact>
<ActiveStatus>Y</ActiveStatus>
<FirstName>User1</FirstName>
<LastName>User1</LastName>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
<Contact>
<ActiveStatus>Y</ActiveStatus>
<FirstName>User2</FirstName>
<LastName>User2</LastName>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
</ListOfContact>
<ListOfAccount_Organization>
<Account_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationId>0-R9NH</OrganizationId>
<OrganizationIntegrationId/>
</Account_Organization>
</ListOfAccount_Organization>
</Account>
</ListOfAccount>
</SiebelMessage>
Then the following XML (integration object instance) is submitted with Synchronize:
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CSN>1-3JGO7</CSN>
<Competitor>Y</Competitor>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>CHS</LanguageCode>
<Location>test</Location>
<Name>ABC Corp</Name>
<ListOfContact>
<Contact>
<ActiveStatus>N</ActiveStatus>
<FirstName>User1</FirstName>
<LastName>User1</LastName>
<MiddleName></MiddleName>
<Organization>Default Organization</Organization>
</Contact>
<Contact>
<FirstName>User3</FirstName>
<LastName>User3</LastName>
<MiddleName></MiddleName>
<Organization>Default Organization</Organization>
</Contact>
</ListOfContact>
</Account>
</ListOfAccount>
</SiebelMessage>
Following is the result you will receive. Because the contact information is included in the integration object instance, User2 in the database is deleted because it was an unmatched node. User1 is updated because it is a matched node. User3 is inserted because it is a new node. Since Business Address was not included in the integration object instance, it is left in the business object.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CSN>1-3JGO7</CSN>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>CHS</LanguageCode>
<Location>Test</Location>
<Name>ABC Corp</Name>
<ListOfAccount_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "Y">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>ATown</City>
<Country>USA</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>123 Main St</StreetAddress>
</Account_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "N">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>BTown</City>
<Country>USA</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>456 Oak St</StreetAddress>
</Account_BusinessAddress>
</ListOfAccount_BusinessAddress>
<ListOfContact>
<Contact>
<ActiveStatus>N</ActiveStatus>
<FirstName>User1</FirstName>
<LastName>User1</LastName>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
<Contact>
<ActiveStatus>N</ActiveStatus>
<FirstName>User3</FirstName>
<LastName>User3</LastName>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
</ListOfContact>
</Account>
</ListOfAccount>
</SiebelMessage>
The following table is a high level representation of the previous example.
Table Representation of the Synchronize Method on Deleted Unmatched Children
| Record In Database | Integration Object Instance | Record After Synchronize |
|---|---|---|
Account: ABC Corp
|
Account: ABC Corp
|
Account: ABC Corp
|
This second example demonstrates how all records with an empty container are deleted when using the Synchronize method.
If you start with this business component data:
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CSN>1-3JGO7</CSN>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>ENU</LanguageCode>
<Location>test</Location>
<Name>ABC Corp</Name>
<ListOfAccount_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "Y">
<AddressId>1-3JGOA</AddressId>
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>MyTown</City>
<Country>Canada</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>123 Main St</StreetAddress>
</Account_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "N">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<AddressId>1-3JGOB</AddressId>
<City>YourTown</City>
<Country>Canada</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>456 Oak St</StreetAddress>
</Account_BusinessAddress>
</ListOfAccount_BusinessAddress>
<ListOfContact>
<Contact>
<ActiveStatus>Y</ActiveStatus>
<FirstName>User1</FirstName>
<LastName>User1</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
<Contact>
<ActiveStatus>Y</ActiveStatus>
<FirstName>User2</FirstName>
<LastName>User2</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
<ListOfContact_Organization>
<Contact_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationIntegrationId/>
</Contact_Organization>
</ListOfContact_Organization>
<ListOfContact_AlternatePhone/>
</Contact>
</ListOfContact>
<ListOfAccount_Organization>
<Account_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationId>0-R9NH</OrganizationId>
<OrganizationIntegrationId/>
</Account_Organization>
</ListOfAccount_Organization>
</Account>
</ListOfAccount>
</SiebelMessage>
And the following integration object instance is passed in:
<?xml version = "1.0" encoding = "UTF-8"?> <?Siebel-Property-Set EscapeNames="false"?> <SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType = "Integration Object" IntObjectFormat = "Siebel Hierarchical"> <ListOfAccount> <Account> <AccountStatus>Active</AccountStatus> <CSN>1-3JGO7</CSN> <Competitor>Y</Competitor> <CurrencyCode>USD</CurrencyCode> <LanguageCode>CHS</LanguageCode> <Location>test</Location> <Name>ABC Corp</Name> <ListOfContact/> </Account> </ListOfAccount> </SiebelMessage>
After the sync operation, all the children contacts are deleted because none of the nodes match.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CSN>1-3JGO7</CSN>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>ENU</LanguageCode>
<Location>test</Location>
<Name>ABC Corp</Name>
<ListOfAccount_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "Y">
<AddressId>1-3JGOA</AddressId>
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<City>MyTown</City>
<Country>Canada</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>123 Main St</StreetAddress>
</Account_BusinessAddress>
<Account_BusinessAddress IsPrimaryMVG = "N">
<AddressActiveStatus>Y</AddressActiveStatus>
<BillAddressFlag>Y</BillAddressFlag>
<AddressId>1-3JGOB</AddressId>
<City>YourTown</City>
<Country>Canada</Country>
<MainAddressFlag>Y</MainAddressFlag>
<ShipAddressFlag>Y</ShipAddressFlag>
<StreetAddress>456 Oak St</StreetAddress>
</Account_BusinessAddress>
</ListOfAccount_BusinessAddress>
<ListOfAccount_Organization>
<Account_Organization IsPrimaryMVG = "Y">
<Organization>Default Organization</Organization>
<OrganizationId>0-R9NH</OrganizationId>
<OrganizationIntegrationId/>
</Account_Organization>
</ListOfAccount_Organization>
</Account>
</ListOfAccount>
</SiebelMessage>
The following table is a high level representation of the operation.
This second example demonstrates how all records with an empty container are deleted when using the Synchronize method.
Table Representation of Records with Empty Containers Being Deleted Using Synchronize Method
| Record In Database | Integration Object Instance | Record After Synchronize Operation |
|---|---|---|
Account: ABC Corp
|
Account: ABC Corp
|
Account: ABC Corp
|
Insert Method
This method is also similar to the Synchronize method with the exception that the EAI Siebel Adapter generates an error if a matching root component is found; otherwise, it inserts the root component and synchronizes all the children. It is important to note that when you insert a record, there is a possibility that the business component would create default children for the record, which will be removed by the Insert method. The Insert method synchronizes the children, which deletes all the default children. For example, if you insert an account associated with a specific organization, then it will also be automatically associated with a default organization. As part of the Insert method, the EAI Siebel Adapter deletes the default association, and associates the new account with only the organization that was originally defined in the input integration object instance. The EAI Siebel Adapter achieves this by synchronizing the children.
Example of Using the Insert Method
If you use the Insert method with the example of the integration object instance represented in XML that follows, then a new service request is created with two activities.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2R6E" IntObjectName = "Sample Service Request"
MessageType = "Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfSampleServiceRequest>
<ServiceRequest>
<Account>Genesys Communications</Account>
<AccountLocation>San Francisco, CA</AccountLocation>
<Area>Network</Area>
<ClosedDate/>
<CommitTime/>
<ContactBusinessPhone>4155551100</ContactBusinessPhone>
<ContactLastName>Kastrup-Larsen</ContactLastName>
<Description>Setting up Router services<Description>
<Priority>3-Medium</Priority>
<SRNumber>1-MYUNIQUEVALUE</SRNumber>
<ServiceRequestType>External</ServiceRequestType>
<ListOfAction>
<Action>
<BillableFlag>N</BillableFlag>
<Description2>test activity1</Description2>
<EstWorkTimeRemaining>8</EstWorkTimeRemaining>
<Planned/>
<PrimaryOwnedBy>SADMIN</PrimaryOwnedBy>
<RowStatusOld>N</RowStatusOld>
<Status>Unscheduled</Status>
<Type>Appointment</Type>
</Action>
<Action>
<BillableFlag>N</BillableFlag>
<Description2>test activity2</Description2>
<EstWorkTimeRemaining>8</EstWorkTimeRemaining>
<Planned/>
<PrimaryOwnedBy>SADMIN</PrimaryOwnedBy>
<Status>Unscheduled</Status>
<Type>Appointment</Type>
</Action>
</ListOfAction>
</ServiceRequest>
</ListOfSampleServiceRequest>
</SiebelMessage>
For this example to work, you must have the contact, Kastrup-Larsen, in the database. If you try the Insert method against a server database where the contact does not exist, then you will receive the following error:
Picklist validation of field 'Contact Last Name' in integration component 'Service Request' did not find any matches satisfying the query '[Last Name] = "Kastrup- Larsen"', and an attempt to create a new record through the picklist failed (SBL- EAI-04186)
Also, if you try to insert the previous instance a second time, then you will receive the following error message:
IDS_ERR_EAI_SA_INSERT_MATCH_FOUND. Insert operation on integration component 'Service Request' failed because a matching record in business component 'Service Request' with search specification '[SR Number] = "1-MYUNIQUEVALUE" was found.(SBL- EAI-04383).
Upsert Method
The Upsert method is similar to the Synchronize method with one exception; the Upsert method does not delete any records.
The Upsert method will result in insert or update operations. If the record exists, then it will be updated. If the record does not exist, then it will be inserted. Unlike the Synchronize method, upsert will not delete any children.
To determine if an update or insert is performed, the EAI Siebel Adapter runs a query using user keys fields or the search specifications to determine if the parent or primary record already exists. If the parent record exists, it will be updated. If no matching parent record is found, then the new record will be inserted. Once again, upsert will not delete any children. If existing children are found, then they are updated.
You can update multiple corresponding top-level (highest-level) parent business component records using one XML file, as in the following example:
<SiebelMessage MessageId="" MessageType="Integration Object" IntObjectName="Transaction"> <ListofTransaction> <Transaction> <Field1>xxxx</Field1> <Field2>yyyy</Field2> ... </Transaction> <Transaction> <Field1>aaaa</Field1> <Field2>bbbb</Field2> ... </Transaction> ... </ListofTransaction> </SiebelMessage>
Update Method
This method is similar to the Synchronize method, except that the EAI Siebel Adapter returns an error if no match is found for the root component; otherwise, it updates the matching record and synchronizes all the children.
For example, if you send an order with one order item to the EAI Siebel Adapter, then it will take the following actions:
Queries for the order, and if it finds a match, then it updates the record.
Updates or inserts the new order item depending on whether a match was found for the new order item.
Deletes any other order items associated with that order.
Delete Method
You can delete one or more records in a business component that is mapped to the root integration component, given an integration object instance. A business component record is deleted as specified by an integration object instance. The integration component instance fields are used to query the corresponding business component and any records retrieved will be deleted. You call the Delete method using only one of the following method arguments:
A Query By Example (QBE) integration object instance.
A Primary Row Id and Output Integration Object Name.
A Search Specification.
For example, if you pass in this XML document, then the Test Account account is deleted.
<?xml version = "1.0" encoding = "UTF-8"?> <?Siebel-Property-Set EscapeNames="false"?> <SiebelMessage MessageId = "1-2IOY" IntObjectName = "EAI Account" MessageType = "Integration Object" IntObjectFormat = "Siebel Hierarchical"> <ListOfAccount> <Account> <Name>Test Account</Name> <Location>EMV</Location> </Account> </ListOfAccount> </SiebelMessage>
Any child contacts that once belonged to the account will still remain in the database, but will not be associated with this Account.
Execute Method
The Execute method can be specified on the EAI Siebel Adapter to perform combinations of various operations on components in an integration object instance. This method uses the following operations:
query
querypage (same as query when used as children operation)
sync (the same method as Synchronize and is the default operation)
upsert
update
updatesync
insert
insertsync
delete
skipnode
skiptree
none
These operations perform the same tasks as the related methods. For example, the delete operation makes the EAI Siebel Adapter delete the business component record matched to the particular integration component instance. However, what will be done to the children depends on the combination of the parent operation and the child operation. For information, see About Execute Method Operations.
An XML document sent to a Siebel application can include operations that describe whether a particular data element must be inserted, updated, deleted, synchronized, and so on. These operations can be specified as an attribute at the component level. They cannot be specified for any other element.
The following XML example demonstrates using the upsert and delete operation to delete a particular child record without updating the parent:
<SiebelMessage MessageId="" MessageType="Integration Object" IntObjectName="Sample
Account">
<ListofSampleAccount>
<Account operation="upsert">
<Name>A. K. Parker Distribution</Name>
<Location>HQ-Distribution</Location>
<Organization>North American Organization</ Organization>
<Division/>
<CurrencyCode>USD</CurrencyCode>
<Description>This is the key account in the AK Parker Family</
Description>
<HomePage>www.parker.com</HomePage>
<LineofBusiness>Manufacturing</LineofBusiness>
<ListOfContact>
<Contact operation="delete">
<FirstName>Stan</FirstName>
<JobTitle>Senior Mgr of MIS</JobTitle>
<LastName>Graner</LastName>
<MiddleName>A</MiddleName>
<PersonalContact>N</PersonalContact>
<Account>A. K. Parker Distribution</Account>
<AccountLocation>HQ-Distribution</AccountLocation>
</Contact>
</ListOfContact>
</Account>
</ListofSampleAccount>
</SiebelMessage>
About Execute Method Operations
Specify an attribute named operation, in lowercase, to the component’s XML element. The legal values for this attribute are upsert, sync, delete, query, update, insert, updatesync, insertsync, skipnode, skiptree, and none. If the operation is not specified on the root component, then the sync operation is used as the default.
Each child node inherits the operation from the parent if another operation is not explicitly specified. If another operation is explicitly specified, then the following table represents the results of the operation on the current node.
Table Operation Outcomes for the Child Node
| Operation | What Happens to the Current Node | What Happens to Unmatched Children of Current Node |
|---|---|---|
upsert |
Update or insert |
Leave alone |
sync |
Update or insert |
Delete |
update |
Update |
Delete |
updatesync |
Update |
Delete |
insert |
Insert |
Leave alone |
insertsync |
Insert |
Delete |
skipnode |
Skip this node |
Leave alone |
skiptree |
Skip the tree |
Not applicable |
Example of a Parent Node Using a Sync Operation
This example demonstrates the effects of records after a sync operation is performed. The following table is a high level representation of a parent node using the sync operation of the Execute method.
Table Representation of a Parent Node Using the Sync Operation
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Contact1 |
Account1 Contact1 Contact2 |
Account1 Contact1 Contact2 |
Record in Database
The following code represents GENCOMM0 and GENCOMM1 being retrieved as the contacts for this example:
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Active</AccountStatus>
<CurrencyCode>USD</CurrencyCode>
LanguageCode>ENU</LanguageCode>
<Location>San Francisco, CA</Location>
<Name>GenComm</Name>
<ListOfContact>
<Contact>
<FirstName>GENCOMM0</FirstName>
<LastName>GENCOMM0</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
<Contact>
<FirstName>GENCOMM1</FirstName>
<LastName>GENCOMM1</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
</ListOfContact>
/Account>
</ListOfAccount>
</SiebelMessage>
Integration Object Instance
The following code represents the sync operation acting on the contacts from the database.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account operation="sync">
<AccountStatus>Inactive</AccountStatus>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>ENU</LanguageCode>
<Location>San Francisco, CA</Location>
<Name>GenComm</Name>
<ListOfContact>
<Contact>
<FirstName>GENCOMM1</FirstName>
<LastName>GENCOMM1</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
<Contact>
<FirstName>GENCOMM2</FirstName>
<LastName>GENCOMM2</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
</ListOfContact>
</Account>
</ListOfAccount>
</SiebelMessage>
Result Record in Database
The following code represents the results of the sync operation after acting on the two contacts from the database.
<?xml version = "1.0" encoding = "UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId = "1-2QY5" IntObjectName = "EAI Account" MessageType =
"Integration Object" IntObjectFormat = "Siebel Hierarchical">
<ListOfAccount>
<Account>
<AccountStatus>Inactive</AccountStatus>
<CurrencyCode>USD</CurrencyCode>
<LanguageCode>ENU</LanguageCode>
<Location>San Francisco, CA</Location>
<Name>GenComm</Name>
<ListOfContact>
<Contact>
<FirstName>GENCOMM1</FirstName>
<LastName>GENCOMM1</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
<Contact>
<FirstName>GENCOMM2</FirstName>
<LastName>GENCOMM2</LastName>
<MiddleName/>
<Organization>Default Organization</Organization>
</Contact>
</ListOfContact>
</Account>
</ListOfAccount>
</SiebelMessage>
In this case, if a matching Account1 exists in the database, then the EAI Siebel Adapter will perform an update of that record. If no record matching Account1 exists, then the EAI Siebel Adapter will insert a new account.
For all the matching child contacts, the sync operation is inherited. Therefore, if the child exists, then it will be updated. If the child does not exist, then it is inserted. Any child contacts that exist in the database but do not match the integration object instance (unmatched children) are deleted.
The reason for this logic is that the sync operation makes the record in the database look like the integration object instance.
Example of a Parent Node Using an Update Operation
This example demonstrates the effects of records after an update operation is performed. the following table is a high level representation of a parent node using the update operation of the Execute method.
Table Representation of a Parent Node Using the Update Method
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Contact1 |
Account1 Contact1 Contact2 |
Account1 Contact1 Contact2 |
In this case, if a record matching Account1 exists in the database, then the EAI Siebel Adapter updates that specific record. If no matching account exists, then the result of the EAI Siebel Adapter is an error with this message:
Insert operation on integration component 'Account' failed because a matching record in business component 'Account' with search specification '[Name] = "GenComm" AND [Location] = "San Francisco, CA"' was found (SBL-EAI-04383)
For all the matching child contacts, the update operation is inherited. Therefore, if the child exists, then it will be updated. If the child does not exist, then it is inserted. For child contacts that exist in the database but do not match the integration object instance, they will be deleted. These might be child contacts created or associated with the Account by default.
This is very similar to the previous example except the record must exist in the database.
Example of a Parent Using an Update Operation and One More Child Using an Insert Operation
This example demonstrates the effects on records after an update operation acts on the parent, and an insert operation acts on one of the children records. The following table is a high level representation of this example.
Table Representation of Two Operations
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Contact1 |
Account1 Contact1 Contact2 |
Account1 Contact1 Contact2 |
In this case, if a record matching Account1 exists in the database, then the EAI Siebel Adapter updates that record. If no record matching Account1 exists, then the result from the EAI Siebel Adapter is an error.
You can also override the parent operation as in the case for Contact2. Since Contact2 does not exist, and there is an explicit insert operation, it will be inserted. Any unmatched children will be deleted as part of the parent operation (update). This is the reason why Contact0 is deleted.
If you are explicitly overriding the parent operation, then you must make sure the operation applies. For example, the two combinations in the following table and the second table in this topic will fail. In the following table, it fails because an insert is attempted when Contact1 already exists in the database.
Table Representation of Overriding a Parent Operation Using Insert
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Contact1 |
Account1 Contact1 Contact2 |
None |
In the following table, the update fails because SubContact3 inherits from Contact2's operation, and Subcontact3 does not exist in the database.
Table Representation of Overriding a Parent Operation Using Update
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact1 Contact2 SubContact1 SubContact2 |
Account1 Contact1 Contact2 SubContact1 SubContact3 |
None |
Example of a Parent Using the Update Operation and One More Child Using the Upsert Operation
This example demonstrates the effects of records after an update operation acts on the parent, and an upsert operation acts on one of the children records. The following table is a high level representation of this example.
Table Representation of Overriding a Parent Operation Using Upsert
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Contact1 |
Account1 Contact1 Contact2 |
Account1 Contact1 Contact2 |
In this case, if a record matching Account1 exists in the database, then the EAI Siebel Adapter updates that record. If no record matching Account1 exists, then the result of the EAI Siebel Adapter is an error.
For a record matching Contact2, the upsert operation overrides the update operation. Therefore, if Contact2 exists, then it is updated. If no record matching Contact2 is found, then it is inserted. Unmatched child contacts are deleted.
Example of a Parent Using the Upsert Operation and One More Child Using the Sync Operation
This example demonstrates the effects of records after an update operation acts on the parent, and a sync operation acts on one of the children records. The following table is a high level representation of this example.
Table Representation of Overriding a Parent Operation Using Sync
| Record In Database | Integration Object Instance | Record After Execute Operation |
|---|---|---|
Account1 Contact0 Organization2 Contact1 Organization2 Contact2 Organization2 |
Account1 Contact1 Organization1 Contact2 Organization3 |
Account1 Contact0 Organization2 Contact1 Organization1 Organization2 Contact2 Organization3 |
In this case, if a record matching Account1 exists in the database, then the EAI Siebel Adapter updates that record. If no record matching Account1 exists, then the EAI Siebel Adapter inserts the record.
For all child contacts, the upsert operation applies. Therefore, if the child exists, then it is updated. If the child does not exist, then it is inserted. For child contacts that exist in the database, but do not match the integration object instance, they will remain unchanged because upsert does not delete children.
In the case of Contact2, which has the sync operation overriding the upsert operation, it is updated, and its children are synchronized.
Skiptree Operation
The whole sub tree rooted at this node is not processed. It is the same as that whole sub tree not existing in the integration object instance. Operations specified in child nodes do not affect processing in any way since the EAI Siebel Adapter does not act on the child.
<?xml version="1.0" encoding="UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId="1-2RE" MessageType="Integration Object"
IntObjectName="Sample Account" IntObjectFormat="Siebel Hierarchical">
<ListOfSampleAccount>
<Account operation="upsert">
<Name>foo </Name>
<Location>cold storage</Location>
<ListOfContact>
<Contact operation="skiptree">
<FirstName>firstname</FirstName>
<LastName>contact1</LastName>
<Organization>Default Organization</Organization>
<PersonalContact>N</PersonalContact>
<ListOfBusinessAddress>
<BusinessAddress operation="insert">
<City>San Mateo</City>
<Zip>94402</Zip>
<AddressName>primary address</AddressName>
</BusinessAddress>
</ListOfBusinessAddress>
</Contact>
<Contact>
<FirstName>firstname</FirstName>
<LastName>contact2</LastName>
<Organization>Default Organization</Organization>
<PersonalContact>N</PersonalContact>
</Contact>
</ListOfContact>
</Account>
</ListOfSampleAccount>
</SiebelMessage>
Based on this example, the account is upserted. The processing of the first contact is completely skipped although the business address child has an insert operation set. Also, the second contact is upserted.
If the skiptree operation is specified for the account integration component, then the EAI Siebel Adapter skips processing the complete account. This results in no operation. It is possible to have many accounts with some having skiptree specified as shown in the following example. The EAI Siebel Adapter processes the trees that do not have skiptree specified.
<?xml version="1.0" encoding="UTF-8"?> <?Siebel-Property-Set EscapeNames="false"?> <SiebelMessage MessageId="1-2RE" MessageType="Integration Object" IntObjectName="Sample Account" IntObjectFormat="Siebel Hierarchical"> <ListOfSampleAccount> <Account operation="skiptree"> <Name>foo</Name> <Location>cold storage<Location/> </Account> <Account operation="upsert"> <Name>bar</Name> <Location>cold storage<Location/> </Account> </ListOfSampleAccount> </SiebelMessage>
Skipnode Operation
Similar to all other Execute operations, the children nodes inherit the semantics of the operation from the parent nodes. If a node has the skipnode operation set, then the EAI Siebel Adapter will skip setting field values for all children unless a child has an explicit operation set that will override.
<?xml version="1.0" encoding="UTF-8"?>
<?Siebel-Property-Set EscapeNames="false"?>
<SiebelMessage MessageId="1-2RE" MessageType="Integration Object"
IntObjectName="EAI Account" IntObjectFormat="Siebel Hierarchical">
<ListOfAccount>
<Account operation="skipnode">
<Name>foo</Name>
<Location>cold storage</Location>
<ListOfContact>
<Contact operation="upsert">
<IntegrationId>1-123</IntegrationId>
<FirstName>firstname</FirstName>
<LastName>contact1</LastName>
<ListOfContact_Organization>
<Contact_Organization>
<Organization operation="insert">MyOrganization</Organization>
</Contact_Organization>
</ListOfContact_Organization>
</Contact>
<Contact operation="upsert">
<IntegrationId>2-123</IntegrationId>
<FirstName>firstname</FirstName>
<LastName>contact2</LastName>
</Contact>
</ListOfContact>
</Account>
</ListOfAccount>
</SiebelMessage>
Based on this example, the account is skipped. However, the EAI Siebel Adapter will attempt to insert the two contacts.
EAI Siebel Adapter Business Service Method Arguments
Each of the EAI Siebel Adapter methods takes arguments that allow you to specify required and optional information to the adapter. You can locate the arguments for each method (and whether it can be used as an input argument, output argument, or both) in the following table.
Table EAI Siebel Adapter Business Service Method Arguments
| Argument | Query | Query Page | Sync | Upsert | Update | Insert | Delete | Execute |
|---|---|---|---|---|---|---|---|---|
BusObjCacheSize |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
DeleteByUserKey |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
Input |
ErrorOnNonExisting Delete |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
Input |
ExecutionMode |
Input |
Input |
not applicable |
Input |
Input |
Input |
not applicable |
Input |
IntObjectName |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
Input |
LastPage |
not applicable |
Output |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Output |
MessageId |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
NewQuery |
not applicable |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
NumOutputObjects |
Output |
Output |
Output |
Output |
Output |
Output |
Output |
Output |
OutputIntObject Name |
Input |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
PageSize |
not applicable |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
PrimaryRowId |
Input |
not applicable |
Output |
Output |
Output |
Output |
Input |
Input/Output |
QueryByUserKey |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
SearchSpec |
Input |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
Input |
SiebelMessage |
Input/Output |
Output |
Input/Output |
Input/Output |
Input/Output |
Input/Output |
Input/Output |
Input/Output |
SortSpec |
not applicable |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
StartRowNum |
not applicable |
Input |
not applicable |
not applicable |
not applicable |
not applicable |
not applicable |
Input |
StatusObject |
not applicable |
not applicable |
Input |
Input |
Input |
Input |
Input |
Input |
ViewMode |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
Input |
The following table presents each argument of the EAI Siebel Adapter business service methods.
Table Defining EAI Siebel Adapter Business Service Method Arguments
| Argument | Display Name | Description |
|---|---|---|
BusObjCacheSize |
Business Object Cache Size |
Default is 5. Maximum number of Business Objects instances cached by the current instance of the EAI Siebel Adapter. If set to zero, then the EAI Siebel Adapter does not use the cache. |
DeleteByUserKey |
Delete By User Key |
A Boolean argument. Forces the EAI Siebel Adapter to use only the user keys to identify a record. |
ErrorOnNonExisting Delete |
Error On Non Existing Delete |
A Boolean argument. Determines whether or not the EAI Siebel Adapter aborts the operation if no match is found. |
ExecutionMode |
Execution Mode |
Used to set the direction of a query on a business component. Valid values are ForwardOnly and Bidirectional. The default is Bidirectional. ForwardOnly is more efficient than Bidirectional, and is recommended in cases where you must process a large number of records in the forward direction only (such as for report generation). For operations that are likely to return more than 10000 records, use ForwardOnly to avoid errors. For more information on executing queries, see the topic on the ExecuteQuery business component method in Siebel Object Interfaces Reference. |
IntObjectName |
Integration Object Name |
Name of the integration object to delete. |
LastPage |
Last Page |
Boolean indicating whether or not the last record in the query result set has been returned. |
MessageId |
Message Id |
The MessageId can be used to specify the ID for the generated message. By default, the EAI Siebel Adapter generates a unique ID for each message. However, if you want to use the workflow instance ID, then you can use this argument to specify the ID. |
NewQuery |
New Query |
Default is False. Boolean indicating whether a new query will be executed. If set to True, a new query is executed flushing the cache for that particular integration object. |
NumOutputObjects |
Number of Output Integration Objects |
Number of output integration objects. |
OutputIntObjectName |
Output Integration Object Name |
The name of the integration object that is to be output. |
PageSize |
Page Size |
Default is 10. Indicates the maximum number of integration object instances to be returned. |
PrimaryRowId |
Object Id |
The PrimaryRowId refers to the Id field in the Business Component, Row_Id at the table level. PrimaryRowId is only returned as an output argument if you are passing in one integration object instance. If you are passing multiple integration object instances, then this argument is not returned as an output argument. To obtain the ID field when multiple integration objects are processed, use the StatusObject argument. |
QueryByUserKey |
Query By Key |
A Boolean argument. Forces the EAI Siebel Adapter to use only the user keys to perform a query. |
SearchSpec |
Search Specification |
This argument allows you to specify complex search specifications as free text in a single method argument. For information, see About Using Language-Independent Code with the EAI Siebel Adapter Business Service. |
SiebelMessage |
Siebel Message |
The input or the output integration object instance. |
SortSpec |
Sort Specification |
Default is the SortSpec of the underlying business component. This argument allows you to specify complex sort criteria as a free text in a single method argument, using any business component fields and standard Siebel sort syntax. For examples, see Using Siebel Tools. |
StartRowNum |
Starting Row Number |
Default is 0 (first page). Indicates the row in the result set for the QueryPage method to start retrieving a page of records. |
StatusObject |
Status Object |
This argument tells the EAI Siebel Adapter whether or not to return a status message. |
ViewMode |
View Mode |
Default is All. Visibility mode to be applied to the Business Object. Valid values are: Manager, Sales Rep, Personal, Organization, Sub-Organization, Group, Catalog, and All. Note that the ViewMode user property on the integration object has priority over the ViewMode method argument. |
About the Search Spec Input Method Argument
The SearchSpec input method argument is applicable to the QueryPage, Query, Delete, and Execute methods. This method argument allows you to specify complex search specifications as free text in a single method argument. Expressions within a single integration component are restricted only by the Siebel Query Language supported by the Object Manager. Integration components and fields are referenced using the following notation:
[IntCompName.IntCompFieldName]
For example, given an integration object definition with two integration components, Account as the root component and Contact as the child component, the following search specification is allowed:
([Account.Site] LIKE "A*" OR [Account.Site] IS NULL) AND [Contact.PhoneNumber] IS NOT NULL
This search specification queries accounts that either have a site that starts with the character A, or do not have a site specified. In addition, for the queried accounts, it queries only those associated contacts who have a phone number.
You can include the child integration component in a search specification only if its parent components are also included.
About Multivalue Groups in the EAI Siebel Adapter Business Service
Multivalue groups (MVGs) in the business components are mapped to separate integration components. Such integration components are denoted by setting a user property MVG on the integration component to Y. For information on MVGs, see Integration Objects.
An integration component instance that corresponds to a primary MVG is denoted by the attribute IsPrimaryMVG set to Y. This attribute is a hidden integration component field and does not have a corresponding business component field.
Each MVG that appears on the client UI is mapped to a separate integration component. For example, in the Orders Entry - Orders screen, there is an account address, a bill-to address, and a ship-to address. Each of these MVGs needs a separate integration component definition. Each field defined for an integration component (represented by the class CSSEAIIntCompFieldDef) maps to a field in the MVG. For such fields, External Name denotes the name of the business component field as it appears on the master business component, and the user property MVGFieldName denotes the name of the business component field as it appears on the MVG business component.
Setting a Primary Position for a Contact
You have a contact with multiple contact positions in a Siebel application. None of these positions are marked as the primary position for the contact, and you want to select one of them as the primary position.
To specify a contact position as a primary
Create your XML file and insert
<IsPrimaryMVG='Y'>before the contact position you want to identify as the primary position for the contact as follows:<?xml version="1.0" encoding="UTF-8" ?> <?Siebel-Property-Set EscapeNames="false"?> - <SiebelMessage MessageId="1-69A" IntObjectFormat="Siebel Hierarchical" MessageType="Integration Object" IntObjectName="Sample Contact"> - <ListOfSampleContact> - <Contact> <FirstName>Pal888</FirstName> <IntegrationId>65454398</IntegrationId> <JobTitle>Manager</JobTitle> <LastName>John888</LastName> <MiddleName /> <PersonUId>1-Y88H</PersonUId> <PersonalContact>N</PersonalContact> - <ListOfContact_Position> - <Contact_Position IsPrimaryMVG="Y"> <EmployeeFirstName>Siebel</EmployeeFirstName> <EmployeeLastName>Administrator</EmployeeLastName> <Position>Siebel Administrator</Position> <RowStatus>N</RowStatus> <SalesRep>SADMIN</SalesRep> </Contact_Position> </ListOfContact_Position> </Contact> </ListOfSampleContact> </SiebelMessage>.
Use the Upsert or Sync method to update the account.
About Using Effective Dating with Siebel EAI Adapter Business Service
The Siebel EAI Adapter allows you to access effective dating data, which means the start date and end date for a given field or link. Third-party applications can request and receive effective dating data from the Siebel application.
To view XML samples for effective dating functionality see Enabling Effective Dating on Fields.
You specify effective dating on fields of a given business component through a Siebel Web Client administration screen. For more information, see Enabling Effective Dating on Fields. Two integration component fields attributes allow you to set effective dating: EDStartDate and EDEndDate. Standard querying techniques, such as query, insert, update, sync can be used to request effective dating-enabled data.
As the following figure shows, the Siebel Object Manager framework features APIs which are called by the Siebel EAI Adapter when an integration object with effective dating enabled fields or links is read by the XML Converter.
The following two topics explain how effective dating works:
Enabling Effective Dating on Fields
This topic explains how effective dating works on fields. It contains the following topics:
Configuring Integration Components for Effective Dating on Fields
You can enable effective dating on a field in an existing integration object if the corresponding field in the business component is effective dating-enabled. You enable fields for effective dating through the Siebel Web Client administration Effective Dating screen.
To enable effective dating on fields
In the Siebel Web Client, navigate to Administration - Effective Dating, then Field.
In the Effective Dating Buscomp list, select the required business component.
The list displays the fields already enabled for ED.
If you want enable effective dating field not present in this list, click New, then in the Field field click the Select button.
In the Business Component Fields window select the required field, then click OK.
This enables the fields for ED.
You use Siebel Tools to synchronize the object from your current repository, with its underlying business object in the Siebel database which contains the new EDEnabled user property. For more information on synchronizing integration objects, see Synchronizing Integration Objects.
To enable effective dating on an integration object
In Siebel Tools, select the integration object you want to enable for effective dating.
Click the Synchronize button in the Integration Objects list.
The Integration Object Synchronize wizard appears.
Click the plus symbol to display all the related integration components.
Uncheck the boxes beside the objects and components you do not want to include in the synchronization of your Siebel integration object.
Locate the integration component containing the effective dating-enabled fields and drill down on it.
Click the plus symbol to display all the user properties of the field.
Locate the EDEnabled user property from the list and add it to the repository side.
Review the summary, and if changes are needed, click Back and make the needed changes.
If no changes are needed, click Finish to synchronize the Siebel integration object and the Siebel business object.
How the XML Converter Reads Effective Dating Data from Fields
The XML converter reads effective dating attributes contained in an XML file, maps them to a property set, and converts the property set to an integration object instance by embedding the EDStartDate and EDEndDate attributes inside the field name.
For example: If a SOAP request contains the following query for an effective dating field:
<acc:EDListOfFirstName> <acc:FirstName EDStartDate="04/01/2012" EDEndDate=">James</acc:FirstName> </acc:EDListOfFirstName>
The data will be converted into a child property set of the integration component instance as follows:
c[0] CCFPropertySet@1DA79960 p#0 c#1 type="ListOfRelated Contact" vt=0 value="
{
c[0] CCFPropertySet@1D9FD870 p#1 c#2 type="Related Contact" vt=0 value="
{
p["Contact Id"] = "Contact1";
c[0] CCFPropertySet@1FD92BB0 p#0 c#1 type="EDListOfFirst Name" vt=0 value="
{
c[0] CCFPropertySet@13258470 p#2 c#0 type="First Name" vt=3 value="James"
{
["EDEndDate"] = ";
["EDStartDate"] = "04/25/2012";
}
}
}
}
The dates are now embedded into the field name.
WSDL Schema Generation for Effective Dating on Fields
Effective dating requires two complex type attributes StartDate and EndDate for each effective dating-enabled field. In the following schema example the location field is enabled for effective dating, as shown by the two additional attributes EDStartDate and EDEndDate. Historical data can be retrieved by setting the cardinality of the effective dating-enabled XSD element to unbounded.
WSDL Schema Example
<xsd:complexType name="RelatedContact"> <xsd:sequence> <xsd:element name="ContactId" maxOccurs="1" minOccurs="0" type="xsd:string"/> <xsd:element name="EDListOfFirstName" maxOccurs="1" minOccurs="0" type="xsdLocal1:EDListOfFirstName"/> <xsd:element name="ContactIntegrationId" maxOccurs="1" minOccurs="0" type="xsd:string"/> <xsd:element name="EDListOfLastName" maxOccurs="1" minOccurs="0" type="xsdLocal1:EDListOfLastName"/> . . . . </xsd:sequence> </xsd:complexType> <xsd:complexType name="EDListOfFirstName"> <xsd:sequence> <xsd:element name="FirstName" maxOccurs="unbounded" minOccurs="0" type="xsdLocal1:FirstName"/> </xsd:sequence> </xsd:complexType> <xsd:complexType name="FirstName"> <xsd:simpleContent> <xsd:extension base="xsd:string"> <xsd:attribute name="EDStartDate" type="xsd:string"/> <xsd:attribute name="EDEndDate" type="xsd:string"/> </xsd:extension> </xsd:simpleContent> </xsd:complexType>
SOAP Query Example
The previous WSDL schema example allows you to generate the following SOAP query:
<ElementName EDStartDate=dd1/mm1/yyyy1, EDEndDate = dd2/mm2/yyy2>value</ElementName>
For example:
<acc:RelatedContact> <acc:ContactId>88-30ARL</acc:ContactId> <acc:EDListOfFirstName> <acc:FirstName EDStartDate="04/01/2012" EDEndDate=">James</acc:FirstName> </acc:EDListOfFirstName> <acc:EDListOfLastName> <acc:LastName EDStartDate="04/01/2012" EDEndDate=">Bond</acc:LastName> </acc:EDListOfLastName> </acc:RelatedContact>
Similarly you can perform insert, update, and synchronize operations on data using the WSDL Schema example above.
Enabling Effective Dating on Links
This topic explains how to enable effective dating on links. It contains the following topics:
Enabling Effective Dating on Links
You can enable effective dating on a link in an existing integration object if the corresponding link in the business component is effective dating-enabled. You enable link for effective dating through the Siebel Web Client administration Effective Dating screen.
To enable effective dating on links
In the Siebel Web Client, navigate to Administration - Effective Dating, then Child Buscomp.
In the Effective Dating Buscomp list, select the required business component, then in the Child Buscomp view select the required link if it is shown.
If you need to create a new link, see Step 3.
Click New, then in the Link Name field click the Select button.
In the Link window select the required link, then click OK.
Web Service Schema Example
The following Web service schema example shows a link between the Household and Related Contact business components which have been enabled for effective dating. The effective dating attributes are displayed in bold text.
<xsd:complexType name="Household"> <xsd:complexType name="RelatedContact"> <xsd:attribute name="EDStartDate" type="xsd:string" /> <xsd:attribute name="EDEndDate" type="xsd:string" /> <xsd:sequence> <xsd:element name="ContactIntegrationId" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="EDListOfFirstName" maxOccurs="1" minOccurs="0" type="xsdLocal1:EDListOfFirstName"/> <xsd:element name="EDListOfLastName" maxOccurs="1" minOccurs="0" type="xsdLocal1:EDListOfLastName"/> <xsd:element name="MiddleName" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="PersonUId" maxOccurs="1" minOccurs="0" type="xsd:string" / > <xsd:element name="PersonalContact" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="ContactId" maxOccurs="1" minOccurs="0" type="xsd:string" / > <xsd:element name="DateEnteredHousehold" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="DateExitedHousehold" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="PrimaryOrganizationId" maxOccurs="1" minOccurs="0" type="xsd:string" /> <xsd:element name="Relationship" maxOccurs="1" minOccurs="0" type="xsd:string" /> </xsd:sequence> <xsd:attribute name="IsPrimaryMVG" type="xsd:string" /> </xsd:complexType> </xsd:complexType>
This will produce the following XML:
<hous:Household>
<hous:ListOfRelatedContact>
<hous:RelatedContact EDStartDate="1/1/2003" EDEndDate="">
<hous:ContactId>88-30KSP</hous:ContactId>
< hous:EDListOfFirstName>
< hous:FirstName EDStartDate="04/01/2012" EDEndDate="">SF1N6</acc:James>
</ hous:EDListOfFirstName>
< hous:EDListOfLastName>
< hous:LastName EDStartDate="04/01/2012" EDEndDate=">SL1N6</acc:Bond>
</ hous:EDListOfLastName>
< hous:MiddleName>MN1</hous:MiddleName>
</hous:RelatedContact>
</hous:ListOfRelatedContact>
</hous:Household>
Siebel EAI Adapter Operations for Effective Dating on Links
The Siebel EAI Adapter receives the integration object in the format described in the Enabling Effective Dating on Links. Depending on the specified operations the effective dates are used as described in the following:
Insert operation
Once the record is inserted into the parent and child business component, the Siebel EAI Adapter reads the EDStartDate and the EDEndDate from the integration object and inserts these values into the corresponding effective dating business component.
Update operation
Once the record is inserted into the parent and child business component, the Siebel EAI Adapter removes all history records from the effective dating enabled business component and then reads the EDStartDate and EDEndDate values from the integration object and inserts these dates as fresh records into the business component.
Upsert and Synchronize Operations
If the upsert attribute is specified for the operation in the integration component then no history records are deleted, instead the history given in the XML input is inserted into the history table.
The synchronize operation can result in the insert, update or deletion of the child integration component as specified in the conditions set in the Synchronize Method.
XML Example
This example illustrates what is required if you want to perform an insert or upsert operation to insert or update multiple history records for the same child business component.
<hous:Household> <hous:ListOfRelatedContact> <hous:RelatedContact EDStartDate="1/1/2003" EDEndDate="> <hous:ContactId>88-30KSP</hous:ContactId> </hous:RelatedContact> <hous:RelatedContact EDStartDate="1/1/2002" EDEndDate="12/31/2002"> <hous:ContactId>88-30KSP</hous:ContactId></hous:RelatedContact> <hous:RelatedContact EDStartDate="1/1/2001" EDEndDate="12/31/2001"> <hous:ContactId>88-30KSP</hous:ContactId> </hous:RelatedContact> <hous:RelatedContact EDStartDate="1/1/2000" EDEndDate="12/31/2000"> <hous:ContactId>88-30KSP</hous:ContactId> </hous:RelatedContact> <hous:ListOfRelatedContact> </hous:Household>
About Using Language-Independent Code with the EAI Siebel Adapter Business Service
If the user property AllLangIndependentVals is set to Y at the integration object level, then the EAI Siebel Adapter uses the language-independent code for its LOVs.
In the outbound direction, for example, the Query method, if the AllLangIndependentVals is set to Y, then the EAI Siebel Adapter translates the language-dependent values in the Siebel Database to their language-independent counterpart based on the List Of Values entries in the database.
In the inbound direction, for example the Synchronize method, if the AllLangIndependentVals is set to Y, then the EAI Siebel Adapter expects language-independent values in the input message, and translates them to language-dependent values based on the current language setting and the entries in the List Of Values in the database.
About LOV Translation and the EAI Siebel Adapter Business Service
The Siebel application distinguishes two types of lists of values (LOV):
Multilingual LOV (MLOV). Stores a language-independent code (LIC) in the Siebel Database that is translated to a language-dependent value (LDV) for active language by Object Manager. MLOVs are distinguished by having the Translation Table specified in the Column definition.
Single-language LOV. Stores the LDV for the current language in the Siebel Database. The Boolean integration object user property AllLangIndependentVals determines whether the EAI Siebel Adapter will use LDV (No = no translation necessary) or LIC (Yes = translation needed) for such LOVs.
Translating to LIC affects performance, but allows easier cooperation between systems that operate on different languages. This option is especially used by various import and export utilities.
The AllLangIndependentVals integration object user property is undefined for integration objects when the base object type is not Siebel Business Object. When the base object is Siebel Business Object, AllLangIndependentVals is defined with a default value of N.
The following table explains the behavior of the EAI Siebel Adapter according to the AllLangIndependentVals integration object user property values.
Table EAI Siebel Adapter’s Behavior for the User Property All LangIndependentVals
| AllLangIndependentVals | Yes | No | Undefined |
|---|---|---|---|
LOV |
LIC |
LDV |
LDV |
MLOV |
LIC |
LDV |
LIC |
Siebel EAI and Run-Time Events
The Siebel application allows triggering workflows based on run-time events or workflow policies.
Run-Time Events. Siebel EAI supports triggering workflows based on run-time events such as Write Record, which is triggered whenever a record is written. If you use the EAI Siebel Adapter to import data into Siebel Business Applications, and use run-time events, then consider the following:
For the EAI Siebel Adapter, one call to the EAI Siebel Adapter with an input message is a transaction. Within a transaction, the EAI Siebel Adapter makes multiple Write Record calls. At any point in the transaction, if the EAI Siebel Adapter encounters a problem the transaction is rolled back entirely. However, if you have specified events to trigger at Write Record, such events are called as soon as the EAI Siebel Adapter makes Write Record calls even though the EAI Siebel Adapter might be in the middle of a transaction. If you have export data workflows triggered on such events, this might lead to exporting data from Siebel Business Applications that is not committed and might be rolled back. It is also possible that your events are triggered when the record is not completely populated, which leads to situations that are not handled by your specified event processing workflow.
To avoid the effects of this interaction between the EAI Siebel Adapter and run-time events use the business service EAI Transaction Service to figure out if a transaction (typically, the EAI Siebel Adapter) is in progress. You might then want to skip processing that is not desirable when the EAI Siebel Adapter is in progress.
For example, suppose you have a workflow to export orders from Siebel Business Applications, which is triggered whenever the order record is written. You also import orders into Siebel Business Applications using EAI. In such a situation, you do not want to export orders while they are being imported, because the import might be aborted and rolled back. You achieve this using the EAI Transaction Service business service as the first step of the export workflow. If you find that a transaction is in process you can branch directly to the end step.
Workflow Policies. In addition to Run-Time Events, Siebel Business Applications also support Workflow Policies as a triggering mechanism for workflows. You can use workflow policies instead of run-time events to avoid the situation discussed in this topic. Use Workflow Policies instead of Run-Time Events when possible.
Guidelines for Using the EAI Siebel Adapter Business Service
The following guidelines are to be considered when using the EAI Siebel Adapter:
Keep the integration objects small. Basically, inactivate any unused fields in the integration component. Avoid creating large integration object instances.
Test the developed object definitions using the EAI Siebel Adapter before adding to production. You must test your input and output using working and negative scenarios. Also do performance testing to make sure you are satisfied with the performance of the input and the output.
Oracle does not support the use of EAI to update data that is based on administration-type business components such as Client - Mobile or Position. Only the System Administrator updates these types of data.
Always use a search specification with the Query() method to avoid receiving every object when run.
To optimize database performance, you can explicitly specify that the EAI Siebel Adapter use only user key fields. This feature is available for the methods Query, Delete, and Execute. To use it, set the input property QueryByUserKey to True for the EAI Siebel Adapter business service and pass an integration object instance (for example, a Siebel Message) as an input as well. By default, the Siebel adapter uses all the fields in the input integration object instance.
Troubleshooting the EAI Siebel Adapter Business Service
The EAI Siebel Adapter natively accesses Siebel objects definitions using the business objects, integration objects, and business component classes. Because of this design, you might get an EAI Siebel Adapter error that contains an error message from the Siebel Object Manager. See the figure in the topic About the Difference Between Integration Objects and Integration Object Instances for a logical overview of the Siebel architectural layers. The figure in the topic About the Difference Between Integration Objects and Integration Object Instances also shows the component events that will help you determine in which layer of the application the problem is occurring.
The EAI Siebel Adapter functionality must be considered in light of the entire application functionality. For example, the Siebel Communications product line provides preconfigured Asset Based Ordering functionality that uses Siebel workflows and business services. The workflows use the EAI Siebel Adapter business service to extract data from the database and to update the database.
When using this functionality, the possibility exists that you might get an error in a step of the workflow that indicates a problem with the EAI Siebel Adapter, such as the asset you want to insert already exists in the system. In this case, first verify that you are not inserting a duplicate asset. If you have validated that the asset is new and not a duplicate, then you must research the specifics as to why the EAI Siebel Adapter failed to insert the new asset or attempted to insert a duplicate asset.
If you have modified the preconfigured Asset integration object or business object, it could be one of your customizations. For example, perhaps your asset requires additional fields, and you are not providing those fields in your inbound integration object instance. Therefore, it uses any default values, thus creating a potential duplicate asset.
Enabling Logging for the EAI Siebel Adapter Business Service
Using component events, logging can be done in the Siebel application. Components are used to assist with the debugging of problems in the Siebel application. A list of useful and relevant component events for debugging EAI Siebel Adapter problems are listed in the following table. These components events can be enabled on any server component that is capable of running an EAI process and on the Siebel client. You might want to enable other events not listed in the following table.
Table Component Events for Debugging EAI Siebel Adapter Problems
| Event Alias Name | Logging Level | Description |
|---|---|---|
EAISiebAdpt |
4 or 5 |
Captures EAI Siebel Adapter related events, including integration component and integration component fields accessed and the values for the fields; business components and business component fields accessed and the values for the fields. This is the main event to enable for EAI Siebel Adapter troubleshooting. |
EAISiebAdptPerf |
4 |
Captures EAI Siebel Adapter performance related events, including operation performed and time for the operation in milliseconds. This event summarizes the result of the EAI Siebel Adapter operation. For more information on performance logging, see Troubleshooting the EAI Siebel Adapter Business Service and Doc ID 476905.1 on My Oracle Support. This document was previously published as Siebel FAQ 1840. |
EAISiebAdptSvcArgTrc |
3 or 4 |
Dumps the inputs and output arguments for the EAI Siebel Adapter when EnableServiceArgTracing=true. For more information on argument tracing, see Enabling Siebel Argument Tracing. |
EAITransaction |
4 |
Captures when an EAI Transaction starts. |
EAIInfra |
4 |
Output Message: IntObjType=Contact Interface Format=Siebel Hierarchical |
EAIQrySpec |
4 |
Captures the search specification if one is specified. |
SQL |
4 |
Captures SQL executed against the database. |
SQLParseAndExecute |
4 |
Captures SQL statements and shows SQL bind parameters executed. Shows SQL executed against the database. Might sometimes be different than the SQL show in ObjMgrSQLLog. |
ObjMgrLog |
4 or 5 |
Logs error code and error message encountered by various Siebel objects. |
ObjMgrDataLog |
4 |
Logs the beginning of a transaction for the database connection. |
ObjMgrBusServiceLog |
4 |
Captures creation, deletion and invocation of a Business Service. |
ObjMgrBusCompLog 4 |
4 or 5 |
Captures the beginning and end of the Business Component creation and deletion. |
For all the events listed in the previous table, setting the logging level to level 4 is sufficient for most types of testing. You can set the component event to level 5 if you want to see debug level output, but it is not generally recommended as it adds more lines of data to the log file that might or might not be helpful. Logging level 4/5 represents that a logging level of 4 or 5 is supported.
To enable EAI Siebel Adapter logging
Navigate to the Administration - Server Configuration screen, Servers view.
In the starting applet, select the Siebel Server that you want to enable EAI Siebel Adapter logging.
In the middle applet, select the Components tab, and highlight the component.
In the lower applet, select the Events tab, and set component events.
When you enable the component event logging, make sure you select the appropriate server component or components involved in the process. For example, if you are testing receiving XML data in the MQSeries Server Receiver, then you would enable logging on the MQSeriesSrvRcvr component.
You can also use the same srvrmgr command to turn on the component event logging. You will use the "%" shortcut syntax to enable events. An example of this syntax is "change evtloglvl EAISIEB%=4 for comp BusIntMgr".
Enabling Siebel Argument Tracing
You can also export input and output arguments in XML format to a file for the EAI Siebel Adapter. These XML files represent the input and output arguments integration object instances. This is a useful technique as it writes to a file the integration object instances in the directory where your Siebel process is running. For example, in the Siebel Developer Web Client, it might be c:/siebel/bin.
To enable output arguments tracing
Set the server parameter EnableServiceArgTracing to True:
If you are running the Siebel Developer Web Client, then add the following to your .cfg file:
[EAISubsys] EnableServiceArgTracing = TRUE
If you are running the Siebel Web Client, modify the following Siebel Server parameter for your object manager:
"EnableServiceArgTracing" = true
Set the appropriate component event level on your server component through the server manager on the server or SIEBEL_LOG_EVENTS in the Siebel Developer Web Client.
If you set event to:
=3, then input arguments will be written out to a file when an error happens.
=4, then input and output arguments will be written to a file.
Configuring the EAI Siebel Adapter Business Service for Concurrency Control
The EAI Siebel Adapter supports concurrency control to guarantee data integrity and avoid overriding data by simultaneous users or integration processes. To do so, the EAI Siebel Adapter uses the Integration Component Key called the Modification Key.
Modification Key
A Modification Key is an Integration Component Key of the type Modification Key. A Modification Key is a collection of fields that together are used to verify the version of an integration component instance. Typically, Modification Key fields are Mod Id fields for the tables used. Multiple Modification Key fields might be needed, because a business component might be updating multiple tables, either as extension tables, or through implicit or explicit joins.
The EAI Siebel Adapter methods (Insert, Update, Synchronize, Upsert) check for the existence of a Modification Key. If no Modification Key is specified in the integration component definition, or if Modification Key fields are not included in the XML request, then the EAI Siebel Adapter does not check for the record version and proceeds with the requested operation. If a valid Modification Key is found, but the corresponding record cannot be found, then the EAI Siebel Adapter assumes that the record has been deleted by other users and returns the error SSASqlErrWriteConflict.
If a valid Modification Key as well as the corresponding record can be found, then the EAI Siebel Adapter checks if the Modification Key fields in the XML request and the matched record are consistent. If any of the fields are inconsistent, then the EAI Siebel Adapter assumes that the record has been modified by other users and returns the error SSASqlErrWriteConflict. If all the fields are consistent, then the EAI Siebel Adapter proceeds with the requested operation.
Modification IDs
To determine which Mod Id fields must be used as part of a Modification Key, you expose Mod Id fields for tables whose columns might be updated by that integration object. In some situations you might have to add corresponding integration component fields as well as business component fields.
When using Modification IDs, the following behaviors are present:
All fields must be present in the integration object instance for the Mod Key to be used.
Only one defined Modification Key is present for each integration component. Unlike for User Keys, multiple Mod Keys are not allowed.
About the Modification ID for a Base Table
The integration component field Mod Id for a base table is created by the Integration Object Builder Wizard, but you must make sure it is active if it is needed for your business processes.
About the Modification ID for an Extension Table
An extension table’s Mod Id field is accessible as extension table name.Mod Id in the business component, for example, S_ORG_EXT_X.Mod Id. However, if your business processes require this field, then you must manually add it to the integration object definition by copying the Mod Id field and changing the properties.
About the Modification ID for a Joined Table
A joined table’s Mod Id field must be manually added in both business component and integration object definitions. Business component Mod Id fields for joined tables must:
Be prefixed with CX string and preferably followed by the name of the join
Be Joined over the correct join
Have MODIFICATION_NUM specified as underlying column of type DTYPE_INTEGER
About MVG and MVGAssociation Integration Components
For integration components that are of type MVG or MVGAssociation, in addition to the preceding steps, you must create user properties MVGFieldName and AssocFieldName for each Modification ID integration component field, respectively, and set the name of the field shown in the parent business component as the value.
To configure the EAI Siebel Adapter business service for concurrency control
For each integration component, identify all needed Modification IDs:
Note: In addition to the Modification ID for the base table, Modification IDs for tables that are used through one-to-one extension as well as through implicit joins are relevant. For example, on modifying an account record MODIFICATION_NUM column on S_ORG_EXT is updated, not the MODIFICATION_NUM column on S_PARTY.Identify all active fields in an integration component that will be updated and have to be concurrency safe.
Select the corresponding business component, the value in the External Name property of the integration component.
For each field identified in Step a, check the value of the Join property of the field. If the join is not specified, then the field belongs to the base table; otherwise, note the name of the join.
In the Object Explorer, select Business Component, then Join, and query for the business component from Step b. Search whether there is an entry whose Alias property matches the name of the join from Step c:
If a matching Alias is found, then this field belongs to a Joined Table. The name of the join in Step c is the join name, and the value of the Table property is the joined table.
If no Alias matches, then this is an implicit join to an Extension Table. The name of the join in Step cis the name of the extension table.
Create business component fields for Mod Ids of Joined Tables. For the previous example, create a new field in the business component Account with the following settings:
Name. CX_Primary Organization-S_BU.Mod Id
Join. Primary Organization-S_BU
Column. MODIFICATION_NUM
Type. DTYPE_INTEGER
Expose all Modification IDs identified in Step 1 as integration component fields.
For MVG and MVG Association integration components, add user property MVGFieldName and AssocFieldName respectively, on all Modification ID fields as follows:
Check the Integration Component User Prop sub type for user properties of the integration component.
If there is a user property called MVGAssociation, then the integration component is a MVG Association, but if there is a user property called Association then the integration component is a MVG.
Note: If the integration component is neither an MVG nor an MVG Association, then nothing is required to be done.
Repeat the following steps for each Modification ID field on the integration component:
Add user property MVGFieldName if MVG, or AssocFieldName if MVG Association.
Set the value of the user property to the same as the field name, for example, Mod Id, extension table name.Mod Id, or CX_join.Mod Id.
Create Modification Key.
Define a new integration component key of type Modification Key, and include all the integration component fields exposed in Step 3 to this key.
Validate integration objects and deliver the workspace.
Modify client program to use the Modification Key mechanism:
The client program must store the value of the Modification IDs when it queries data from the Siebel Database.
The client program must send exactly the same values of the Modification IDs that it retrieved from the Siebel Database when sending an update.
The client program must not send any Modification IDs when sending a new record to the Siebel application. If this is violated, then the client program generates an error indicating that the record has been deleted by another user.
Integration Component Account Example
Consider an integration component Account of the business component Account:
Field Home Page has property Join set to S_ORG_EXT. This is an implicit join, because it is not listed in the joins; therefore, this field belongs to Extension Table S_ORG_EXT.
Field Primary Organization has property Join set to Primary Organization-S_BU. This is an explicit join, because it is listed in the joins. The value of Table property is S_BU; therefore, this field belongs to Joined Table S_BU joined over Primary Organization-S_BU.
Activate integration component field Mod Id:
Set Name, External Name, XML Tag properties to Mod Id
Set External Data Type property to DTYPE_NUMBER
Set External Length property to 30
Set Type property to System
Add integration component field S_ORG_EXT.Mod Id:
Set Name, External Name, XML Tag properties to S_ORG_EXT.Mod Id
Set External Data Type property to DTYPE_NUMBER
Set External Length property to 30
Set Type property to System
Add integration component field CX_Primary Organization-S_BU.Mod Id:
Set Name, External Name, XML Tag properties to CX_Primary Organization-S_BU.Mod Id
Set External Data Type property to DTYPE_NUMBER
Set External Length property to 30
Set Type property to System
Integration Component Account_Organization Example
Consider the integration component Account_Organization of the Sample Account integration object. Account_Organization is an MVG Association as denoted by the presence of the user property MVGAssociation. Assume two Modification IDs, Mod Id and S_ORG_EXT.Mod Id, were exposed on this integration component:
For field Mod Id create a new user property with the name of AssocFieldName with a value of Mod Id.
For field S_ORG_EXT.Mod Id create a new user property with the name of AssocFieldName with a value of S_ORG_EXT.Mod Id.
In this integration component example, Account of the Sample Account integration object, takes the following action:
Create a new Integration Component key called Modification Key.
Set the type of the key as Modification Key.
Add integration component fields Mod Id, S_ORG_EXT.Mod Id, and S_BU.Mod Id to the Modification Key.
Status IDs
When using Status IDs with Modification IDs, the following behavior can be present:
All fields must be present in the integration object instance for the Modification Key to be used.
Only one defined Modification Key is present for each integration component. Unlike User Keys, multiple Modification Keys are not used with Status IDs.