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 10 provides an overview of the functionality available in
business object application-specific information.
Table 10. Overview of application-specific information in supported business objects
Scope of application-specific information | Functionality |
---|---|
Entire business object | Specifies:
|
Simple attributes | Specifies:
|
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 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; WRAPPER=true|false
where TableName identifies the database table, StatusColumnName is the name of the database column used to perform logical deletes, and StatusValue is the value that signifies that a business object is inactive or deleted, and true|false indicates whether the top-level business object is a wrapper object.
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 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.
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.
For simple attributes, application-specific information format consists of a number 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]]]: [PH=true|false]:[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] [TS=true|false]]
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 11 describes each name-value parameter.
Table 11. Name-value parameters in attribute application-specific information
Parameter | Description |
---|---|
CN=col_name | The name of the 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. |
PH=true|false | If PH=true, then the corresponding simple attribute is a placeholder attribute. A simple attribute is also a placeholder if its ASI is blank or null. |
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 database during a Create operation. The value of set_attr_name cannot reference an attribute in a 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.
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 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 or WebSphere MQ Integrator Broker. BYTEARRAY=false is the default. For more information, see "Working with binary data". |
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 CLOB
datatype.
|
TS=true|false | For attributes of type DATE, when TS=false is specified in the application-specific information for the attribute, the attribute is treated as a DATE type. When TS=true, the attribute is treated as a TIMESTAMP type. The default value of TS is true. |
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.
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 5 illustrates these relationships.
Figure 5. Example of relationships among business objects
Figure 5 illustrates the following relationships:
The application-specific information for the ORGS attribute might be:
KEEP_RELATIONSHIP=true
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 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
The application-specific information for the Addr attribute is:
CONTAINMENT=OWNERSHIP
The application-specific information for the AID attribute contains the name of the column in the database that corresponds to the current attribute, and specifies the current attribute's foreign key by containing the type of the child business object and the name of its primary key attribute; for example:
CN=FK_AD:FK=Address.ID
The application-specific information for the child's primary-key attribute is
CN=pk
The application-specific information for the SPID attribute is:
CONTAINMENT=NOOWNERSHIP
For more information on the CONTAINMENT parameter, see Application-specific information for attributes that represent children.
The application-specific information for the Address SPID attribute contains the name of the column in the database that corresponds to the current attribute, and specifies the current attribute's foreign key by containing the type of the child business object and the name of its primary key attribute; for example:
CN=FK_SP:FK=StateProvince.ID
The application-specific information for the child's primary key attribute is:
CN=SP_ID
The application-specific information for the child's parentID attribute contains the name of the column in the database that corresponds to the current attribute, and specifies the current attribute's foreign key by containing the name of its parent's primary key attribute; for example:
CN=SD_ID:FK=ID
The connector uses the UID parameter to generate the unique ID for the business object. The connector generates unique IDs by using sequences (as DB2 and Oracle do), or counters (which are structured as tables), and then issues the INSERT statement.
IBM DB2 and Microsoft SQL Server do not require that the ID be passed in an INSERT statement. Instead, they generate the ID at the time of creation. After successful creation of the business object, the connector can retrieve and use this value.
The connector uses a sequence or counter to generate the ID value and then issues the INSERT statement:
For information on configuring the table's name, see UniqueIDTableName. The script for installing this table is:
\connectors\i2ADW\dependencies\uid_table_oracle.sql \connectors\i2ADW\dependencies\uid_table_mssqlserver.sql \connectors\i2ADW\dependencies\uid_table_db2.sql
See the PreserveUIDSeq property for information on preserving the unique ID sequence during processing.
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.
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 Single-cardinality relationships that store the relationship in the child.
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.
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, 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".
The connector uses verb application-specific information only for the Retrieve and RetrieveByContent 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:
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:
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. The placeholder attribute can be populated at runtime by the integration broker 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.