Business object architecture defines various properties that apply to attributes. This section describes how the connector interprets several of these properties and describes how you should set them when modifying a business object.
Each business object attribute must have a unique name.
Each business object attribute must have a type, such as Integer, String or the type of a contained child business object.
At least one simple attribute of every business object for Clarify CRM must be specified as the key. To do so, set this property to true. The key attribute is always the first attribute. Therefore, when creating a business object for Clarify CRM, be sure to define the first attribute as the key so that Create operations will return a value for the new key and Retrieve operations will return the correct record from the table that the business object represents.
Note that the connector ignores multiple keys and only uses the first key, except in Retrieve operations when the application-specific text in the business object definition specifies multiple key retrieve; for information on multiple key retrieve, see "Specifying multiple key attributes for retrieve operations".
The key property is processed slightly differently in top-level business objects and child business objects.
For Create operations, the connector processes key attributes as follows:
If the key represents the objid field in a Clarify CRM table, but the value for the key is not null, the connector attempts to create a record with a new key value. Depending on the Clarify CRM schema and indexes, one of the following behaviors will occur:
On Create and Update operations, the Clarify CRM application is designed to generate its own objid values. For this reason, it is strongly recommended that you not design business objects to pass in values for objid fields unless you know how the Clarify CRM application will behave.
For information on automatically generated values for attributes, see "Generating attribute values automatically".
In all cases, on a successful completion of a Create operation, the connector will return a populated key in the business object, whether the value was the objid value, a value for a non-objid field, or an automatically generated value.
For a Retrieve operation, if the attribute is a key, its value is used to retrieve the other values for the business object, but the key value itself is not retrieved from the database. If the verb is Retrieve and the key value is CxMissingId, the connector will return a failure because it cannot retrieve the object.
If the verb is Create or Update and the value of the key is unknown for a child business object, use the string CxMissingId for the key attribute value. When the key value of a child business object is set to CxMissingId, the connector will perform a Create for a child object without first checking whether the record already exists.
However, because the query parameters are not constrained when there is more than one child object, there is a possibility of orphan data in the Clarify CRM database. To eliminate this possibility, cross reference child keys.
Relationships between tables in the Clarify CRM application are defined by named relations rather than by foreign keys. As an example, information on a business organization is stored in Clarify CRM in the bus_org table. This table includes relations to the site and address tables, which store information on the organization's site and primary address. The relations are implemented as columns in the bus_org table.
WebSphere Business Integration Adapter business objects for Clarify CRM use Clarify CRM named relations to represent relationships between tables. Each individual business object can reference multiple tables by including attributes whose application-specific text specify the relations. When several attributes reference the same foreign table, the relation is specified in the first attribute that references the table.
Because relationships are contained in named relations, the Foreign Key property is not used in business objects for Clarify CRM to explicitly specify that an attribute represents a foreign key. Instead, this property is used to define how the connector processes attributes with relations.
The rules for connector processing of Foreign Key attributes for Create and
Update operations are shown in Table 13. Note that the Foreign Key property is only checked
for attributes that have named relations in their application-specific
text.
Table 13. Connector processing of foreign key property
Foreign key property setting | Attribute value | Description of connector processing |
---|---|---|
true | Not null | If the attribute application-specific text includes a named relation, the connector checks for the existence of the record in the application database using the value of the Foreign Key attribute. If the record exists, the connector creates the relation between the entities. If the record does not exist, the connector returns BON_FAIL. |
true or false | Null | The connector evaluates whether the foreign key attribute is required (the Required property is set to true). If the attribute is required, the connector returns BON_FAIL. If the attribute is not required, the connector skips the attribute. |
false | Not null | If the attribute application-specific text includes a named relation, the connector checks for the existence of the record in the application database using the value of the Foreign Key attribute. If the record exists, the connector creates the relation between the entities. If the record does not exist, the connector creates the record and creates the relation. |
As shown in Table 13, the Foreign Key property is overloaded in business objects for Clarify CRM to specify what kind of foreign key lookup the connector will perform. If Foreign Key is set to false, the connector performs a dynamic lookup of the related record, creating the relation if the record exists and creating both the record and relation if the record does not exist. If Foreign Key is set to true, the connector simply creates the relation if the record exists and fails the operation if it does not exist.
As an example, suppose that the AddressState_prov attribute in the Clarify_SiteAddress business object specifies a state in the Clarify state_prov table. If the state_prov table already contains all state names, you can set Foreign Key to true so that the connector will find an existing state name or fail. This limits the spellings of state names to those in the table. If the spelling of state names is not important, you can set Foreign Key to false so that the connector will insert any spelling of state names.
In summary, when modifying business objects for Clarify CRM, use the Foreign Key property to specify what kind of lookup the connector should perform.
The Required property specifies whether an attribute must contain a value. If a particular attribute in a business object that you are modifying must contain a value, set the Required property to true.
If the verb is Create and Required is true, the connector will cause the Create operation to fail if the business object does not have a valid value or a default value for a Required attribute.
The connector does not check the Required property for verbs other than Create.
The connector does not currently use the Max Length property. It is good practice, however, to set the value of this property to the number of bytes the attribute can contain. At a minimum, set the value of Max Length to 8 so that the attribute value can be CxIgnore.
This property specifies a default value for the attribute that will be used if there is no runtime value for the attribute in the business object. If the following criteria are met, the UseDefaults configuration property is enabled:
If the UseDefaults property is enabled the following will occur: