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.
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.
The connector uses application-specific information for simple attributes and container attributes. The application-specific property field must be empty for the ObjectEventId attribute.
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.
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
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:
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. |
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.
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
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
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:
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.
To keep existing relationships, edit the application-specific information to contain the string keep=1;. This directs the connector to ignore Delete verbs on child objects. For example, suppose that an existing contact is associated with one address, and the connector receives a Update business object with child business objects representing two new addresses but no child business object for the existing address. If the container attribute application-specific information has the value keep=1;, the contact is updated to have both the existing and the new addresses. If the application-specific information is empty, the row containing the existing address is deleted, and the new addresses are added.
Attribute application-specific information can specify that the connector perform only Delete operations. This option is used in the case of wrapper collaborations. To delete existing relationships, edit the application-specific information to contain the string delOnly=1;.
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.
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.