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_BO_Account specifies the Siebel Account object, as shown below.

[BusinessObjectDefinition] 
Name = Siebel_BO_Account 
Version = 1.0.0 
AppSpecificInfo = Account 

On a container attribute, the application-specific information at the object level is not used.

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
nm= The name of the corresponding field in the Siebel business component.
pick= Specifies a many-to-one relationship (Pick List). The default value is false.
set= Used only with a Pick List. Specifies the attribute name of a key in the Siebel business component referenced by the Pick List.

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:

nm=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 = nm=Main Phone Number 

For backward compatibility, when attribute application-specific information for the Siebel field name does not include the constant nm and there are no other parameters in the application-specific information, the constant nm is the default. If there are additional parameters in the application-specific information, the complete name-value pair is required. In other words, the two application-specific information formats below are the same if the nm=parameter is the only parameter for this attribute:

AppSpecificInfo =Main Phone Number
AppSpecificInfo= nm=Main Phone Number

Foreign key relationship using a pick list

In Siebel, a foreign key relationship between two business components is defined by a Pick List. If a field has an associated Pick List, the field's PickList property and PickList map define the relationship between the two business components. One of the attributes in the PickList map 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 Pick List, 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 Pick List 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 Pick List as a field property. Two attributes are required because the Pick List relationship is based on the object name rather than the object Id.

In the application-specific information for the Pick List attribute, specify that this attribute is a Pick List using the text pick=1. Then, to identify which record in the Pick List should be selected, use the text set=fieldname. The set parameter specifies which attribute of the linked object is used in the search specification to identify the record you want to pick.

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 Pick List to the Internal Product business component, so you add an attribute for the key and another attribute for the Pick List. The attributes might be defined in the business object as shown below.

[Key Attribute]
Name = ProductId
Type = String
Cardinality = 1
IsForeignKey = true
AppSpecificInfo = Product Id
 
[Pick List Attribute]
Name = ProductName
Type = string
Cardinality = n
AppSpecificInfo = nm=ProductName;pick=1;set=Id

In some cases, Pick List 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 Pick List value. To ensure that the correct data is retrieved, you can restrict the Pick List 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=Id
 
Name=Last_Name
Type=String
Cardinality=1
AppSpecificInfo=Last Name
 
Name=First_Name
Type=String
Cardinality=1
AppSpecificInfo=First Name
 
Name=Site
Type=String
Cardinaity=1
AppSpecificInfo=N/A
 
Name=City
Type=String
Cardinaity=1
AppSpecificInfo=N/A
 
Name=Account
Type=String
Cardinality=1
AppSpecificInfo=nm=Account;pick=1;set=Name;restrict=Location:Site,City:City

The AppSpecificInfo for restricting Pick List fields follows this syntax:

restrict=<column name>:<Siebel GUI name>,<column name>:<Siebel GUI name>

There is no limit to the number of restricting fields. Do not use spaces between the attributes after the set 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 pick=1 specifies that the ProductName attribute corresponds to a Pick List business component, and the set parameter specifies that the value of the Id identifies which record the connector should pick.

On a Create, you must create a new Product business component for the picklist with a containment relationship to the Asset business component as follows:

[Key Attribute]
Name = ProductId
Type = String
Cardinality = 1
IsForeignKey = true
AppSpecificInfo = Product Id
 
[Pick List Attribute]
Name = Siebel_BCInternalProduct
Type = Siebel_BCInternalProduct
Relationship = containment
AppSpecificInfo = nm=Siebel_BCInternalProduct;pick=1;set=Id

Note the following mapping tips for Pick List attributes:

Application specific text 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
nm= The name of the Multi Value Field in the Siebel business component.
mvg=1 pick=1 assc=1 Specifies the relationship type between Siebel business components. mvg=1 specifies a one-to-many relationship. pick=1 specifies a many-to-one relationship, and assc=1 specifies a many-to-many relationship. The default value if no relationship type is specified is mvg=1.
to=;from= Preprocessing instructions for the connector to set the to attribute to the value of the from attribute. The from attribute must be populated before the attribute containing this text parameter is processed. The to attribute is set only if it is null. This text can only be used if the objects containing the attributes have a 1-to-1 relationship.
keep=1 delOnly=1 Specifies constraints on Update operations.

Field names for container attributes

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:

nm=multiValueFieldName

For example, the business object Siebel_BCContact 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_BC_BusinessAddress 
ContainedObjectVersion = 1.0.0 
Relationship = Containment 
Cardinality = n
IsKey = false
IsForeignKey = false
AppSpecificInfo = nm=Street Address

For backward compatibility, when attribute application-specific information for the Siebel field name does not include the constant nm and there are no other parameters in the application-specific information, the constant nm is the default. If there are additional parameters in the application-specific information, the complete name-value pair is required.

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. Use the following values to specify a relationship type.


Parameter Description
mvg=1 Specifies that the relationship is a one-to-many relationship, or a Siebel Multi-Value Link
pick=1 Specifies that the relationship is a Pick List. For more information on specifying a Pick List relationship between parent and child business objects, see "Specifying pick list relationships".
assc=1 Specifies that the relationship is a many-to-many relationship through an intersection table. 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.
nomvl=1 Specifies that there is a Link or Multi Value Link relationship between the parent and child object, but there is no multi value field on the parent business object. In this case, you must set the Transactional property. See "Connector-specific properties" for more information on setting the Transactional property.

If no relationship parameter is specified, mvg=1 is used. 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 mvg=1 to indicate that Street Address is a Multi Value Field that links the Siebel Contact business component to the Siebel Business Address business component.

[Example of Container Attribute] 
Name = PrimaryAddress 
Type = Siebel_BC_BusinessAddress 
ContainedObjectVersion = 1.0.0 
Relationship = Containment 
Cardinality = n
IsKey = false
IsForeignKey = false
AppSpecificInfo = nm=Street Address;mvg=1 

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 path;to=attribute path;

The attribute path value can be any of the following:

A full path is traversed from the top-level business object down the hierarchy. The from=;to=; set of parameters can be used on any simple or container attribute, and is acted on before the attribute is processed. Note the following rules:

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

Figure 2. Using a full path to assign value of one attribute to another


Figure 3. Using a short path to assign value of one attribute to another


Specifying pick list relationships

Some Pick List relationships require the creation of the picked child object in the same transaction. In IBM WebSphere Business Integration Adapter business objects, a Pick List 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 Pick List 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 Pick List relationship between Quote and Account. As shown in the figure below, AccountId is the key attribute, and Account is the Pick List object.




In the application-specific information, pick=1 indicates that the container attribute represents a Pick List, the from= parameter is the pointer to the key attribute, and the to= parameter points to the key attribute of the Siebel_BCAccount business object.

The order of the attributes is significant in a Retrieve operation, because the value of AccountId 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 AccountId is a foreign key and is retrieved after the object is created.

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

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

Specifying constraints for update operations on multiple cardinality objects

On an Update operation for a hierarchical business object, the connector first retrieves the data from the application and creates a hierarchical business object that contains the current values for the entity. It then compares the business object in the business object request to the application business object, creating records for child business objects not present in the application, updating records that exist in the application, and deleting records that exist in the application but are not present in the collaboration business object.

In addition to this default behavior, you can configure the connector's behavior for updating child objects using the keep and delOnly parameters.

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.

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.

Note:
It is recommended that you use RowId as the key attribute in Create and Update requests.

Copyright IBM Corp. 1997, 2004