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 validematrix_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 anematrix_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 11,.

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


Table 11. 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 12 shows a business object definition that includes two user-defined eMatrix attributes, PartNumber and Size, and maps to the ASI property object_id.


Table 12. 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 13shows the same business object definition, but it now maps to the eMatrix properties, name and revision.


Table 13. 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 14 lists the relationship properties.


Table 14. 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_objectorfrom_objectattribute, 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:

-- Command_object
        | -- Input_Object
        | -- Output_Object

The input and output objects are child objects of the top-level command. The input object definition, which encapsulates the command string and its parameters, is required. However, the output object definition, which encapsulates the output returned by the command, is optional.

The input child object must contain the following attributes:

If a command returns results, the object must have an output attribute defined to receive the data. The output attribute may be a string or a child object. If you use a child object as an output attribute, you must specify a data handler to enable the adapter to map the incoming data. To specify a data handler, you can use one of these attribute pairs:

See Command examples for an illustration.

A command object hierarchy cannot contain or be contained in a hierarchy containing a collection of eMatrix business objects and relationships. It must stand on its own.

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

Command examples

Here is an example of a command object definition.

--Command_Object
      | -- Input_Object (ASI = 'type=input;command=approve %ObjectId% signature
 %signature% comment %Comment%'
                      | -- ObjectId = 1000
            | -- Signature = Loan Approved
            | -- Comment = Approved up to $20,000

The actual command processed in eMatrix, after the adapter had made its substitutions, would be:

approve 1000 signature Loan Approved comment Approve up to $20,000

Here is an example of a command object that executes a program that returns XML.

--Command_Object
      | -- Input_Object (ASI = 'type=input;command=exec program BuildReport
 %ObjectIde%'
                      | -- ObjectId = 1000
      | -- Output_Object (ASI = 
'type=output;dh_mo=Default_DataHandler_MO:dh_mimetype=text/xml'
                      | -- AttrA
            | -- AttrB

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 15 lists the business object verbs available to the adapter for eMatrix and describes the actions that the adapter performs with each one.

Table 15. 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 16 lists simple attributes.

Table 16. 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, 2003