Siebel Innovation Pack 2017: Execute Method

Integration Platform Technologies: Siebel Enterprise Application Integration > EAI Siebel Adapter Business Service > EAI Siebel Adapter Business Service Methods >

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

NOTE: A none operation is equivalent to operation sync.

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 Table 16.

NOTE: The operation method names are case sensitive. If you misspell an operation method, then the EAI Siebel Adapter assumes the default operation.

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:

<Account operation="upsert">

<Name>A. K. Parker Distribution</Name>

<Location>HQ-Distribution</Location>

<Organization>North American Organization</ Organization>

<Description>This is the key account in the AK Parker Family</Description>

<HomePage>www.parker.com</HomePage>

<LineofBusiness>Manufacturing</LineofBusiness>

<Contact operation="delete">

<JobTitle>Senior Mgr of MIS</JobTitle>

<LastName>Graner</LastName>

<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.

NOTE: Specifying an operation within the ListOf tag is not supported. For information on the ListOf tag, see XML Reference: Siebel Enterprise Application Integration.

Each child node inherits the operation from the parent if another operation is not explicitly specified. If another operation is explicitly specified, then Table 16 represents the results of the operation on the current node.

Table 16. 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. Table 17 is a high level representation of a parent node using the sync operation of the Execute method.

Table 17. Representation of a Parent Node Using the Sync Operation
Record In Database	Integration Object Instance	Record After Execute Operation
Account1 Contact0 Contact1	Account1 `operation=sync` 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"?>

<AccountStatus>Active</AccountStatus>

LanguageCode>ENU</LanguageCode>

<Location>San Francisco, CA</Location>

<Name>GenComm</Name>

<FirstName>GENCOMM0</FirstName>

<LastName>GENCOMM0</LastName>

<Organization>Default Organization</Organization>

</Contact>

<FirstName>GENCOMM1</FirstName>

<LastName>GENCOMM1</LastName>

<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"?>

<Account operation="sync">

<AccountStatus>Inactive</AccountStatus>

<Location>San Francisco, CA</Location>

<Name>GenComm</Name>

<FirstName>GENCOMM1</FirstName>

<LastName>GENCOMM1</LastName>

<Organization>Default Organization</Organization>

</Contact>

<FirstName>GENCOMM2</FirstName>

<LastName>GENCOMM2</LastName>

<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"?>

<AccountStatus>Inactive</AccountStatus>

<Location>San Francisco, CA</Location>

<Name>GenComm</Name>

<FirstName>GENCOMM1</FirstName>

<LastName>GENCOMM1</LastName>

<Organization>Default Organization</Organization>

</Contact>

<FirstName>GENCOMM2</FirstName>

<LastName>GENCOMM2</LastName>

<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. Table 18 is a high level representation of a parent node using the update operation of the Execute method.

NOTE: The examples represented by Table 18, Table 19, and Table 22 basically have the same result. However, as reflected in Table 21, the children do not automatically inherit Update if it is only set for the root.

Table 18. Representation of a Parent Node Using the Update Method
Record In Database	Integration Object Instance	Record After Execute Operation
Account1 Contact0 Contact1	Account1 `operation=update` 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. Table 19 is a high level representation of this example.

Table 19. Representation of Two Operations
Record In Database	Integration Object Instance	Record After Execute Operation
Account1 Contact0 Contact1	Account1 `operation=update` Contact1 Contact2 `operation=insert`	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 Table 20 and Table 21 will fail. In Table 20, it fails because an insert is attempted when Contact1 already exists in the database.

Table 20. Representation of Overriding a Parent Operation Using Insert
Record In Database	Integration Object Instance	Record After Execute Operation
Account1 Contact0 Contact1	Account1 `operation=update` Contact1 `operation=insert` Contact2 `operation=insert`	None

In Table 21, the update fails because SubContact3 inherits from Contact2's operation, and Subcontact3 does not exist in the database.

Table 21. 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 `operation=update` 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. Table 22 is a high level representation of this example.

Table 22. Representation of Overriding a Parent Operation Using Upsert
Record In Database	Integration Object Instance	Record After Execute Operation
Account1 Contact0 Contact1	Account1 `operation=update` Contact1 Contact2 `operation=upsert`	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. Table 23 is a high level representation of this example.

Table 23. 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 `operation=upsert` Contact1 Organization1 Contact2 `operation=sync` 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"?>

<Account operation="upsert">

<Location>cold storage</Location>

<Contact operation="skiptree">

<FirstName>firstname</FirstName>

<LastName>contact1</LastName>

<Organization>Default Organization</Organization>

<BusinessAddress operation="insert">

<City>San Mateo</City>

<AddressName>primary address</AddressName>

</BusinessAddress>

</ListOfBusinessAddress>

</Contact>

<FirstName>firstname</FirstName>

<LastName>contact2</LastName>

<Organization>Default Organization</Organization>

</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"?>

<Account operation="skiptree">

<Location>cold storage<Location/>

</Account>

<Account operation="upsert">

<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"?>

<Account operation="skipnode">

<Location>cold storage</Location>

<FirstName>firstname</FirstName>

<LastName>contact1</LastName>

<ListOfContact_Organization>

<Contact_Organization>

<Organization operation="insert">MyOrganization</Organization>

</Contact_Organization>

</ListOfContact_Organization>

</Contact>

<Contact operation="upsert">

<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 Table 24.

Table 24. 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

Table 25 presents each argument of the EAI Siebel Adapter business service methods.

Table 25. 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 SearchSpec 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.

NOTE: The operator between fields for a particular integration component instance can be AND unless between the same field. You use the DOT notation to refer to integration components and their fields.

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.

NOTE: Setting a primary record in an MVG is supported when the Auto Primary property of the underlying multivalue link is specified as Selected, None, or Default.

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.

Integration Platform Technologies: Siebel Enterprise Application Integration		Copyright © 2017, Oracle and/or its affiliates. All rights reserved. Legal Notices.