Business object application-specific text

Application-specific text in business object definitions provides the connector with application-dependent instructions on how to process business objects. This meta-data is used in conjunction with a business object's attribute properties and structure. If you extend or modify Clarify CRM application-specific business objects, you must make sure that the application-specific information in the business object definition matches the syntax that the connector expects.

This section provides information on the object, attribute, and verb application-specific text format for business objects for Clarify CRM. Table 8 provides an overview of the functionality available in business object application-specific text for Clarify CRM.

Table 8. Overview of application-specific text in business objects for Clarify CRM

Scope of application-specific text Types of functionality
Entire business object Define the scope of transactions in the connector Specify that the connector perform retrieves using multiple keys
Simple attributes [Required] Specify table name, field name, and data type for an attribute Specify one or more relations between attributes in the primary table and one or more foreign tables Specify how retrieve queries are constructed Specify automatic generation of attribute values Specify preprocessing for attributes Specify that Retrieve operations use non-key values
Container attributes Specify whether existing relations are kept for child business objects on Update operations
Business object verb Specify that the connector retrieve only the parent business object in a hierarchical object. Specify that the connector follow a retrieve by non-key values with a regular retrieve operation.

Using business object application-specific text

The business object for Clarify CRM includes application-specific text at the business object level that:

The sections that follow provide information on these types of application-specific text.

Defining the scope of business object transactions

When the connector is processing a request to change data in the Clarify CRM database, it can process business object transactions in two ways:

By default, the connector commits an entire business object at once. You can use the object application-specific text to specify that the connector execute a commit after each business object.

Transactionality is set by specifying Transactionality=Partial or Transactionality=Full in the application-specific text. If Transactionality is set to Partial, the connector executes a commit after processing each business object. This means that if there is a parent object and several contained child objects, the connector will execute a commit after updating the parent object, a commit after updating the first child object, and so on. If Transactionality is set to Full or not set, the connector will wrap the whole transaction in one commit.

For example, to specify that the connector execute a commit after each business object, use the following text:

AppSpecificInfo = Transactionality=Partial 

For every business object, it is recommended that transactionality initially be set to Full. However, due to a known problem in the Clarify API, the connector cannot rely on the sequence of the SQL statements that the API generates. In certain cases, the API may perform an action in a different order than the connector requested.

To force the Clarify API to execute the statements in the order specified, set Transactionality to Partial. Note, however, that if transactional support is set to Partial, a hierarchical business object is not committed in one transaction, and a failure only partially rolls back transactions for a hierarchical business object.

To view the set of actions that the API has performed, examine the SQL log that the connector has generated. This file contains the actual SQL scripts executed by the connector. The name of this log is set by the connector configuration property SQLDumpFileName; the default file is C:\\temp\XrclarifySQL.log.

Note:
If the entire WebSphere Business Integration Adapter business object is committed in one transaction, the transaction log of the Clarify CRM database may need to be significantly increased. For example, if a Clarify_Contract business object includes 900 line items, the log must be large enough to handle this object in one transaction. Consult your database administrator for information.

Specifying multiple key attributes for retrieve operations

By default, when the connector performs a Retrieve operation, it uses the value of the first key attribute, which must be the first attribute, as the key to the record in Clarify CRM. You can also use the business object application-specific text to specify that the connector retrieve a business object using the value of several attributes designated as keys.

The use of more than one key attribute creates a compound key for the purpose of querying Clarify CRM. Because multikey retrieve is set at the parent business object level, this application-specific text enables multikey retrieve for all business objects of a particular type.

To allow multikey retrieve, edit the business object application-specific information to specify MultiKeyRetrieve=True. The format is:

AppSpecificInfo = MultiKeyRetrieve=True 

The default is false; that is, only the first key attribute value is used. Note the following restrictions:

Attribute application-specific text

The application-specific text for attributes differs depending on whether the attribute is a simple attribute or a container attribute. For information on application-specific text for container attributes, see "Application-specific text for container attributes".

Format of application-specific text for simple attributes

For simple attributes, application-specific text format consists of eight positional parameters separated by colon (:) delimiters. The positional parameters can be preceded by one or more name-value pairs. The name-value pairs are optional and can be specified in any order. Semi-colons are used as field delimiters between name-value pairs. If any name-value pairs are present, they are separated from the positional parameters by a vertical bar (|). Therefore, reserve the colon, semi-colon, and vertical bar characters as delimiters.

The format of attribute application-specific text is shown below. Note that only the table name, field name, and data type parameters are required; bracketed fields in the syntax example are optional.

[SchemeName = Value;PP=Value;RBC=Value| ]
tablename:fieldname:[relation[,...]]:datatype:[ParentIndex]:
[RelateToAttribute[,...]]:[AttrNameToLookFor:FieldNameToRetrieve

Table 9 describes the meaning of each positional parameter. Table 10 briefly describes the name-value pairs. Examples of the use of these parameters are provided in the sections that follow.

Table 9. Positional parameters in attribute application-specific text

Field Description
tablename
The name of the Clarify CRM database table for this attribute.
fieldname
The name of the column in the Clarify CRM database table.
relation[, ...]
A list of Clarify CRM relations used to relate this attribute to the attributes in the RelateToAttribute list described below.
datatype 
An integer value indicating the type of data. Supported types are: 1 = integer data (int, tinyint), 2 = floating point data (real), 3 = string data (varchar, text, datetime), 4 = decimal data (corresponding to the Clarify CRM decimal type introduced in Clarify 5.0)
ParentIndex 
The index of the parent object in a query.
RelateToAttribute[, ...] 
A list of attributes to be related to this attribute using the relations specified in the relation list described above. A leading .. (two dots) points to an attribute in this object's parent object, and a leading ... (three dots) points to an attribute in this object's grandparent object.
AttrNameToLookFor
The name of an attribute in this business object whose table name should be used, along with the field name specified in Field Name To Retrieve parameter, to assign to the tablename and fieldname parameters for this attribute.
Field Name To Retrieve
Field name to use to assign to the tablename/fieldname parameters for this attribute. Used with the AttrNameToLookFor parameter.


Table 10. Name-value pairs in attribute application-specific text

Name-value pair Description
SchemeName=Value
The constant SchemeName and its value as defined by the value in the name column of the Clarify CRM table_num_scheme table. This name-value pair is used to specify the automatic generation of one or more attribute values.
PP=viewOrTable:column:
condition:location[...]
Specifies preprocessing of an attribute
RBC=tablename:fieldname
Specifies each attribute that is to be used in a RetrieveByContent operation.

Specifying the clarify table name and field name for an attribute

Attribute application-specific text must specify the tablename, fieldname, and datatype parameters for all attributes. These parameters enable the connector to create a new record in a table for a Create operation or locate a record in a table for a Retrieve operation or an Update operation. All other application-specific text fields are optional.

When you modify or add business object attributes, be sure to specify the name of the table, name of the field, and the data type for the attribute in the Clarify CRM database.

Example: Simple create operations

The following example shows a business object named Clarify_PartnerSite and its key attribute SiteObjid. In the application-specific text for the SiteObjid attribute, the business object designer coded the location for the attribute value as the objid field in the Clarify CRM site table. The data type of the field is integer.

Name = SiteObjid
IsKey = true
AppSpecificInfo = site:objid::1:

The connector can use the application-specific text to create a new record in the site table. Figure 7 shows an example Clarify CRM site table and an example business object definition for a Clarify_PartnerSite business object.

Note:
Do not name a Clarify CRM application-specific business object Clarify_Site. The business object Clarify_Site is obsolete, and the use of this name will trigger obsolete processing in the connector that may result in a user code exception.

Figure 7. Attribute application-specific text specifying table name, field name, and data type


Specifying relations between objects

If an attribute references a Clarify CRM table other than the primary table, the attribute application-specific text must specify the relation and RelateToAttribute parameters. These parameters enable the connector to create a new record in the associated table for a Create operation or find a record in an associated table for a Retrieve operation.

The relation parameter must be included in the application-specific text of the first attribute that references the table. Subsequent attributes that reference the table cannot include a relation.

The RelateToAttribute parameter specifies the attribute that is to be related to this attribute by the relation. This parameter can point to an attribute in the current business object, the parent business object, or the grandparent business object using the following syntax:

When you modify or add business object attributes that refer to associated tables, be sure to specify the name of the associated table, the name of the field, the data type for the attribute, the relation name, and the RelateToAttribute name.

The next sections provide examples of using several attribute application-specific text parameters.

Example: Creating an individual business object with relations to a single associated table

To define attributes that reference a table related to the primary table, define an attribute whose application-specific text contains the relation between the tables, and then include other attributes that reference the foreign table.

For example, a business object definition named Clarify_PartMaster, representing the Clarify part_num table, includes several attributes that reference the mod_level table. In the business object definition shown in Figure 8, the part_num table is specified as the primary table in the application-specific text of the business object's primary key, PartId. The relation between the part_num table and mod_level table is specified in the application-specific text of the ModLevelObjId attribute. The application-specific text of the following attribute, ModLevel, simply references the mod_level table.

The application-specific text in the ModLevelObjId attribute shows the use of the tablename, fieldname, relation, datatype, and RelateToAttribute parameters.

Figure 8. Business object with relation to a foreign table


Example: Creating a hierarchical business object with relations between parent and child business objects

In this example, assume that the business object Clarify_PartnerSite is a hierarchical business object containing a child business object named Clarify_SiteAddress. When the connector receives a Create request for Clarify_PartnerSite, it does the following:

The Clarify_PartnerSite and Clarify_SiteAddress business object definitions are illustrated in Figure 9. The application-specific text in the primary key attribute of the child business object shows the use of the tablename, fieldname, relation, datatype, and RelateToAttribute parameters. The RelateToAttribute parameter specifies the SiteObjid attribute in the parent business object.

Figure 9. Creating relations within a hierarchical business object


The connector uses the application-specific text shown in the business objects above to process the business objects. The connector follows these general steps:

  1. The connector creates a new site record in the site table. The value in the objid key becomes the value for the SiteObjid attribute in the parent Clarify_PartnerSite business object. The data type of the field is string.
  2. The connector creates a new record in the address table. The value of the objid key becomes the value for the AddressObjId attribute in the child Clarify_SiteAddress business object. The data type of the field is integer.
  3. From the child Clarify_SiteAddress object, the connector locates the site table using the ..SiteObjid parameter in the application-specific text. This parameter points to the SiteObjid attribute in the parent business object. The SiteObjid attribute in the parent business object provides the reference to the business object's primary table and primary key.
  4. The connector relates the address record to the site table by populating the cust_primaddr2address relation field of the site table with the value of address.objid of the address record. The connector uses the inverse relation cust_primaddr2address.

Figure 10 shows the Clarify CRM site table and address table and the corresponding WebSphere Business Integration Adapter business object definitions.

Figure 10. Creating a hierarchical business object


Example: Creating a hierarchical business object with multiple relations to the same field

In the next example, the child business object has multiple relations to the parent business object. The application-specific text instructs the connector to create a new site record, create a new address record, and link the address record to the site record as primary address, billing address, and shipping address. The three relations between the address table and the site table are created using each inverse relation in the list of relations: cust_primaddr2address, cust_billadd2address, and cust_shipaddr2address. The format is:

Name = AddressObjId 
AppSpecificInfo = address:objid:cust_primaddr2address,
   cust_billaddr2address,cust_shipaddr2address:1:0:..SiteObjid,
   ..SiteObjid,..SiteObjid 

The site table relation columns are populated with the address.objid of the related address record. Because all three customer types use the same address, the relation columns contain the same ID. Figure 11 shows these relations.

Figure 11. Multiple relations referring to the same field


Example: Using the relateToAttribute to point to parent and grandparent business objects

The business object Clarify_Contract_Schedule_Subline provides an example of application-specific text that points to both parent and grandparent business objects. The application-specific text is:

Name = ContractLineObjId 
AppSpecificInfo =contr_itm:objid:schedule2contr_itm,parent2contr_itm:
1:0:...ContrSchedObjid,..ContractLineObjId 

Using this text, the connector creates relations as follows:

The second relation represents a line item hierarchy, where the current line item is a subordinate line item, and the parent line item is specified in the ContractLineOjbId key attribute of the parent business object. This line item hierarchy is represented by a WebSphere Business Integration Adapter business object hierarchy, where the parent line item is a Clarify_Contract_Schedule_Line business object, and the child line item is a Clarify_Contract_Schedule_Subline child business object.

Specifying the parentIndex parameter for retrieve operations

To retrieve data from the Clarify CRM database, the connector defines a query or a set of queries that selects the specified data. The connector determines the type of query based on whether the business object uses relations to join tables.

The connector builds queries as follows:

To enable the connector to build an array of queries, the application-specific text must contain two index numbers: an index number in the ParentIndex parameter and the query index, which is generated by the connector. The connector uses these index numbers to define the query.

For an individual business object that uses relations to join tables, the connector generates the query index by indexing the first business object attribute as 0 and incrementing the index for each subsequent attribute that refers to a relation. For an attribute that refers to a relation, the application-specific information ParentIndex parameter specifies the query index number for the attribute that contains the other key for the join.

Figure 12 illustrates a sample business object and shows how the business object designer would index the attributes in the business object for a Retrieve operation. The illustration also shows the application-specific information for each attribute.

Figure 12. Query index and parentIndex parameters for a business object


When you create a business object, count the attributes that refer to new relations to determine what the query index will be. Then set the ParentIndex parameter to point to the correct query index.

Note:
When modifying a business object, it is recommended that you add new attributes at the end of a business object. If you add an attribute in the middle of an existing business object or delete an attribute from a business object, and the business object will be used for Retrieve operations, you will have to re-index the Parent Indexes.

Retrieving hierarchical business objects

In a Retrieve operation on a hierarchical business object, the connector typically gets the key from the top-level business object and then recursively works through the entire business object retrieving all the child business objects. To do this, the connector builds a query for the parent object, and builds a new query for each child business object.

The query index for the parent business object is generated as described above. The query index for each child business object implicitly includes the parent key as index 0, and then increments the index for each new relation. Each child query index is generated in the same way as top-level objects except that it begins at 1.

Figure 13 shows how the connector indexes attributes for a parent business object and a child business object. The figure also shows the application-specific information.

Figure 13. Query index and parent index for a hierarchical business object


A business object can have any number of attributes that refer to relations. Figure 14 shows another example of query indexes and parent indexes in hierarchical business objects.

Figure 14. Another example of query indexes and parent indexes


Summary of rules for using the parentIndex parameter

If you are modifying a business object for Clarify CRM and want to use the business object for Retrieve operations, you will need to set up the ParentIndex parameter in the business object application-specific text. Follow these rules:

Assigning an attribute a value from another table

You can use the AttrNameToLookFor and FieldNameToRetrieve parameters to retrieve data from a field in another table and assign the value to the current attribute. To do this, you specify a table name using the AttrNameToLookFor parameter and a field name using the FieldNameToRetrieve parameter. This assigns the value in that field to the table and field for the current attribute. An example of application-specific text for this is:

AppSpecificInfo = site_part:site_objid::1:::CustomerId:objid 

In this example, the connector retrieves the value of objid from the table pointed to by attribute name CustomerId and assigns it to the site_objid column of the site_part table. Figure 15 illustrates this application-specific text.

Figure 15. Assigning an attribute a value from an attribute in another table


Note that these parameters can only be used to retrieve values for attributes within a single business object; they cannot be used to retrieve values across business objects.

Preprocessing attributes

The application-specific information for an attribute can be coded so that the connector obtains the value for the attribute before executing a business object request, such as an Update or Retrieve.

To use preprocessing, you must edit the business object definition. In the application-specific information for the attribute you want to preprocess, use the following format:

PP= viewOrTable:column:condition:location[:condition2:location2]

where:

viewOrTable 
is the name of the database view or table used for the preprocessing.
column 
is the name of the column where the connector will search for the value of this attribute
condition 
is the name of an attribute whose value is used to retrieve this attribute from location. The value cannot be a Clarify CRM relation
location 
is the name of the column where the connector searches for the condition value
condition2 
is the name of the optional second attribute whose value is used to retrieve this attribute. The value cannot be a Clarify CRM relation.
location2 
is the name of the column where the connector searches for the condition2 value
condition3 
is the name of the optional third attribute whose value is used to retrieve this attribute. The value cannot be a Clarify CRM relation.
location3 
is the name of the column where the connector searches for the condition3 value

Add the information to the application-specific information as follows:

Example: Preprocessing attributes

View x_mp has three fields: modlevel_objid, modlevel_name, and part_id. The connector can retrieve the value of the ModLevelObjId attribute using the values of the attributes ModLevel and ItemId.

The ModLevelObjId attribute's application-specific text is:

PP=x_mp:modlevel_objid:ModLevel:modlevel_name:ItemId:part_id|... 

The connector obtains the values of the conditions and uses them to obtain the value of the attribute whose preprocessing this represents. The connector could use the following SQL statement when preprocessing the ModLevelObjid attribute, if the value found in the modlevel_name column is x, and the value found in the ItemID column is y.

Select modlevel_objid from table_x_mp where modlevel_name = x and part_id = y

Generating attribute values automatically

You can use application-specific text for an attribute to automatically generate values for attributes such as IDs. This application-specific text uses the Clarify CRM table table_num_scheme, which contains all the ID fields for Clarify CRM tables. If you want to add IDs to this table, see the Clarify CRM documentation for information.

You can automatically generate the value of one or more attributes in a single business object. To automatically generate values for an attribute, you must edit its application-specific information. In the application-specific information, use the following format:

AppSpecificInfo = SchemeName=Value

where Value specifies the name of the scheme from the name column of the table_num_scheme table.

Add the name-value pair to the application-specific information as follows:

Note the following rules:

Example: Generating ID values for an attribute

For example, to generate sequential ID values for the SiteID attribute in the example Clarify_PartnerSite business object, use the following text:

AppSpecificInfo = SchemeName=Site ID|site:site_id::3: 

Retrieving by non-key values

A business process might need to retrieve a business object for which it has a set of attribute values without having the one key attribute that uniquely identifies an application record. Such a retrieve is called "retrieve by non-key values" or "retrieve by content."

The connector allows retrieval by non-key values if the following conditions are met:

When the connector receives a request for a RetrieveByContent operation, it queries Clarify CRM for the appropriate record by using all the non-null values for attributes designated as RetrieveByContent (RBC). When the connector gets a response, it fills in values for the designated attributes that were previously null.

The connector can return the business object with all designated attributes filled in or follow-up with a subsequent Retrieve operation to get the entire business object. However, the connector does a subsequent Retrieve only if the application-specific business object definition specifies that it should.

Setting up a business object for retrieving by non-key values

To define a business object for retrieving by non-key values, do the following:

Specifying the attributes

Each attribute that will supply a value to the Retrieve operation or receive a value from the retrieve must be defined by adding the following parameter to the attribute's application-specific information:

RBC=tableName:fieldName

The tableName argument is the name of a view or table in the database. This value must be the same for all attributes used in a non-key retrieve. The use of a view lets you include values from different tables.

The first attribute of the business object must always be coded for non-key retrieve in order for any attribute to be used. This ensures that the key value will be filled in as a result of the operation.

Add the information to the application-specific information as follows:

Specifying subsequent retrieve

To define a business object to follow a Retrieve by non-key values operation with a subsequent regular Retrieve operation, place the following property in the application-specific information for the RetrieveByContent verb:

SubsequentRetrieve=true

The default value for this property is false. The connector performs a deep or shallow retrieve based on the value of the RequestRetrieve configuration parameter.

Application-specific text for container attributes

For Update operations, you can edit the application-specific text for attributes that contain child business objects to specify that the connector keep any existing relations between tables and add new relations required by new child business objects. The format for this application-specific text is:

AppSpecificInfo = keeprelations

Case is ignored in checking for this application-specific text.

If this parameter is not specified, the connector deletes existing relations between the parent business object and child business object tables and then adds any new relations required by new child business objects.

Note:
If the parent business object is non-existent, the update fails.

As an example, if an existing contract is associated with an existing site, such as New York, and the connector receives an Update Contract business object with a child business object representing a new site, such as San Francisco, and the container attribute application-specific text has the value keeprelations, the contract will be associated with both New York and San Francisco. If keeprelations is not specified, the contract will be associated only with San Francisco.

Figure 16 shows how the keeprelations value is set in the System Manager for the Contract business object to associate a new ContractLine with an existing Contract.

Figure 16. Example of the keeprelations value in the contract business object


Note:
If updating data in a child object when there are multiple child objects, you must provide the child object ID (not CxIgnore) in order to preserve relations to the other children even when keeprelations is used. This is different from using CxMissingID, which would add a new child object (and keep relations to the existing children) instead of updating the data for an existing child. The child ID is required since the connector needs to know which child to update and will delete relations to all children except the first if it does not know the child ID to be updated.

The connector uses verb application-specific text to specify the following types of Retrieve operations:

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

Retrieve verb

The default action for a Retrieve verb is to retrieve the parent business object and all related child objects. You can edit the application-specific text for the Retrieve verb to specify that the connector retrieve only the parent business object in a hierarchical object. This feature is used for event processing only.

The application-specific text to retrieve only the parent object is RetrieveAll=False. This text is associated with the Retrieve verb, but it applies to all verbs. An example of a Retrieve verb with this text is:

[Verb]
Name = Retrieve
AppSpecificInfo = RetrieveAll=False 

Specifying a retrieve following a retrieve by non-key values

The RetrieveByContent verb specifies a set of attribute values other than the key attribute for the connector to use when building a Retrieve query. In a RetrieveByContent operation, the connector returns values for the business object key and for other designated attributes. You can edit the application-specific text for the RetrieveByContent verb to specify that the connector follow a RetrieveByContent operation with a subsequent Retrieve operation to retrieve the entire business object.

To specify that the connector follow a RetrieveByContent operation with a Retrieve operation, place the following property in the application-specific text for the RetrieveByContent verb:

AppSpecificInfo = SubsequentRetrieve=true

The default value for this property is false.

Copyright IBM Corp. 1997, 2004