Meta-object configuration

The business object itself consists of a top-level business object that holds one or more child objects representing the data structure. This means each business object holds some child objects that contain metadata and one or more child objects that contain the actual business content.

The top-level business object is a wrapper for all objects that will be exchanged. As a wrapper, the top-level business object holds no business data, but rather provides the application-specific text and name-value pairs needed to build the objects required to initiate and complete the exchange. The name-value pairs indicate child attributes that specify metadata needed to create the requested or required business objects.

Figure 8 shows the top-level business object and child object relationships when:

Figure 8. Top-level business object and child (business and meta-objects) in poll for events scenario

Figure 9 shows the top-level business object and child object relationships when:

Figure 9. Top-level business object and child meta-objects in poll for events scenario

Figure 10 shows the top-level business object and child object relationships when:

Figure 10. Top-level business object and child (business and meta) objects in request processing scenario

Figure 11 shows the top-level business object and child object relationships when:

Figure 11. Top-level business object and child (business and meta-) objects in request processing scenario

The WebSphere MQ Workflow process can have different input and output data structures, but transactions involving a collaboration and a connector can involve only one object type. To get around this limitation, some top-level business objects are constructed that have, as children, a request object and one or more response objects. Specifically, the name of the data structure appended to the <boprefix> configuration property determines which top-level business object is created. The first (non metadata related) child object in this top-level business object is populated with the data structure.

To distinguish child meta-objects from business-content child objects, the application-specific information for the top-level business object must include a tag as follows:

cw_mo_tag=child meta-object_attribute_name

Note:
Multiple metadata tags should be delimited by a semi-colon. White space surrounding delimiters are ignored. (For example: cw_mo_foo = bar is equivalent to cw_mo_foo=bar)

where tag = one of the following:

All application-specific information beginning with cw_mo_ is reserved for configuration or dynamic metadata. Accordingly, when a connector agent receives a business object, it can immediately determine if any runtime metadata has been included for the business object by simply checking the application-specific information of the business object itself. Data handlers, too, check the application-specific information at the business object level to determine which child objects to include or exclude in the serialization or de-serialization process.

For example, consider a top-level business object named WfRequest_MyCustomer that needs a configuration meta-object. You can specify an object configuration attribute of type MyConfig. To allow the connector to recognize the meta-object and keep the data handler from incorporating "MyConfig" when serializing the parent object, you add application-specific information to the WRequest_MyCustomer object in the form of the tag cw_mo_wfptcfg=MyConfig.

When constructing a request or response for WebSphere MQ Workflow, the connector uses templates to construct business objects.

MO_MQWorkflow_ProcessTemplateConfig

To provide information on the WebSphere MQ Workflow process to be created and executed, the connector requires that a meta-object be included in the top-level business object. This meta-object includes information regarding the process template to use, whether a response is required, whether WebSphere MQ Workflow must wait until the process is compete before returning a result, and more. By storing this information in a meta-object, the connector can dynamically configure application-specific information for the requested WebSphere MQ Workflow process. This meta-object (or its equivalent) is required for all collaboration requests.

The connector reads the application-specific information of the top-level business object and looks for a name value pair:

cw_mo_wfptcfg=xxx

where xxx is the name of the child attribute that specifies the metadata. Table 8 shows the attribute names and descriptions.

Table 8. MO_MQWorkflow_ProcessTemplateConfig meta-object attributes
Attribute name Description Accepted values
ProcessTemplateName(Required) Name of WebSphere MQ Workflow template to execute. Default = none Any
ProcessInstanceName Name of WebSphere MQ Workflow instance to execute. Does not apply in asynchronous execution mode.

Default = If left blank, a new instance of the process template is created.

Any
KeepName Flag indicating whether a process should be discarded after use.

Default = false

true or false
UserID Identifies a user with authorization to execute the process. This is the same as the connector-specific property, ApplicationUserID. For important restrictions on this attribute, see ApplicationUserID.

Default = Value of connector configuration property ApplicationUserID

Any
ResponseTimeout Amount of time (in ms) to wait for a response from WebSphere MQ Workflow. A positive value requires the connector to wait for a response. A negative value causes the connector to return successfully once a request is issued to the WebSphere MQ Workflow input queue.

Default = -1

Integer
TimeoutFatal If a response is not received by WebSphere MQ Workflow, the connector returns BON_APPRESPONSETIMEOUT to InterChange Server and terminates the connector agent.

Default = false (does not apply if ResponseTimeout is less than 0)

true or false
ExecutionMode Determines whether a process executes asynchronously or synchronously in relation to the collaboration. When this mode is Asynchronous, a new instance of the process template is created and executed. A PID is returned to the collaboration for tracking purposes. When this mode is Synchronous, an instance (either existing or new) of a process template is executed. The resulting business object is returned to the collaboration once the workflow process is completed.

Default = Synchronous

Asynchrounous or Synchronous

MO_MQWorkflow_ContainerInfo

Activity invoking (ActivityImplInvoke)messages issued by WebSphere MQ Workflow optionally can hold container information in addition to a business object. This container information can be mapped to the child meta-object MO_MQWorkflow_ContainerInfo (if defined) and published to subscribing collaborations. It includes information provided by WebSphere MQ Workflow regarding the conditions and environments in which the process originated.

Note:
The MO_MQWorkflow_ContainerInfo metadata is for informational purposes only. A collaboration may choose to ignore it or take different actions based on the process model or role of the user initiating the requested process.

The connector reads the application-specific information of the top-level business object and looks for the name-value pair:

cw_mo_wfcontainer=XXX

where XXX is the name of the child attribute to populate with the top-level business object information. This information has no value to the connector and is not used for processing business objects. Passing this information to the connector as part of a business object has no effect.

Here is a the MO_MQWorkflow_ContainerInfo definition.

[ReposCopy]

      Version = 3.1.0
  [End]
  [BusinessObjectDefinition]
  Name = MO_MQWorkflow_ProcessInfo
  Version = 1.0.0


    [Attribute]
    Name = Role
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = true
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = Organization
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ProcessAdministrator
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = Duration
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ObjectEventId
    Type = String
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]

    [Verb]
    Name = Create
    [End]

    [Verb]
    Name = Delete
    [End]

    [Verb]
    Name = Retrieve
    [End]

    [Verb]
    Name = Update
    [End]
[End]
[BusinessObjectDefinition]
Name = MO_MQWorkflow_ActivityInfo
Version = 1.0.0

    [Attribute]
    Name = Priority
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = true
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = MembersOfRoles
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = CoordinatorOfRole
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = Organization
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = OrganizationType
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = LowerLevel
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = UpperLevel
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = People
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = PersonToNotify
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = Duration
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = Duration2
    Type = String
    Cardinality = 1
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ObjectEventId
    Type = String
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]

    [Verb]
    Name = Create
    [End]

    [Verb]
    Name = Delete
    [End]

    [Verb]
    Name = Retrieve
    [End]

    [Verb]
    Name = Update
    [End]
[End]
[BusinessObjectDefinition]
Name = MO_MQWorkflow_ContainerInfo
Version = 1.0.0

    [Attribute]
    Name = PROCESS_INFO
    Type = MO_MQWorkflow_ProcessInfo
    ContainedObjectVersion = 1.0.0
    Relationship = Containment
    Cardinality = 1
    MaxLength = 1
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ACTIVITY_INFO
    Type = MO_MQWorkflow_ActivityInfo
    ContainedObjectVersion = 1.0.0
    Relationship = Containment
    Cardinality = 1
    MaxLength = 1
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ACTIVITY
    Type = String
    Cardinality = 1
    MaxLength = 1
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = PROCESS
    Type = String
    Cardinality = 1
    MaxLength = 1
    IsKey = true
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = PROCESS_MODEL
    Type = String
    Cardinality = 1
    MaxLength = 1
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]
    [Attribute]
    Name = ObjectEventId
    Type = String
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = false
    IsRequiredServerBound = false
    [End]

    [Verb]
    Name = Create
    [End]

    [Verb]
    Name = Delete
    [End]

    [Verb]
    Name = Retrieve
    [End]

    [Verb]
    Name = Update
    [End]
[End]

MO_MQWorkflow_ProcessInstance

Optionally, a process instance ID (PID) is returned by WebSphere MQ Workflow in response to a process execution. Upon successful creation or execution of a workflow process, the connector populates this object with details of the process. If the process is executing in parallel to the initiating collaboration, the collaboration can use the PID to control the process instance (if the process was executed asynchronously to the collaboration).

The connector reads the application-specific information of the parent business object and looks for a name-value pair:

cw_mo_wfpid

=XXX

where XXX is the name of the child attribute that should contain the process instance metadata. The object must conform to the requirements set forth by the XML data handler. Furthermore, the names of the attributes in the child object have semantic value to the connector. The application-specific information for the object must include "ProcessInstance".

It is highly recommended that all custom objects be derived from this sample.

Table 9. MO_MQWorkflow_ProcessTemplateInstance meta-object attributes
Attribute name Description Accepted values
ProcInstID Primary key identifying the process instance Any
ProcessInstName See the WebSphere MQ Workflow programming guide.
ProcInstParentName See the WebSphere MQ Workflow programming guide.
ProcInstTopLevelName See the WebSphere MQ Workflow programming guide. Any
ProcInstDescription See the WebSphere MQ Workflow programming guide. Integer
ProcInstState State of Process SuspendedResumedTerminated
LastStateChangeTime See the WebSphere MQ Workflow programming guide. Asynchronous or Synchronous
LastModificationTime See the WebSphere MQ Workflow programming guide.
ProcTempID See the WebSphere MQ Workflow programming guide.
ProcTempIName See the WebSphere MQ Workflow programming guide.
Icon See the WebSphere MQ Workflow programming guide.
Category See the WebSphere MQ Workflow programming guide.

MO_MQWorkflow_ActivityRequest

When an WebSphere MQ Workflow process instance issues an activity-invoking (ActivityImplInvoke) message and the following conditions are met:

The connector extracts the activity information from the ActivityImplInvoke message. This activity information is mapped to the child meta-object MO_MQWorkflow_ActivityRequest and then published to subscribing collaborations.

The connector reads the application-specific information of the top-level business object and looks for the following name-value pair:

cw_mo_wfactivityrequest

=XXX

where XXX is the name of the child attribute to populate with the top-level business object information. This information is neither of value to the connector nor used for processing business objects. Table 10 shows the attribute names and descriptions.

Table 10. MO_MQWorkflow_ActivityRequest attributes
Attribute Name Description Accepted Values
ActImplCorrelID
The ID that correlates the
ActivityImplInvoke
message issued by the process instance with the
ActivityImplInvokeResponse
message. The collaboration uses
ActImplCorrelID
to send the response to the connector
Any
Starter
The user ID that initiated the process instance Any
ProcTemplID
The ID of the process template. Any
ProgramName
The program name which is called by the process instance Any
ResponseRequired
Identifies whether the process (or instance) expects the ActivityImplInvokeResponse message Yes or No or IfError
ExternalProcessContext
The process context of the process instance Any

MO_MQWorkflow_ActivityResponse

To correlate a response with a request, the connector requires that the top-level business object include a meta-object with appropriate information. This meta-object includes information regarding the ActImplCorrelID of the associated ActivityImplInvoke message, the user ID (Starter) associated with the process instance, and the return code linked to the process instance. This meta-object is required when a collaboration associates an ActivityImplInvokeResponse with the ActivityImplInvoke message.

The connector reads the application-specific information of the top-level business object and looks for the following name value pair:

cw_mo_wfactivityresponse

=XXX

where XXX is the name of the child attribute that specifies the metadata. Table 11 shows the attribute names and descriptions

Table 11. MO_MQWorkflow_ActivityResponse Attributes
Attribute Name Description Accepted Values
ActImplCorrelID
ID by which the process instance correlates the response with the request invoked by the associated
ActivityImplInvoke
message.
Any
Starter
The user ID that initiated the process instance associated with the ActivityImplInvoke message Any
ReturnCode
The return code issued to the process instance Integer

Application-Specific Information

The application-specific information at the parent business object level is structured in name-value pair format, separated by semicolons. White space is ignored. For example:

cw_mo_wfptcfg=CUST_Config;cw_mo_pid=CUST_IN_Nieman

Copyright IBM Corporation 2003, 2005. All Rights Reserved.