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.
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 6,.
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:
attr=<eMatrix attribute name>
in the business object definition attribute-level ASI.
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 |
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:
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.
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.
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
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:
type=input
which defines it to the adapter as the input
command=<command string to run in eMatrix>
You can use the command string to refer to any attribute in the child object by enclosing the attribute name in percent signs (% <name>%). See the example below.
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.
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
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 10 lists the business object verbs available to the adapter for eMatrix and describes the actions that the adapter performs with each one.
Table 10. 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.
|
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.
|
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.
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 11 lists 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 (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).