Verb processing

The connector processes business objects passed to it by a collaboration based on the verb for each business object. The connector uses business object handlers and the doForVerb() method to process the business objects that the connector supports. The connector supports the following business object verbs:

Note:
Business objects with Create, Update, and Delete verbs can be issued either asynchronously or synchronously. The default mode is asynchronous. The connector does not support asynchronous delivery for business objects with the Retrieve, Exists, or Retrieve by Content verbs. Accordingly, for Retrieve, Exists, or Retrieve by Content verbs, the default mode is synchronous.

Create, update, and delete

Processing of business objects with create, update and delete verbs depends on whether the objects are issued asynchronously or synchronously.

Asynchronous delivery

This is the default delivery mode for business objects with Create, Update, and Delete verbs. A message is created from the business object using a data handler and then written to the output queue. If the message is delivered, the connector returns SUCCESS, else FAIL.

Note:
The connector has no way of verifying whether the message is received or if action has been taken.

Synchronous delivery

If a ReplyToQueue has been defined in the connector-specific properties and a responseTimeout exists in the conversion properties for the business object, the connector issues a request in synchronous mode. The connector then waits for a response to verify that appropriate action was taken by the receiving application.

For WebSphere MQ, the connector initially issues a message with a header as shown in the table below.

Field Description Value
Format Format name Output format as defined in the conversion properties and truncated to 8 characters to meet IBM requirements (example: MQSTR)
MessageType Message Type MQMT_DATAGRAM*if no response is expected from the receiving application.
MQMT_REQUEST* if a response is expected
Report Options for report message requested. When a response message is expected, this field is populated as follows:MQRO_PAN* to indicate that a positive-action report is required if processing is successful.MQRO_NAN* to indicate that a negative-action report is required if processing fails.MQRO_COPY_MSG_ID_TO_CORREL_ID* to indicate that the correlation ID of the report generated should equal the message ID of the request originally issued.
ReplyToQueue Name of reply queue When a response message is expected this field is populated with the value of connector property ReplyToQueue.
Persistence Message persistence MQPER_PERSISTENT*
Expiry Message lifetime MQEI_UNLIMITED*

* Indicates constant defined by IBM.

The message header described in the table above is followed by the message body. The message body is a business object that has been serialized using the data handler.

The Report field is set to indicate that both positive and negative action reports are expected from the receiving application. The thread that issued the message waits for a response message that indicates whether the receiving application was able to process the request.

When an application receives a synchronous request from the connector, it processes the business object and issues a report message as described in the tables below.

Field Description Value
Format Format name Input format of busObj as defined in the conversion properties.
MessageType Message Type MQMT_REPORT*

*Indicates constant defined by IBM.

Verb Feedback field Message body
Create, Update, or Delete SUCCESS VALCHANGE (Optional) A serialized business object reflecting changes.

VALDUPES FAIL (Optional) An error message.


WebSphere MQ feedback code Equivalent response*
MQFB_NONE (this is the default if no feedback code is specified) VALCHANGE
MQFB_PAN orMQFB_APPL_FIRST SUCCESS
MQFB_NAN orMQFB_APPL_FIRST + 1 FAIL
MQFB_APPL_FIRST + 2 VALCHANGE
MQFB_APPL_FIRST + 3 VALDUPES
MQFB_APPL_FIRST + 4 MULTIPLE_HITS
MQFB_APPL_FIRST + 5 FAIL_RETRIEVE_BY_CONTENT
MQFB_APPL_FIRST + 6 BO_DOES_NOT_EXIST
MQFB_APPL_FIRST + 7 UNABLE_TO_LOGIN
MQFB_APPL_FIRST + 8 APP_RESPONSE_TIMEOUT (results in immediate termination of connector agent)

*See the Connector Development Guide for Java for details.

If the business object can be processed, the application creates a report message with the feedback field set to MQFB_PAN (or a specific WebSphere business integration system value). Optionally the application populates the message body with a serialized business object containing any changes. If the business object cannot be processed, the application creates a report message with the feedback field set to MQFB_NAN (or a specific WebSphere business integration system value) and then optionally includes an error message in the message body. In either case, the application sets the correlationID field of the message to the messageID of the connector message and issues it to the queue specified by the replyTo field.

Upon retrieval of a response message, the connector by default matches the correlationID of the response to the messageID of a request message. The connector then notifies the thread that issued the request. Depending on the feedback field of the response, the connector either expects a business object or an error message in the message body. If the feedback code is MQFB_NONE (the default value if no feedback code is specified), the connector by default considers the return code to be VALCHANGE. The connector then passes the response message to the data handler and updates the business object. If a business object was expected but the message body is not populated, the connector simply returns the same business object that was originally issued by InterChange Server for the Request operation. If an error message was expected but the message body is not populated, a generic error message will be returned to InterChange Server along with the response code. However, you can also use a message selector to identify, filter and otherwise control how the adapter identifies the response message for a given request. This message selector capability is a JMS feature. It applies to synchronous request processing only and is described below.

Filtering response messages using a message selector

Upon receiving a business object for synchronous request processing, the connector checks for the presence of a response_selector string in the application-specific information of the verb. If the response_selector is undefined, the connector identifies response messages using the correlation ID as described above.

If response_selector is defined, the connector expects a name-value pair with the following syntax:

response_selector=JMSCorrelationID LIKE 'selectorstring'

The message selectorstring must uniquely identify a response and its values be enclosed in single quotes as shown in the example below:

response_selector=JMSCorrelationID LIKE 'Oshkosh'

In the above example, after issuing the request message, the adapter would monitor the ReplyToQueue for a response message with a correlationID equal to "Oshkosh." The adapter would retrieve the first message that matches this message selector and then dispatch it as the response.

Optionally, the adapter performs run-time substitutions enabling you to generate unique message selectors for each request. Instead of a message selector, you specify a placeholder in the form of an integer surrounded by curly braces, for example: '{1}'. You then follow with a colon and a list of comma-separated attributes to use for the substitution. The integer in the placeholder acts as an index to the attribute to use for the substitution. For example, the following message selector:

response_selector=JMSCorrelationID LIKE '{1}': MyDynamicMO.CorrelationID

would inform the adapter to replace {1} with the value of the first attribute following the selector (in this case the attribute named CorrelationId of the child-object named MyDynamicMO. If attribute CorrelationID had a value of 123ABC, the adapter would generate and use a message selector created with the following criteria:

JMSCorrelation LIKE '123ABC'

to identify the response message.

You can also specify multiple substitutions such as the following:

response_selector=PrimaryId LIKE '{1}' AND AddressId LIKE '{2}' : PrimaryId, Address[4].AddressId

In this example, the adapter would substitute {1} with the value of attribute PrimaryId from the top-level business object and {2} with the value of AddressId from the 5th position of child container object Address. With this approach, you can reference any attribute in the business object and meta-object in the response message selector. For more information on how deep retrieval is performed using Address[4].AddressId, see JCDK API manual (getAttribute method)

An error is reported at run-time when any of the following occurs:

For example, if you include the literal value '{' or '}' in the message selector, you can use '{{' or "{}" respectively. You can also place these characters in the attribute value, in which case the first "{" is not needed. Consider the following example using the escape character: response_selector=JMSCorrelation LIKE '{1}' and CompanyName='A{{P': MyDynamicMO.CorrelationID

The connector would resolve this message selector as follows:

JMSCorrelationID LIKE '123ABC' and CompanyName='A{P'

When the connector encounters special characters such as '{', '}', ':' or ';' in attribute values, they are inserted directly into the query string. This allows you to include special characters in a query string that also serve as application-specific information delimiters.

The next example illustrates how a literal string substitution is extracted from the attribute value:

response_selector=JMSCorrelation LIKE '{1}' and CompanyName='A{{P': MyDynamicMO.CorrelationID

If MyDynamicMO.CorrelationID contained the value {A:B}C;D, the connector would resolve the message selector as follows: JMSCorrelationID LIKE '{A:B}C;D' and CompanyName='A{P'

For more information on the response selector code, see JMS 1.0.1 specifications.

Bidirectional Support

For the Adapter for WebSphere MQ, support is provided for bidirectional transformation of business object content. Bidirectional support is also provided when the connector exchanges metadata with an external WebSphere MQ application and uses a synchronous delivery filtering mechanism to locate a response message in the ReplyToQueue. Under these circumstances, bidirectional transformation is applied so that the Windows standard format is transformed to the bidirectional format of the WebSphere MQ application. This is done using the attributes set for the BiDi.Application standard configuration property.

When the response_selector is specified with the following syntax,

response_selector=JMSCorrelationID LIKE 'selectorstring'

and when bidirectional characters appear in the 'selectorstring', then the adapter can be configured to transform the 'selectorstring' to the bidirectional format of the external application, which is the application responsible for sending response messages for the request created by the adapter. This would be necessary when the bidirectional format of the external application is different from the default Windows format of the application-specific information as defined originally in the Connector Designer application. In such cases, the BiDi.Application standard configuration property needs to be configured with the bidirectional format of the external application; then the adapter will transform the message selector string before it is used for filtering response messages.

Creating custom feedback codes

You can extend the WebSphere MQ feedback codes to override default interpretations by specifying the connector property FeedbackCodeMappingMO. This property allows you to create a meta-object in which all WebSphere business integration system-specific return status values are mapped to the WebSphere MQ feedback codes. The return status assigned (using the meta-object) to a feedback code is passed to InterChange Server. For more information, see "FeedbackCodeMappingMO".

Retrieve, exists and retrieve by content

Business objects with the Retrieve, Exists, and Retrieve By Content verbs support synchronous delivery only. The connector processes business objects with these verbs as it does for the synchronous delivery defined for create, update and delete. However, when using Retrieve, Exists, and Retrieve By Content verbs, the responseTimeout and replyToQueue are required. Furthermore, for Retrieve By Content and Retrieve verbs, the message body must be populated with a serialized business object to complete the transaction.

The table below shows the response messages for these verbs.

Verb Feedback field Message body
Retrieve or RetrieveByContent FAIL FAIL_RETRIEVE_BY_CONTENT (Optional) An error message.

MULTIPLE_HITS SUCCESS A serialized business object.
Exist FAIL (Optional) An error message.

SUCCESS

Copyright IBM Corp. 1997, 2004