Contents of application-specific business object definitions

A business object definition includes the following information:

Table 6. Contents of a business object definition.

Contents of business object definition Description For more information
Business object structure The structure of an application-specific business object is typically designed to correspond closely to the application entity (data structure) at the level that the connector or data handler interacts with the application (such as at the table level, the API level, or at different levels within an API). "Structure of application-specific business objects"
Attribute properties Attributes contain individual pieces of data within an application entity. They also have properties that provide information such as the data's type, cardinality, and default value. Attribute properties also specify whether the attribute is required or key. "Attributes in an application-specific business object"
Application-specific information An application-specific business object definition often includes text strings that tell the connector how the business object is represented in the application or how to process it. "Business object application-specific information"

Structure of application-specific business objects

The way a connector or data handler processes business objects is determined in part by the structure of the business objects that it supports. As you design the structure of an application-specific business object, you need to determine what structure best represents a particular application entity and how this structure affects the design of connector and data handler logic or how the structure is processed by an existing connector or data handler.

While a goal of connector and data handler design is to code a connector or data handler so that it can handle new and changed business objects without modification, it is difficult to create a connector or data handler that can handle any possible business object.

Typically, a connector or data handler is designed to make assumptions about the structure of its business objects, the relationships between parent and child business objects, and the possible application representation of business objects. If designing for an existing connector or data handler, your task is to understand these assumptions and design business objects accordingly.

A beginning set of questions to consider about the structure of an application-specific business object is:

For more information about the business object structures that can represent single or multiple application entities, see "Determining business object structure".

Note:
Certain connectors may require the top-level business object to contain specific information. For example, the XML connector requires its top-level business object to contain simple attributes for a URL, MIME type, and business object prefix, as well as complex attributes to contain a request business object and a response business object. If you are designing a business object for an existing connector, refer to its adapter user guide for specific structure requirements. For more information, see "Designing for an existing connector or data handler".

Attributes in an application-specific business object

The attributes hold the individual pieces of data in an application entity. When defining attributes for an application-specific business object, consider these questions:

As a rule, keep the structure of the business object the same as the structure of the corresponding application entity (such as database tables or DTDs). If the business object is large (contains many attributes), define only the attributes that are used in the business process for which you are designing the business object. However, if the business object is small, define all of the attributes to be available for future use. The number of attributes you define depends on the size of the business objects and the complexity of the relationships between them.

In addition to identifying which application entities must exist as attributes in the business object, you should also examine the business process to determine if any additional attributes are required. As part of the analysis of the business process, identify the business object's requirements. Stepping through a business process reveals how a business object is handled and how the required attributes are used. Variations in the business process and the handling of exceptions might identify additional attributes that are required to process the business object. These additional attributes might not correspond to data that is retrieved or updated in the application.

For example, you may need attributes that:

Business object application-specific information

After you have defined the structure of an application-specific business object definition and defined the set of attributes that the business object definition contains, you can determine whether the connector or data handler needs additional information about how to process the business object to enable it to handle the requests it receives from the integration broker. The business object definition can include this additional information in application-specific information.

Application-specific information provides the connector or data handler with application-dependent instructions on how to process business objects. The recommended approach to designing the relationship between business objects and connectors is to store information in the business object definition that helps a connector interact with an application or data source. Such information, called metadata, can be specified in the application-specific information of each business object, business object attribute, and business object verb.

The application-specific information is a string that is entered during business object design and read at run time by a connector or data handler. The connector or data handler uses the metadata in the business object definition to process business object instances. Because the connector or data handler has access to its supported business object definitions at run time, it can dynamically determine how to process a particular business object.

Consider the following advantages and limitations of application-specific information when designing a business object:

Suggested format of application-specific information

It is recommended that you use name-value pair syntax when you define application-specific information. This syntax specifies the name of the property and its associated value, separated by a equals sign (=), as the following syntax shows:

name1=value1;name2=value2
 

For example, the following name-value pair defines a "table name" property:

TN=TableName
 

Name-value pairs allow values to be specified in random order. The connector evaluates the name of each parameter before interpreting the value. It is recommended that you separate name-value pairs with a delimiter that:

Note:
If you are creating a business object for an existing connector, check its adapter user guide to determine the syntax that it requires. Not all connectors may default to use a semicolon as a delimiter, or be configurable in that respect.

Table 7 provides examples of parameters that can be included in an attribute's application-specific information. These parameters are relevant only to a business object that represents data in a database table.

Table 7. Example name-value parameters for attribute application-specific information.

Parameter Description
TN=TableName
 
The name of the database table.
CN=col_name
 
The name of the database column for this attribute.
FK=[..]fk_attributeName] The value of the Foreign Key property defines a parent/child relationship.
UID=AUTO This parameter notifies the connector to generate the unique ID for the business object and load the value in this attribute.
CA=set_attr_name
 
The Copy Attribute property instructs the connector to copy the value of one attribute into another. 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.
OB=[ASC|DESC] If a value is specified for the Order By 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 to determine whether to retrieve the child business object in ascending order or descending order.
UNVL=value
 
Specifies the value the connector uses to represent a null when it retrieves a business object with null-valued attributes.

One attribute's application-specific information might combine several of the example parameters listed above. This example uses semicolon (;) delimiters to separate the parameters:

TN=LineItems;CN=POid;FK=..PO_ID
 

The application-specific information in this example specifies the name of the table, the name of the column, and that the current attribute is a foreign key that links the child business object to its parent.

Content of application-specific information

The content of application-specific information can vary considerably in complexity. Some examples are:

If the business object definition includes application-specific information and the connector has been designed to make use of it, the connector can extract the content of the application-specific information from the business object definition and use it for processing.

Example: How a connector processes application-specific information

As an example of how a connector processes application-specific information, assume that your application is based on tables and that you want to work with an application table called CURRENTCUST, which stores information on customers. This table has two columns: CSTName and CSTCity.

In the AppSpecificInfo property of the business object header, you can store the table name. In the AppSpecificInfo property of each attribute, you can store the column names. In addition, because the connector for this application uses SQL statements to interact with the database, you can design the verb application-specific information to hold SQL verbs and keywords. Figure 18 illustrates how this Customer business object definition might look.

Figure 18. Application-specific information in a business object definition.

When a metadata-driven connector receives an instance of this business object from an integration broker, it extracts the table name and column names from the application-specific information properties in the business object definition, and then extracts the attribute and verb values from the business object instance. Using the table and column names, the attribute values, and the SQL keywords in the verb application-specific information, the connector can build an SQL statement.

Figure 19 shows an example of this type of processing. The connector extracts the verb processing instructions and the table and column names from the business object definition. It then gets the attribute values from the business object instance. Using this information, the connector builds an SQL INSERT statement to update the CURRENTCUST table with the new information.

Figure 19. Using application-specific information to build an SQL statement for a Create operation

As mentioned above, a business object definition can include AppSpecificInfo text for the business object as a whole, and for its attributes and verbs. The following sections provide more information on the use of application-specific information in these components of a business object.

Important

The length of application-specific information is restricted to 1000 characters.

Figure 5 uses the attribute-level AppSpecificInfo property to store the name of the Invoice subform and the attribute's corresponding field name. The example uses name-value pairs to specify the information.

Tips on designing application-specific information

When designing business objects to maximize the metadata-driven behavior of a connector, follow these general recommendations for storing application-specific information in the business object definition:

The careful use of the AppSpecificInfo property enables a connector to handle a variety of business objects in the same way. If an application is consistent in how it handles data operations, and if for all operations the connector performs consistent tasks, the business object can be designed to enable a completely metadata-driven connector.

Copyright IBM Corp. 1997, 2004