Business objects for eMatrix

Valid application-specific business objects in the WebSphere Business Integration system model the essential components of the eMatrix system. The following eMatrix components can be modelled as WebSphere Business Integration business objects:

A WBIA business object definition specifies the components it represents in the ematrix_class value of its application-specific information (ASI), defined at the business object level. The three valid ematrix_class values, corresponding to the eMatrix components listed above, are discussed in the next section.

Business object types

eMatrix business object types are represented in the WBIA system by business object definitions with business object-level ASI that specify an ematrix_class with the value of business_object. The ASI must also contain an object_type parameter that specifies the name of the eMatrix business object type that this particular WBIA business object will model. For example:

ematrix_class=business_object; object_type=<name of eMatrix business object type>

The eMatrix business object types, and hence their business object definitions in the WBIA system, contain two sets of fields. They are:

The eMatrix properties available to you through the business object are listed in Table 6,.

Note:
Use an attribute of type "String" to represent a date. For supported date formats, refer to the eMatrix documentation.


Table 6. eMatrix business object properties

Property Description Expected attribute type
object_id Unique ID for eMatrix object String
Name Name of eMatrix object String
Revision eMatrix object revision number String
Policy The governing policy for the eMatrix object String
Owner The owner of the eMatrix object String
State The current state of the eMatrix object String
Vault The eMatrix vault that contains this object String
to_relationship One or more "to" eMatrix relationships that this
object supports
Child object modeling an
eMatrix relationship

Cardinality = 1...n

from_relationship One or more "from" eMatrix relationships that this
object supports
Child object modeling an
eMatrix relationship

Cardinality = 1...n

eMatrix lets the user identify objects either through an object ID or through a combination of type, name and revision. Therefore, all WBIA business objects must contain either:

These will be key values in the business object definition. For illustrations, refer to "Business object definition examples".

To specify that a particular WBIA business object attribute should be mapped to an eMatrix attribute:

  1. Define the attribute as a simple type, such as a string or integer
  2. Include
     attr=<eMatrix attribute name>
    

    in the business object definition attribute-level ASI.

Business object definition examples

Table 7 shows a business object definition that includes two user-defined eMatrix attributes, PartNumber and Size, and maps to the ASI property object_id.


Table 7. Business object definition #1

Attribute name Type Default value Application-specific information IsKey?
ObjectId String
prop=object_id Yes
State String
prop=state No
PartNumber String ASX31 attr=PartNumber No
Size Integer 15 attr=Size No

Table 8shows the same business object definition, but it now maps to the eMatrix properties, name and revision.


Table 8. Business object definition #2

Attribute name Type Default value Application-specific information IsKey?
Name String AllSeasonX31 prop=name Yes
Revision String 1 prop=revision Yes
State String
prop=state No
PartNumber String ASX31 attr=PartNumber No
Size Integer 15 attr=Size No

Relationships

eMatrix relationships are represented in the WBIA system by business object definitions with business object-level ASI that specify an ematrix_class with the value of relationship. The ASI must also contain an object_type parameter that specifies the name of the eMatrix relationship that this particular WBIA business object will model. For example:

ematrix_class=relationship; object_type=<name of eMatrix relationship type>

Like the business object definitions described above, the business object definitions that reflect eMatrix relationships may contain a combination of eMatrix properties (fixed) and attributes (user-defined).

Table 9 lists the relationship properties.


Table 9. eMatrix relationship object properties

Property Description Expected attribute type
relationship_id Unique ID for eMatrix relationship String
to_object eMatrix object to which this relationship extends
Child object modeling an
eMatrix business object

Cardinality = 1

from_object eMatrix object from which this relationship extends
Child object modeling an
eMatrix business object

Cardinality = 1

All relationship business object definitions must contain:

Note:
A relationship object may contain many instances of the to_object or from_object attribute, as a single relationship can support many object types. However, if the relationship is defined as a to_relationship in the parent business object, then the relationship object may contain only to_object identifiers. Likewise, if a from_relationship is defined in the parent business object, the relationship object may contain only from_object identifiers.

The relationship definition takes this form:

--Business_Object_A
      | -- to_relationship = Relationship_A_to_B
                      | -- to_object = Business_Object_B

or

--Business_Object_A
      | -- from_relationship = Relationship_A_to_B
                      | -- from_object = Business_Object_B

See "Relationship examples" for an illustration.

Defining relationships

The adapter can only recognize relationships between different objects if you define these relationships explicitly in the business object definition. When business objects are related, the adapter requires a relationship object to connect the business objects. If business objects are not connected by a relationship object, they are assumed to be unrelated.

For example, if you define this business object:

--Business_Object_A
      | -- to_relationship = Relationship_A_to_B
                      | -- to_object = Business_Object_B

and then perform a Retrieve on the parent business object (object A), the adapter will retrieve A and only those objects of type B that are related to A through the A-to-B relationship.

However, if you define this business object:

--Business_Object_D
      | -- Business_Object_E

and then perform a Retrieve on the parent business object (object D), the adapter will retrieve D and objects of type E regardless of whether they are related to D. In this case, business object E must have attributes containing valid search criteria, or you will get an error.

You can combine related and unrelated business objects in a definition, depending on the business scenario and relationships. For example, you can define this business object:

--Business_Object_A
      | -- to_relationship = Relationship_A_to_B
                      | -- to_object = Business_Object_B
                    | -- Business_Object_D

Here, business objects A and B are related to each other, but business object D is not related to either of them.

Relationship examples

The two examples shown below are related in the same way, though the relationship is defined differently in each business object definition.

--Car
      | -- to_relationship = CarToTireRelationship
                      | -- to_object = Tire

--Tire 
      | -- from_relationship = CarToTireRelationship
            | -- from_object = Car

Command objects

eMatrix commands are represented in the WBIA system by business object definitions with business object-level ASI that specify an ematrix_class with the value of command. For example:

ematrix_class=command

Command business object definitions are structured as follows:

Figure 3. Structure of command business object definitions


The command object has two attributes: one representing the command's input and the other representing the command's output. The input attribute is required and must be an object. The output attribute is optional and may be either a String or an object. Both the input and output attributes are identified by the corresponding attribute level ASI; either type=input or type=output.

The input object contains the command string that will be executed as well as several variables whose values will be interpolated into the command. The command string is stored in the input object's business object level ASI and is identified by the command= prefix. The following screenshots show an input object, including the command and input variables.

Figure 4. Input object commands


Notice that this screenshot includes the expand bus command. The attributes of the input object represent the variables which will be interpolated into this command string before being sent to the MQL interpreter (shown in Figure 5).

Figure 5. Input object attributes


The output attribute may be either a string or a business object. When the output attribute of the business object is a string, it will contain the text returned by the command. Whe the output attribute is an object, the results of the command will be passed through a data handler and then translated into a business object hierarchy. In this case, the output attribute of the command object must contain information that will invoke the data handler. The following fields may be added to the ASI of the output attribute:

Table 10. Asi output attributes

ASI output attribute Description
dh_mo Specifies the data handler meta-object name
dh_mimetype Specifies the mime-type content that is
passed to the data handler
dh_classname Specifies the fully qualified data handler
Java class name

The following screenshots show an example of an output attribute and its corresponding output object. These screenshots are not related to the input object screenshots found above.

Figure 6. Command object


Note:
The output attribute is identified in Figure 6 by the attribute level ASI type=output. Also, the ASI contains additional information to identify and invoke the XML data handler.
Note:
The input and output objects shown above are not child objects of the command object.

Figure 7. A business object hierarchy assigned to capture the command output


Note:
The business hierarchy shown above represents a imple XML DTD that wil encapsulate the output of an MQL command.

Note:
The only verb supported for command business objects is Create.

Business object verbs

Every business object contains a verb, which describes how the data in the application-specific business object should be handled by the eMatrix adapter.

The adapter identifies a business object using either its unique objectId or a combination of type, name and revision. These are all user-defined properties. For details, see "Business object types".

The adapter interprets the same verb differently for different classes of eMatrix objects. It checks the value of ematrix_class in the business object definition before processing the business object.

Table 11 lists the business object verbs available to the adapter for eMatrix and describes the actions that the adapter performs with each one.

Table 11. Business object verbs and actions

Verb eMatrix class Action
Create Business objects Creates one or more new business objects in eMatrix, along with
any relationships. Uses name, type and revision specified in the request.
Uses vault and policy values if specified, otherwise uses the default.


Creates any specified child objects and relationships.


Relationships Cannot create relationships independently, because all child objects must
have the same verb as the parent object. To create a new relationship
between objects with an already existing relationship, use Update.

Commands Executes the command in the eMatrix system and returns any results to
the request object.
Update Business objects
and relationships
Updates one or more specified business objects and their relationships.
For an example, see below.
Delete Business objects Deletes the specified business object and automatically deletes any
relationships bound to it. All deletes are physical deletes.

Relationships Deletes the relationship denoted by the relationship ID. Disconnects the
business objects bound to the relationship; does not delete them.
Retrieve Business objects
and relationships
Retrieves the entire business object from eMatrix, including relationships
and any eMatrix business objects that correspond to attributes in the
WBIA business object.


The business object returned to the integration broker should accurately
reflect the structure in the business object definition.

RetrieveBy
Content
Business objects
and relationships
Retrieves the entire business object from eMatrix, using key and/or
non-key information. If it finds more than one match, it returns the
first one and sends a message saying "Multiple hits".
Exists Business objects
and relationships
Verifies whether the top-level business object exists in eMatrix.

The verb is contained within the application-specific business object. Its value is set by the broker that creates the business object. The adapter will perform different operations on the eMatrix application, depending on the verb and the contents of the business object.

Once the adapter has processed the business object, and invoked the requisite actions in the eMatrix system, it returns a status code. It may also return a new business object containing information about the state of the application to the integration broker.

Attribute properties

The WBIA business object definitions have various properties that you can set on their business object attributes. The tables below list the attributes and their values.

Table 12 lists simple attributes.

Table 12. Simple attributes

Attribute Property
Name Specifies the business object field name.
Type Specifies the business object field type.
MaxLength 255 by default.
IsKey Each business object must have at least one key attribute, which you specify
by setting the key property to true for an attribute.
IsForeighKey Not used.
Is Required Not used.
AppSpecInfo Stores the application-specific information (ASI), such as attr=<attribute name>.
DefaultValue Specifies a default value that the connector uses for a simple attribute in
the inbound business object if the attribute is not set and is
a required attribute.

Application-specific information

Application-specific information (ASI) provides the connector with application-dependent instructions on how to process business objects. If you extend or modify a business object definition, you must make sure that the application-specific information in the definition matches the syntax that the connector expects.

Application-specific information can be specified on the business object, on each business object attribute, and for each verb. For simple attributes, the ASI specifies either the type of the eMatrix attribute or the name of the eMatrix property (such as name, revision, or vault). For child business objects, the ASI specifies the direction of the relationship (for object hierarchies representing eMatrix business objects and relationships).

Copyright IBM Corp. 1997, 2004