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. |
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.
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.
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:
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".
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. |
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.
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.
Figure 7. Attribute
application-specific text specifying table name, field name, and
data type
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.
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
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:
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
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
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.
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.
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
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:
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.
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:
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
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:
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:
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.
To define a business object for retrieving by non-key values, do the following:
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:
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.
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.
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
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.
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
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