Business object requests

Business object requests are processed when InterChange Server sends a business object to the doVerbFor() method . Using the configured data handler, the adapter converts the business object to an WebSphere MQ message and issues it. There are no requirements regarding the type of business objects processed except those of the data handler.

Verb processing

The adapter processes business objects passed to it by a collaboration based on the verb for each business object. The adapter uses business object handlers and the doForVerb() method to process the business objects that the adapter supports. The adapter 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 adapter 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 verbs

The processing of business objects with the create, update, and delete verbs will depend on whether the objects are issued asynchronously or synchronously.

Asynchronous message delivery

The default delivery mode for business objects with create, update, and delete verbs is asynchronous. A message is created from the business object by using a data handler and then it is written to the output queue. If the message is delivered, the adapter returns BON_SUCCESS, else BON_FAIL .

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

Synchronous message delivery

Note:
This approach requires a customization of the commands that are executed in the FRONT ARENA application when a business object comes from the InterChange Server. The commands should retrieve the ReplyTo queue from the message, and place a reply on the queue within the ResponseTimeout interval. For information about creating and customizing commands in FRONT ARENA, refer to the Programmer's Guide for SunGard FRONT ARENA, 1.5, 5.4.

If a replyToQueue has been defined in the connector properties and a ResponseTimeout exists in the conversion properties for the business object, the adapter issues a request in synchronous mode. The adapter then waits for a response to verify that appropriate action was taken by FRONT ARENA.

Note:
MQMDs are message descriptors. MQMDs contain the control information accompanying application data when a message travels from one application to another. You must specify a value for the MQMD attribute, OutputFormat, in either your static or dynamic meta-object.

The adapter initially issues a message with a header as shown in the following table.

Table 2.

Request message descriptor header (MQMD)
Field
Description Value

Format

The format name.

The output format as defined in the conversion properties where the output is truncated to 8 characters to meet IBM requirements (for example: MQSTR).

MessageType

The message type.

MQMT_DATAGRAM*

Report

The options for the 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

The name of a reply queue.

When a response message is expected, this field is populated with the value of the connector property ReplyToQueue.

Persistence

The message persistence.

MQPER_PERSISTENT*

Expiry

The message lifetime.

MQEI_UNLIMITED*

* Indicates a constant that is defined by IBM.

The message header described in Table 2 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 FRONT ARENA. The thread that issued the message waits for a response message that indicates whether FRONT ARENA was able to process the request.

When FRONT ARENA receives a synchronous request from the adapter, it processes the data of the business object and issues a report message as described in the following tables.

Table 3. Response message descriptor header (MQMD)

Field
Description Value

Format

The format name.

The input format of busObj as defined in the conversion properties.

MessageType

The message type.

MQMT_REPORT*

* Indicates a constant that is defined by IBM.


Table 4. Population of response messages

Verb Feedback field Message body

Create, Update, or Delete

SUCCESS VALCHANGE

(Optional) A serialized business object reflecting changes.


VALDUPES FAIL

(Optional) An error message.


Table 5. WebSphere MQ feedback codes and InterChange Server response values

WebSphere MQ feedback code Equivalent InterChange Server responseInterChange Server*

MQFB_NONE (this is the default if no feedback code is specified)

VALCHANGE

MQFB_PAN or MQFB_APPL_FIRST

SUCCESS

MQFB_NAN or MQFB_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)

MQFB_NONE

What the connector receives if no feedback code is specified in the response message

If the business object can be processed, the application creates a report message with the feedback field set to MQFB_PAN (or a specific InterChange Server 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 InterChange Server value), 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 adapter message and issues it to the queue specified by the replyTo field.

Upon retrieval of a response message, the adapter matches the correlationID of the response to the messageID of a request message. The adapter then notifies the thread that issued the request. Depending on the feedback field of the response, the adapter either expects a business object or an error message in the message body. If a business object was expected, but the message body is not populated, the adapter 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.

Custom feedback codes

You can extend the WebSphere MQ feedback codes to override the default interpretations, shown in Table 5, by specifying the connector property, FeedbackCodeMappingMO. This property allows you to create a meta-object in which all InterChange Server-specific return status values are mapped to the WebSphere MQ feedback codes.

The return status assigned to a feedback code is passed to InterChange Server. For more information, see "FeedbackCodeMappingMO".

Retrieve verb

For business objects with the retrieve verb 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 and retrieve by content verbs, the message body must be populated with a serialized business object to complete the transaction.

Table 6 shows the response messages for these verbs.

Table 6. Population of response message

Verb Feedback field Message body

Retrieve

FAIL

(Optional) An error message.

Data handler message processing

The Adapter for FRONT ARENA uses a newly developed data handler which is capable of coping with native FRONT ARENA messages. The data handler supports both message-to-business object conversion and conversion in the opposite direction.

When converting messages to business objects, the data handler relies on a newly developed name handler which determines the type of business object to be created from certain message fields. For details about this and other connector-specific properties, see Configuring the data handler. For details about developing a data handler, see the Data Handler Guide.

Copyright IBM Corp. 1997, 2004