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.
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,.
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:
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 7. A business object hierarchy assigned to capture the command output
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.
|
| 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 12 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).