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.
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).
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.
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; it can contain alphanumeric characters and underscores but cannot contain spaces, punctuation, or special characters.
Notes:
The Type property defines the data type of the attribute:
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.
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.
When you specify as key a complex attribute:
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 creates the relationship only if the record for the entity exists.
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.
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.
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.
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.
Notes:
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.
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.
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 1 lists the basic verbs that a business object definition can
support.
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 1, a business object definition might also need to support one or more of the following verbs:
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.
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.
Figure 2. Business object definition showing the application-specific property for each element
This section covers the following topics:
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
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
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.
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.
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 execute 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.