Business object application-specific information

Application-specific information in business object definitions provides the connector with application-dependent instructions on how to process business objects. Because a meta-data-driven connector makes assumptions about how its supported business objects are designed, modifications to business objects must match the connector's rules for the connector to process modified business objects correctly. Therefore, if you modify or create Siebel application-specific business objects, you must be sure that the application-specific information in the business object definition matches the syntax that the connector expects.

This section describes the application-specific information for the Siebel business object, attributes, and verbs.

Business object application-specific information

The application-specific information at the top level of a business object specifies the name of the Siebel business object. For example, the object application-specific information for the parent business object Siebel_BCAccount specifies the Siebel Account object, as shown below.

[BusinessObjectDefinition] 
Name = Siebel_BCAccount 
Version = 1.0.0 
AppSpecificInfo = ON=Account;CN=Account 

Example of multiple unrelated business components:

[BusinessObjectDefinition]
Name = Siebel_BCInternalProduct
Version = 1.0.0
AppSpecificInfo = CN=InternalProduct
 
[BusinessObjectDefinition]
Name = Siebel_BCProductDefect
Version = 1.0.0
AppSpecificInfo = CN=ProductDefect
 
[BusinessObjectDefinition]
Name = Siebel_BOInternalProduct
Version = 1.0.0
AppSpecificInfo = ON=InternalProduct
 
[Attribute]
Name = Siebel_BCInternalProduct
Type = Siebel_BCInternalProduct
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = 1
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =
 
[Attribute]
Name = Siebel_BCProductDefect
Type = Siebel_BCProductDefect
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = 1
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =

Attribute application-specific information format

The connector uses application-specific information for simple attributes and container attributes. The application-specific property field must be empty for the ObjectEventId attribute.

Application-specific information for simple attributes

For simple attributes, the application-specific information consists of the name-value pairs listed in the following table. The name-value pairs are order-independent and are delimited by semicolons.

Parameter Description
FN = The name of the corresponding field in the Siebel business component.
PLK = ...;Restrict=<field name>:Siebel GUI Name>,<field name>:Siebel GUI Name Business components in Siebel can be associated with a many-to-one relationship using PickLists. The PickList can be searched, and a specific value can be chosen to be placed in a field. The PickListKey is set in case there is a PickList associated with the field in Siebel. The PickListKey identifies the field in the PickList that is used in the search specification to obtain the PickList record. In some cases, PickList values are chosen based on more than one attribute. In such cases, the PickList can be restricted by more than one field.

Example of the use of these parameters are provided in the sections that follow.

Field names for a simple attributes

application-specific information for simple business objects attributes must specify the name of the corresponding field in the Siebel business component. The application-specific information for this is:

FN=fieldname 

For example, in the Siebel_BCAccount business object the application-specific information for the Main Phone attribute specifies that Main Phone Number is the corresponding field in the Siebel Account business component. The application-specific information in the business object attribute is shown below.

Name = Main Phone
Type = String
IsKey = false
AppSpecificInfo = FN=Main Phone Number 

Foreign key relationship using a pickList

In Siebel, a foreign key relationship between two business components is defined by a PickList. If a field has an associated PickList, the field's PickList property and PickList correspondence define the relationship between the two business components. One of the attributes in the PickList correspondence is usually an Id, such as Account Id or Product Id.

On a simple attribute in a business object, if a Siebel business component field has an associated PickList, the attribute application-specific information in the business object should be coded to provide the connector with this information so that the connector can use the attribute as a foreign key.

To specify a PickList for an attribute, you need to include two attributes in the business object. The first attribute identifies the foreign key field of the related business component, and the second attribute corresponds to the field in the business component that has the PickList as a field property. Two attributes are required because the PickList relationship is based on the object name rather than the object Id.

In the application-specific information for the PickList attribute, specify that this attribute is a PickList using the text PLK. Then, to identify which record in the PickList should be selected, use the text PLK=...;Restrict=<field name>:<Siebel GUI Name>,<field name>:Siebel GUI Name>.

For example, suppose that you are creating a Siebel_BCAsset business object, and you want to add an attribute in the business object as a foreign key to the Siebel_BCInternalProduct business object. The Product Name field in the Siebel Asset Mgmt business component is a PickList to the Internal Product business component, so you add an attribute for the key and another attribute for the PickList. The attributes might be defined in the business object as shown below.

[Key Attribute]
Name = Id
Type = String
Cardinality = 1
IsForeignKey = true
AppSpecificInfo = Product Id
 
[PickList Attribute]
Name = ProductName
Type = string
Cardinality = n
AppSpecificInfo = FN=ProductName;PLK=Id

In some cases, PickList values are chosen based on more than one attribute. For example, where there is more than one Account with the same name, a Contact retrieve will get the first Account with that name if Account name is set as the only PickList value. To ensure that the correct data is retrieved, you can restrict the PickList by more than one field. In the following example, the Contact business object is restricted by Account, Site and City:

[Key Attribute]
Name = ContactId
Type = String
Cardinality = 1
AppSpecificInfo = FN=Id
 
Name = Last_Name
Type = String
Cardinality = 1
AppSpecificInfo = FN=Last Name
 
Name = First_Name
Type = String
Cardinality = 1
AppSpecificInfo = FN=First Name
 
Name = Site
Type = String
Cardinality = 1
AppSpecificInfo = N/A
 
Name = City
Type = String
Cardinality = 1
AppSpecificInfo = N/A
 
Name = Account
Type = String
Cardinality = 1
AppSpecificInfo = FN=Account;PLK=Name;Restrict=Location:Site,City:City

The AppSpecificInfo for restricting PickList fields follows this syntax:

Restrict=<field name>:<Siebel GUI name>,<field name>:<Siebel GUI name>

There is no limit to the number of restricting fields. Do not use spaces between the attributes after the Restrict parameter. All restricting fields must be added as attributes to the business object, and should have no AppSpecificInfo. These attributes serve as place holders for the restricting fields.

On a Retrieve, the application-specific information PLK=Id specifies that the ProductName attribute corresponds to a PickList business component, and the set parameter specifies that the value of the Id identifies which record the connector should pick.

Some PickList relationships require the creation of a picked child, for example, the PickList relationship between Account and Quote in Siebel_BCQuote. On a Create, you must create a new Account business component for the PickList with a containment relationship to the Quote business component as follows:

[Business Object Definition]
Name = Siebel_BCQuote
Version = 7.0.0
Relationship = Containment
AppSpecificInfo = ON=Quote;CN=Quote
 
Name = Account
Type = String
AppSpecificInfo = FN=AccountId
 
Name = Account
Type = Siebel_BCAccount
Relationship = Containment
Cardinality = 1
IsForeignKey = false
AppSpecificInfo = LFN=Account;PL=true;From=AccountId;To=AccountId
 
[Siebel_BCAccount]
Name = AccountId
IsKey = true
AppSpecificInfo = ...

Note the following business processing tips for PickList attributes:

Application-specific information for container attributes

For container attributes, the application-specific information contains the name-value pairs listed in the following table. The name-value pairs are order independent and are separated by semicolons.

Parameter Description
LFN = ...; Multi Value Field Name related to the Siebel business component.
MVL = ...; When MVL is set to Active, it specifies a one-to-many relationship. Setting MVL to Inactive indicates that there is an inactive multi-value link relationship between the parent and child objects, which means that the parent object does not have a multi-value field.
PL = ... When PL is set to True, it indicates that there is a many-to-one relationship.
Assoc = ... When Assoc is set to True, it indicates that a relationship is many-to-many through an intersection table. When the relationship is an association between the two business components, an active multi-value link may or may not exist. Based on whether or not the multi-value link exists, the application specific information can contain: MVL=Active;Assoc=true; If the application specific information contains only Assoc=true, the default is that there is an active multi-value link. If you explicitly specify, the application-specific information will contain: MVL=Active;Assoc=true. If a multi value link does not exist, the application specific information will contain: MVL=Inactive;Assoc=true.
From = ...; To = ... These are preprocessing instructions to the connector to set the To attribute to the value of the From attribute. The From attribute must be populated, while the True attribute is set only if it is null. The objects containing the attributes must have a one-to-one relationship. This is used in a Retrieve operation and to specify which child record needs to be fetched.
SF Simple link which provides the master detail view of the business component structure under a business object. SF represents the source field.
DF Simple link which provides the master detail view of the business component structure under a business object. DF represents the destination field (foreign key).

Field names for container attributes

If the relationship between the parent and child objects is one-to-many, application-specific information for a container attribute referencing a child business object must specify the name of the Multi-Value Field related to the parent business component. A Multi-Value Field represents the Multi-Value Link that defines the relationship between the parent and child business components in Siebel. The application-specific information for this is:

LFN=multiValueFieldName

For example, if the Siebel business component Account has a mulit-value field Street Address in the Siebel application, the corresponding WebSphere business integration system business object Siebel_BCAccount has a container attribute for the child business object Siebel_BCBusinessAddress. The application-specific information for this container attribute specifies Street Address as the Multi-Value Field that contains the link to the Siebel Business Address business component.

[Example of Container Attribute] 
Name = PrimaryAddress 
Type = Siebel_BCBusinessAddress 
ContainedObjectVersion = 1.0.0 
Relationship = Containment 
Cardinality = n
IsKey = false
IsForeignKey = false
AppSpecificInfo = MVL=Active;LFN=Street Address

Relationships between parent and child business objects

In addition to the field name, the application-specific information for a container attribute can include a parameter that defines the type of relationship between the parent and child business components in Siebel.

Setting a relationship type parameter to 0 is not valid. To set a relationship type to false, do not include the parameter.

As an example, the container attribute for the child business object Siebel_BCBusinessAddress, shown in the previous section, might include the parameter to indicate that Street Address is a Multi Value Field that links the Siebel Account business component to the Siebel Business Address business component.

[Example of Container Attribute] 
Name = PrimaryAddress 
Type = Siebel_BCBusinessAddress 
ContainedObjectVersion = 1.0.0 
Relationship = Containment 
Cardinality = n
IsKey = false
IsForeignKey = false
AppSpecificInfo = MVL=Active;LFN=Street Address

Another example for the child business object Siebel_BCOpportunity is shown here which has a many-to-many relationship to Siebel_BCContact or Association. In this case, on a Create operation, the connector searches for the business component using the populated fields of the business object in the container. If the connector finds a matching object, it associates it with the parent business component. If the object is not found, an error is logged, and the business object request fails.

Name = Siebel_BCContact
Version = 1.0.0
AppSpecificInfo = ON=Contact;CN=Contact
 
Name = ContactId
Type = String
Cardinality = 1
MaxLength = 10
IsKey = true
IsForeignKey = false
IsRequired = false
AppSpecificInfo = FN=Id
 
Name = ...
 
Name = ...
 
Name = Siebel_BCOpportunity
Type = Siebel_BCOpportunity
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = N
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo =LFN=Opportunity;Assoc=true

This example is for a simple link relationship. In this case, there is a simple link between Quote and Order Entry:

Name = Siebel_BCQuote
Version = 1.0.0
AppSpecificInfo = ON=Quote;CN=Quote
Name = QuoteId
Type = String
Cardinality = 1
MaxLength = 10
IsKey = true
IsFireignKey = false
IsRequired - false
AppspecificInfo = FN=Id
 
Name = ...
 
Name = ...
 
Name = Siebel_BCOrderEntry
Type = Siebel_BCOrderEntry
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = N
MaxLength = 0
IsKey = true
IsFireignKey = false
IsRequired - false
AppspecificInfo = SF=QuoteId;DF=QuoteId

Assigning the value of an attribute to another attribute

Attribute application-specific information can be coded so that the connector obtains a value for an attribute and assigns it to another attribute before the second attribute is processed. This functionality is used in a Retrieve operation and is primarily used on container attributes to specify which record for the child should be retrieved.

To use this functionality, edit the attribute application-specific information in the business object definition to include the following text:

From=attribute;To=attribute;

The attribute path value can be an attribute name in the current business object. Note the following rules:

For example, if a Siebel_BCQuote business object includes a child business object Siebel_BCAccount, attributes in the Siebel_BCQuote object can specify which address from the PickList is retrieved. In this example, AccountId is the key attribute, and Siebel_BCAccount is the picked object. The connector gets the value of the AccountId attribute, and uses that value to retrieve the specific account. The child attributes are processed after the attributes in the parent business object. The following example shows the processing flow of attributes from parent to child business objects.

[Siebel_BCQuote]
Name = Account
Type = String
AppSpecificInfo = FN=Id
 
Name = Account
Type = Siebel_BCAccount
Relationship = Containment
Cardinality = 1
IsForeignKey = false
AppSpecificInfo = LFN=Address;PL=true;From=AccountId;To=AccountId
 
[Siebel_BCAccount]
Name = AccountId
IsKey = true
AppSpecificInfo = ...

Specifying pickList relationships

Some PickList relationships require the creation of the picked child object in the same transaction. In WebSphere business integration system business objects, a PickList relationship between parent and child business objects is represented by two attributes: a key attribute and a single cardinality container attribute for the picked object. This set of attributes can be used to retrieve some or all of the attributes of the PickList business component that are not included in the PickList map.

For example, the Siebel_BCQuote business object might be designed to include two attributes to specify a PickList relationship between Quote and Opportunity. As shown below, OpportunityId is the key attribute, and Opportunity is the PickList object.

Name = Siebel_BCQuote
Version = 1.0.0
AppSpecificInfo = ON=Quote;CN=Quote
 
Name = ...
 
Name = ...
 
Name = OpportunityId
Type = String
Cardinality = 1
MaxLength = 10
IsKey = false
IsForeignKEy = true
IsRequired = false
AppSpecificInfo = FN= OpportunityId
 
Name = Siebel_BCOpportunity
Type = Siebel_BCOpportunity
ContainedObjectVersion = 1.0.0
Relationship = Containment
Cardinality = 1
MaxLength = 0
IsKey = false
IsForeignKey = false
IsRequired = false
AppSpecificInfo = LFN=Opportunity;PL=true;From=OpportunityId;To=OpportunityId

In the application-specific information, PL=true indicates that the container attribute represents a PickList, the From= parameter is the pointer to the key attribute, and the To= parameter points to the key attribute of the Siebel_BCOpprotunity business object.

The order of the attributes is significant in a Retrieve operation, because the value of OpportunityId must be retrieved before it can be defined as the foreign key in the child object. On a Create or Update operation, the value of OpprotunityId is a foreign key and is retrieved after the object is created.

It is not necessary to use a complete business object as a PickList container. An object with only the required keys set is sufficient. The connector uses the following rules for processing a PickList container:

The following are guidelines for maps for PickList attributes on container business objects:

Verb application specific information format

Application-specific information for a business object Retrieve verb can specify that the connector retrieve a limited number of objects on each retrieve. The application-specific information to retrieve a subset of objects is max=n. An example of a Retrieve verb that specifies that only five objects are retrieved is: [Verb] Name = Retrieve AppSpecificInfo = max=5

For other verbs, the application-specific property is not used and should be left blank or omitted when creating business object definitions.

Multiple record retrieval

The adapter processes the RetrievebyContent verb similarly to the way it processes the Retrieve verb, except that it does not check to see that all keys are set on the inbound IBM business object.

The adapter for Siebel supports wrapper business objects. See Business object structure and relationships. The adapter can retirieve multiple records during request processing using the RetrievebyContent verb and a wrapper business object. For a wrapper business object with a multiple cardinality container, all matching records are returned. For a single cradinality child, only one record is processed and MULTIPLE_HITS is returned.

Key attribute for create and update verbs

On a Create or Update request, if the Object Key value is different from RowId, the Siebel application blanks out the Object Key attribute and creates its own RowId for that record.

Important:
You must use RowId as the key attribute in Create and Update requests.

Copyright IBM Corp. 1997, 2004