Business objects in the WebSphere business integration system

The WebSphere business integration system consists of the following components:

In the WebSphere business integration system, information sent or received between components is packaged in the form of a business object, as follows:

Both application-specific business objects and generic objects are modeled during design-time as business object definitions, which are stored in the business integration system. At run time, data is populated in a business object instance (often called a "business object"), which is based on the appropriate definition. The business object moves through the business integration system as dictated by its routing and business logic rules.

Business object definitions

A business object definition represents a template for data that can be treated as a collective unit. It contains a business object header, which specifies the name and version of the business object definition. In addition, the business object definition contains the following information:

Figure 1 shows the parts of a business object definition.

Figure 1. Business object definition parts

The figure shows a business object broken down into its components. The first part is a header wich has the business object name, the version and application specific information. The next section is the business object attributes which consists of one or more attributes and their propertiers. The last part of the business object is the supported verbs and any application specific data pertaining to those verbs. The following sections describe these parts in detail.

Business object attributes and attribute properties

A business object contains attributes, each attribute representing one entity of data. In the business object definition, you define the name of each attribute as well as other attribute properties. The business object instance holds a value for each attribute (or indicates that the attribute does not have a value).

Note:
You can specify default values and string data within a business object in a bidirectional script. Any attribute names you define must only use characters in the US English character set.

Business object definitions include various properties that apply to attributes. These properties provide the connector, data handler, and other components with information on the types, sizes, and default values of attributes. The attribute properties are discussed in the sections that follow.

Name property

Each business object attribute must have a unique name within the business object definition. The name should describe the data that the attribute contains. The name can be up to 80 characters but cannot start with a numeric character. The name can contain alphanumeric characters and underscores but cannot contain spaces, punctuation, or special characters such as:

Notes:

  1. When designing an application-specific business object, check its adapter user guide or the Data Handler Guide for specific naming requirements and recommendations.

  2. This attribute name must use only characters defined in the code set associated with the U.S. English locale (en_US).

Type property

The Type property defines the data type of the attribute:

Note:
All attributes that represent child business objects also have a ContainedObjectVersion property (which specifies the version number of the child object's business object definition) and a Relationship property (which specifies the value Containment).

Cardinality property

Each simple attribute has single cardinality (cardinality 1). Each complex attribute, which represents a child business object or array of child business objects, has single cardinality or multiple cardinality (cardinality n), respectively. For more information on cardinality, see Hierarchical business objects.

Note:
When specified for a required attribute, single cardinality indicates that a child business object must exist, and multiple cardinality indicates zero to many instances of a child business object.

Key property

At least one attribute in each business object must be specified as the key. The key attribute contains a value that uniquely identifies the business object. To define an attribute as a key, set its Key property to true.

Note:
A key value in a business object is often referred to as its primary key.

When you specify as key a complex attribute:

Foreign key property

The Foreign Key property is typically used in application-specific business objects to specify that the value of an attribute holds the primary key of another business object, which links business objects. The attribute that holds the primary key of another business object is called a foreign key. Define the Foreign Key property as true for each attribute that represents a foreign key.

You can also use the Foreign Key property for other processing instructions. For example, this property can be used to specify what kind of foreign key lookup the connector performs. In this case, you might set Foreign Key to true to instruct the connector to check for the existence of the entity in the database and create the relationship only if the record for the entity exists.

Required property

The Required property specifies whether an attribute must contain a value. If a particular attribute in the business object must contain a value to be able to process the business object data, set the Required property for the attribute to true.

For information on enforcing the Required property for attributes within an

application-specific business object, see the section on initAndValidateAttributes() in the Connector Development Guide for C++ and Connector Development Guide for Java(TM).

AppSpecificInfo

The AppSpecificInfo property can contain a String of up to 1000 characters that is specified primarily for an application-specific business object. For information on this property, see Business object application-specific information.

Notes:

  1. Application-specific information is not available in the mapping process.

  2. You can specify this data in a bidirectional script, if required.

Max Length property

The Max Length property is set to the number of bytes that a String-type attribute can contain. Although this value is not enforced by the WebSphere business integration system, specific connectors or data handlers might use this value. Check the guide for the specific adapter or the guide for the data handler that processes the business object to determine minimum and maximum allowed lengths.

Important:
The Max Length property is very important when you use a fixed-width data handler.
Note:
Attribute length is not available in the mapping process.

Default value property

The Default Value property can specify a default value for an attribute.

If this property is specified for an application-specific business object, and the UseDefaults connector configuration property is set to true, the connector can use the default values specified in the business object definition to provide values for attributes that have no values at run time. For more information on how the Default Value property is used, see the section on initAndValidateAttributes() in the Connector Development Guide for C++ and Connector Development Guide for Java.

Notes:

  1. The attribute's default value can use any characters defined in the code set associated with the current locale.

  2. For an attribute whose type is String, you can specify a blank character as a default value.

Comments property

The Comments property allows you to specify a comment for an attribute. Unlike the AppSpecificInfo property, which is used to process a business object, the Comments property provides only documentation information, which may assist other developers in understanding your design decisions.

Note:
The attribute's comments can use any characters defined in the code set associated with the current locale including bidirectional characters. However, the newline character is invalid.

ObjectEventId attribute

The ObjectEventId attribute is not only required, but it must be the last attribute in every business object. The WebSphere business integration system uses this attribute to identify and track an event flow in the system.

The ObjectEventId attribute stores a unique value that identifies each event in the WebSphere business integration system.The connector framework generates values for this attribute in the parent business object and in each child.

Important:
Do not map the ObjectEventId attribute or have a connector or data handler populate it. The business integration system handles the value of this attribute.

Business object verbs

The business object definition includes a list of the verbs that the business object can support. These verbs correspond to operations that are valid on the data within the business object. At run time, a business object contains one active verb, which describes the operation to perform on the data in that particular business object.

Table 2 lists the basic verbs that a business object definition can support.

Table 2. Basic verbs

Verb Function
Create Make a new entity in the application.
Retrieve Using key values, return a complete business object.
Update Change the value in one or more fields in the application entity.
Delete Remove the entity from the application. This operation must be a true physical delete.

In addition to the basic verbs in Table 2, a business object definition might also need to support one or more of the following verbs:

Business object application-specific information

A business object definition can provide application-specific information, whose content provides metadata to the component that processes the business object. A common use of application-specific information is to provide a connector or data handler with application-dependent instructions on how to process the business object. 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.

Note:
Connectors that are designed to use the application-specific information in definitions of their application-specific business objects are called metadata-driven connectors. Because the processing information is configurable, rather than hard-coded, a metadata-driven connector is more flexible and easier to maintain than one that is not metadata-driven. For information on how to design a metadata-driven connector, see the Connector Development Guide for C++ and Connector Development Guide for Java.

Within a business object definition, you can provide application-specific information at one of three levels:

Application-specific information is stored in a field in the business object definition called the AppSpecificInfo property. The value of the AppSpecificInfo property is a text string that can include any information about the business object or application. Figure 2 illustrates the major elements of a business object definition and the application-specific property for each element.

Note:
The string can contain bidirectional characters, if required for your locale.

Figure 2. Business object definition showing the application-specific property for each element

The figure shows a business object. Each area, the header, verb and attributes each contains application specific information.

This section covers the following topics:

Application-specific information for a business object

The application-specific information at the business object level provides information that the connector or data handler uses to process the data. Business object-level application-specific information is used whenever processing instructions are relevant for an entire business object hierarchy. For example, the object-level application-specific information might do one or more of the following:

Figure 3 illustrates application-specific information that identifies a form or table name in an application. The connector can get the table or form name from the AppSpecificInfo property and use it in an API call to retrieve data from the application.

Figure 3. Application-specific information for a business object

The figure shows the business object designer dialog displaying a business object. The title bar of the business object dialog displays the name of the business object. In the dialog are general and attributes tabs. The figure shows a portion of the general page that shows the name of the form in the application.

Application-specific information for an attribute

Each attribute of a business object definition can have application-specific information associated with it. Attribute-level application-specific information is used whenever processing instructions are relevant for the single attribute. For example, this information can specify a field on a form, a column in a table, or whatever the connector needs to locate or work with the attribute. If certain attributes of a business object are located on a particular subform in the application, the AppSpecificInfo property is a good candidate for a place to encode this information.

Figure 4 illustrates the AppSpecificInfo property for an attribute. In this example, the application-specific information specifies the name of a subform and field.

Figure 4. Application-specific information for an attribute.

The figure shows the business object designer displaying the attributes page of a business object. To tfigure highlights both the Customerid attribute on the page and the application specific information for that attribute which is the name of a subform and field in the application.

Figure 5 illustrates the relationship of form, subform, and field name as provided in the object-level and attribute-level application-specific information. This example assumes that a billing application is based on forms, and that the way to interact with invoices in this application is through the Invoice form, which is a subform of a main CustAccount form. The Invoice subform has the following fields: CustName, CustAddr, InvNum, DollarAmount, and Terms.

Figure 5. Using business object definition application-specific information


Figure 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.

Application-specific information for a verb

Each verb definition can include application-specific information that provides the connector or data handler with instructions on how to process the business object when that verb is active.

Note:
The business object handler, which is the part of a connector that handles requests sent from the integration broker to the connector, can be designed to use the application-specific information in the verbs of their application-specific business object definitions. Such business object handlers are called metadata-driven business object handlers. Because the processing information is configurable, rather than hard-coded, a metadata-driven business object handler is more flexible and easier to maintain than one that is not metadata-driven. For information on how to design a metadata-driven business object handler, see the Connector Development Guide for C++ and Connector Development Guide for Java.

For example, if the connector is using an API to handle updates to the application database, the application-specific information can provide the connector with information to run an API.

The verb application-specific information can also specify the name of a function to call in the application to handle the processing of a business object.

Business object instances

While the business object definition represents the template for a collection of data, a business object instance (often just called a "business object") is the run-time entity that contains the actual data. The business object is what is passed between components of the business integration system.

The business object contains the following information:

Figure 6 shows the Customer business object definition and a corresponding business object instance for this definition.

Figure 6. Business object definition and sample business object.

The figure shows an instance of a business object with the following values: CustomerId is 8776, CustomerName is Trievers Inc, CustomerStatus is Active, CustomerRegion is NE, ObjectEventID is 1027111552889_1 and the verbe is Create.

Copyright IBM Corp. 1997, 2004