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. The connector parses the application-specific information from the attributes or verb of a business object or from the business object itself to generate queries for create, update, retrieve, and delete operations.

The connector stores some of the business object's application-specific information in cache and uses this information to build queries for all the verbs.

If you extend or modify an application-specific business object, 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-level, attribute, and verb application-specific information format for business objects supported by the connector.

Table 34 provides an overview of the functionality available in business object application-specific information.

Table 34. Overview of application-specific information in supported business objects

Scope of application-specific information Functionality
Entire business object Specifies:
  • The name of the corresponding database table.
  • Defines the column whose value the connector uses in the WHERE clause to perform a logical (or soft) delete.
  • That the top-level business object is a wrapper.
Simple attributes Specifies:
  • The database column name for an attribute.
  • The foreign key relationship between an attribute in the current business object and a parent or child business object.
  • Automatic generation of unique identifier values.
  • The name of another attribute within the same business object whose value the connector must use to set the value of the current attribute.
  • Whether to use the current attribute when sorting a retrieval.
  • The value to use when the value of the current attribute is null.
  • String substitution behavior.
  • Whether to use the LIKE operator or = operator when comparing strings.
  • The value to use as the wildcard position when the LIKE operator is used.
Attributes that contain a child or an array of child business objects Specifies whether a single-cardinality child is owned by the parent. Specifies whether the connector deletes child data during an update operation if the data is not represented in the source business object.
Business object verb Used only for the Retrieve verb, this text specifies the attributes to be included in the WHERE clause for a retrieval. You can also specify operators and attribute values.

The following sections discuss this functionality in more detail.

Application-specific information at the business-object level

Application-specific information at the business-object level allows you to:

At the business-object level, application-specific information format consists of parameters separated by colon (:) or semicolon (;) delimiters:

TN=TableName; SCN=StatusColumnName:StatusValue

where TableName identifies the database table, StatusColumnName is the name of the application database column used to perform logical deletes, and StatusValue is the value that signifies that a business object is inactive or deleted.

For example, assume that a Customer business object has the following value specified for its business object application-specific information:

TN=CUSTOMER; SCN=CUSTSTATUS:DELETED

Assume also that the connector receives a request to delete the customer. Such a value causes the connector to issue the following SQL statement:

UPDATE CUSTOMER SET CUSTSTATUS = 'DELETED' WHERE CUSTOMER_ID = 2345

If the SCN parameter is not included or no value is specified for it, the connector physically deletes the business object from the application database. In other words, if the business object with the Delete verb includes the SCN parameter in its application-specific information, the connector performs a logical delete. If the business object with the Delete verb does not include the SCN parameter in its application-specific information, the connector performs a physical delete.

Both update and delete operations may use the value of the SCN property:

At the business-object level, application-specific information may be used to specify a wrapper:

WRAPPER=true|false

If the wrapper parameter is set to true, the top-level business object is a wrapper object. The wrapper object is not represented by a database table or view. A wrapper is used as a container for unrelated business objects. The connector ignores the top-level object and processes only the children. The wrapper object may contain N cardinality or N-1 cardinality entities or both.

Application-specific information at the attribute level

The application-specific information for attributes differs depending on whether the attribute is a simple attribute or an attribute that represents a child or an array of child business objects. The application-specific information for an attribute that represents a child also differs depending on whether the parent/child relationship is stored in the child or in the parent. For information on application-specific information for attributes that represent a child or array of child business objects, see Specifying an attribute's foreign key.

Application-specific information for simple attributes

For simple attributes, application-specific information format consists of eleven name-value parameters, each of which includes the parameter name and its value. Each parameter set is separated from the next by a colon (:) delimiter.

The format of attribute application-specific information is shown below. Square brackets ([ ]) surround an optional parameter. A vertical bar (|) separates the members of a set of options. Reserve the colon as a delimiter.

CN=col_name:[FK=[fk_object_name.]fk_attribute_name]:
[UID=[AUTO|uid_name| schema_name.uid_name [=UseIfMissing]|CW.uidcolumnname 
[=UseIfMissing]]]:
[CA=set_attr_name|..set_attr_name]:[OB=[ASC|DESC]]:[UNVL=value]:
[ESC=true|false]:[FIXEDCHAR=true|false]:
[BYTEARRAY=true|false]:[USE_LIKE=true|false:
[WILDCARD_POSITION=non-negative number|NONE|BEGIN|END|BOTH]]:
[CLOB=true]

The only required parameter for a simple attribute that you want the connector to process is the column name. For example, to specify only the column name, use the following format:

CN=customer_id

Table 35 describes each name-value parameter.

Table 35. Name-value parameters in attribute application-specific information

Parameter Description
CN=col_name
The name of the application database column for this attribute.
FK=[fk_object_name.]
fk_attribute_name
The value of this property depends on whether the parent/child relationship is stored in the parent business object or the child If an attribute is not a foreign key, do not include this parameter in the application-specific information. For more information, see "Specifying an attribute's foreign key".
UID=AUTO

UID=uid_name |
schema_name.uid_name
 [=UseIfMissing]

UID=CW.uidcolumnname
[=UseIfMissing]
The connector uses this parameter to generate the unique ID for the business object. If an attribute does not require generation of a unique ID, do not include this parameter in the application-specific information. See the PreserveUIDSeq property description for details on preserving the unique ID during business object processing. For more information, see "Generating a business object's unique identifier".
CA=set_attr_name|..set_attr_name

If set_attr_name is set to the name of another attribute within the current individual business object, the connector uses the value of the specified attribute to set the value of this attribute before it adds the business object to the application database during a Create operation.

The value of set_attr_name cannot reference an attribute in a parent or child business object, but it can reference an attribute in the parent business object if there if set_attr_nameis preceded by the two periods.

If you do not include this parameter in the application-specific information, the connector uses the value of the current attribute without copying the attribute's value (CA) from another attribute.

OB=[ASC|DESC] 

If a value is specified for this parameter and the attribute is in a child business object, the connector uses the value of the attribute in the ORDER BY clause of retrieval queries.

The connector can retrieve child business objects in ascending order or descending order.

Use ASC to specify retrieval in ascending order.

Use DESC to specify retrieval in descending order.

If you do not include this parameter in the application-specific information, the connector does not use this attribute when specifying retrieval order.

UNVL=value
Specifies the value the connector uses to represent a null when it retrieves a business object with null-valued attributes. If you do not include this parameter in the application-specific information, the connector inserts a CxIgnore for the attribute's value.
ESC=[true|false]
Determines whether the connector replaces all instances of each character identified in the ReplaceAllStr property with the substitution strings also specified in the ReplaceStrList property. If this parameter does not contain a value, the connector uses the value of the ReplaceStrList property to make this determination.
FIXEDCHAR=
true|false
Specifies whether the attribute is of fixed length when the columns in the table are of type CHAR, not VARCHAR. For example, if a particular attribute is linked to a column that is of type CHAR, the connector expects FIXEDCHAR in length; for the application specific information of that attribute specify FIXEDCHAR=true. Ensure that the MaxLength property of the attribute is of the CHAR length, which is specified in the application database. By default, FIXEDCHAR=false.
BYTEARRAY=true|false
If BYTEARRAY=true, the connector will read and write binary data to the database and will send that data as a string to ICS/WebSphere MQ Integration Broker. BYTEARRAY=false is the default.
USE_LIKE=true|false
Specifies whether the connector compares strings using the = operator or the LIKE operator. If USE_LIKE is set to true, wildcard queries can be performed by setting WILDCARD_POSITION. If USE_LIKE is set to false, the =operator will be used.
WILDCARD_POSITION=non-negative

number|NONE|BEGIN|END|BOTH
If USE_LIKE is true, the WILDCARD_POSITION is used to specify the position that is the wildcard. This value can be any non-negative number, NONE, BEGIN, END, or BOTH. For example, using BEGIN will place the wildcard character in the first position of the string (%string). Using END will place the wildcard character in the last position of the string (string%). Using BOTH will place wildcard characters in both the first and last position in the string (%string%).
CLOB=true
Only applicable for String Attribute Type. Specifies that the database column that corresponds to this attribute is a CLOBdatatype.

Note:
If none of the application-specific information in any of a business object's attributes cause the connector to build or execute a query, the connector logs a warning and continues operating. It does not throw an exception or return a failure.

Specifying an attribute's foreign key

The value of this property depends on whether the parent/child relationship is stored in the parent business object or the child:

If the value of fk_object_name does not match the type of the child business object, and the value of fk_attribute_name does not match the name of the attribute in the parent or child (as applicable), the connector cannot process this attribute as a foreign key. The case of the business object's name and the attribute's name is significant.

For example, assume that the Customer business object contains the Addr[1] attribute, which represents the Address child business object, and the AID attribute, which stores the primary key of the child business object as a foreign key. In this case, the application-specific information of the parent's foreign key attribute must contain the type of the child business object (Address) as well as the name of its primary key attribute (ID). In this example, the application-specific information of the AID attribute would include FK=Address.ID.

Naming a foreign key attribute

Multiple parent business objects can contain the same child business object, regardless of whether the child is stored with single cardinality or multiple cardinality, and regardless of whether the parent/child relationship is stored on the parent or on the child. However, all parent business objects that store the parent/child relationship must use identically named attributes to contain the child's primary key. Moreover, all child business objects that store the parent/child relationship must use identically named attributes to contain the parent's primary key. Figure 23 illustrates these relationships.

Figure 23. Example of relationships among business objects


Figure 23 illustrates the following relationships:

For more information on the KEEP_RELATIONSHIP parameter, see Application-specific information for attributes that represent children.

The application-specific information for the parentID attribute of each child in the array of Organizations contains the name of the column in the application database that corresponds to the current attribute, and specifies the current attribute's foreign key by containing the name of the parent's primary key attribute; for example:

CN=ORG_ID:FK=ID
Note:
For multiple business objects to contain the same child (where the parent/child relationship is stored in the child), all parent business objects must use an identically named attribute to contain the foreign key for the child. The foreign key parameter of that child's application-specific information identifies only the attribute's name and not the type of the parent business object. The connector assumes that the direct parent is the owner of each child.

Generating a business object's unique identifier

The connector uses the UID parameter to generate the unique ID for the business object. The connector generates unique IDs by using sequences, or counters (which are structured as tables), and then issues the INSERT statement.

The connector uses a sequence or counter to generate the ID value and then issues the INSERT statement:

See the PreserveUIDSeq property for information on preserving the unique ID sequence during processing.

Application-specific information for attributes that represent children

Attributes that represent a single-cardinality child business object can specify whether the child is owned by the parent or shared among multiple parents.

Attributes that represent a single-cardinality child or an array of child business objects can specify the connector's behavior when updating the parent and a subset of the children.

Attributes that represent a single-cardinality child business Object

The format of the application-specific information for attributes that represent a single-cardinality child business object is:

CONTAINMENT= [OWNERSHIP|NO_OWNERSHIP]

Set CONTAINMENT to OWNERSHIP to represent a single-cardinality relationship where the parent owns the child business object. Set CONTAINMENT to NO_OWNERSHIP to represent a single-cardinality relationship where the parent shares the child business object. Do not include the CONTAINMENT parameter when you represent a single-cardinality relationship that stores the relationship in the child rather than in the parent.

For more information, see Single-cardinality relationships and data without ownership and Wrapper objects.

Attributes that represent a child that stores the parent's Key

For Update operations on an array of business objects that store the parent/child relationship in the child, there is a special value for the attribute that represents the child: you can set KEEP_RELATIONSHIP to true to prevent the connector from deleting existing child data that is not represented in the source business object.

For example, assume an existing contract is associated with an existing site, such as New York. Assume further that the connector receives a request to update a Contract business object that contains a single child business object that associates San Francisco as the site. If KEEP_RELATIONSHIP evaluates to true for the attribute that represents the site data, the connector updates the contract to add its association with San Francisco and does not delete its association with New York.

However, if KEEP_RELATIONSHIP evaluates to false, the connector deletes all existing child data that is not contained in the source business object. In such a case, the contract is associated only with San Francisco.

The format for this application-specific information is:

KEEP_RELATIONSHIP=[true|false]

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

Working with Binary Data

If BYTEARRAY=true, the connector will read and write binary data to the database. Since there is no support for binary data in the current version of the WebSphere business integration system framework, the binary data is converted to a String and then sent to the integration broker. The format of this string is a hexadecimal number with 2 characters per byte. For example, if the binary data in the database is 3 bytes with the (decimal) values (1, 65, 255), the string will be "0141ff".

Application-specific information format for verbs

The connector uses verb application-specific information for the Retrieve andRetrieveByContent verbs. This text allows you to specify the attributes to be included in the WHERE clause for a retrieval. You can also specify operators and attribute values.

The syntax for application-specific information for the Retrieve and RetrieveByContent verbs is shown below:

[condition_variable conditional_operator @ [...]:[..]attribute_name [, ...]]

where:

condition_variable
The name of the application database column.
conditonal_operator
The operator supported by the application database, for example =, >, OR, AND, and IN (value1, value2).
@
A variable that is substituted with the value retrieved by getAttrValue(attribute_name). The substitution is positional; that is, the connector substitutes the first @ with the value of the first attribute_name variable specified after the : delimiter.
..
The attribute specified in the attribute_name variable belongs to the immediate parent business object; if this value is missing, the attribute belongs in the current business object.
attribute_name
The name of the attribute whose value the connector substitutes for @.

To understand the syntax of this property, assume that an Item business object has an item_id attribute whose value is XY45 and a Color attribute whose value is RED. Assume further that you specify the Retrieve verb's AppSpecificInfo property as:

Color='RED'

The above application-specific information value causes the connector to build the following WHERE clause for a retrieval:

where item_id=XY45 and Color = 'RED'

For a more complicated example, assume that the Customer business object has a customer_id attribute whose value is 1234 and a creation_date attribute whose value is 01/01/90. Assume also that this business object's parent has a quantity attribute whose value is 20.

Assume further that you specify the Retrieve verb's AppSpecificInfo property as:

creation_date > @ OR quantity = @ AND customer_status 

IN ('GOLD', 'PLATINUM') : creation_date, ..quantity

The above application-specific information value causes the connector to build the following WHERE clause for a retrieval:

where customer_id=1234 and creation_date > '01/01/90' 
OR quantity = 20 AND customer_status IN ('GOLD', 'PLATINUM') 

The connector gets the date value ('01/01/90') from the creation_date attribute in the current business object. It gets the quantity value (20) from the quantity attribute in the parent business object (as indicated by ..quantity in the application-specific information.

After the connector parses the application-specific information for the Retrieve verb, it adds the text to the WHERE clause of the RETRIEVE statement that it constructs from the business object's primary or foreign keys. The connector adds the leading AND to the WHERE clause. The value of the application-specific information must be valid SQL syntax. In the case of RetrieveByContent, the application-specific information is added to the WHERE clause of the RETRIEVE statement that it constructs from the business object's attributes that have their values populated.

The WHERE clause can also refer to placeholder attributes instead of the actual attributes in the parent business object. These placeholders do not have any application-specific information. An attribute can be a placeholder if it satisfies one of the following conditions for its ASI:

  1. Simple attribute with ASI=null or ''
  2. Simple attribute with ASI=PH=TRUE

For example: An Order business object contains a multiple cardinality line item business object, and retrieval of only specific line items is needed. This retrieval can be handled through a placeholder attribute in the Order business object. This placeholder is required in the parent object because the child objects are all pruned. When ICS is the integration broker, the placeholder attribute can be populated at runtime by a map with a list of the specific line items, separated by a comma (,).

For this example, you would add the following information to the WHERE clause for the retrieve verb on the child line item business object:

line_item_id in(@):..placeholder

Where line_item_id in is the ID in the child business object, placeholder is the attribute in the parent. If placeholder contains the values 12,13,14 the query would select the following from the WHERE clause:

line_item_id in(12,13,14)

Where SELECT:..FROM:..WHERE x in (1,2,3) is a standard database SQL syntax.

In the RetrieveByContent verb, if the length of the WHERE clause is 0, the connector will use the application-specific information in the WHERE clause of the RETRIEVE statement. With this feature, the user can send a business object with no attribute values populated and specify verb application-specific information for RetrieveByContent, and the connector will build the WHERE clause based on what was specified in the verb application-specific information alone.

Copyright IBM Corp. 1997, 2003