IBM BPM, V8.0.1, All platforms > Programming IBM BPM > Developing client applications for BPEL processes and tasks > Developing JMS client applications (deprecated) > Access the JMS API (deprecated)

(Deprecated) Structure of a Business Process Choreographer JMS message (deprecated)

The header and body of each JMS message must have a predefined structure.

Attention: The Business Process Choreographer JMS API is deprecated. To develop JMS-based client applications, use the Business Process Choreographer web services API with the SOAP/JMS transport protocol.

A Java Message Service (JMS) message consists of:

The Business Process Choreographer supports text message formats only.


Message header

JMS allows clients to access a number of message header fields.

The following header fields can be set by a Business Process Choreographer JMS client:

JMSReplyTo

The destination to send a reply to the request. If this field is not specified in the request message, the reply is sent to the Export interface's default reply destination (an Export is a client interface rendering of a BPEL process component). This destination can be obtained using initialContext.lookup("jms/BFMJMSReplyQueue");

TargetFunctionName

The name of the WSDL operation, for example, "queryProcessTemplates". This field must always be set. If that the TargetFunctionName specifies the operation of the generic JMS message interface described here. This should not be confused with operations provided by concrete processes or tasks that can be invoked indirectly, for example, using the call or sendMessage operations.

A Business Process Choreographer client can also access the following header fields:

JMSMessageID

Uniquely identifies a message. Set by the JMS provider when the message is sent. If the client sets the JMSMessageID before sending the message, it is overwritten by the JMS provider. If the ID of the message is required for authentication purposes, the client can retrieve the JMSMessageID after sending the message.

JMSCorrelationID

Links messages. Do not set this field. A Business Process Choreographer reply message contains the JMSMessageID of the request message.

Each response message contains the following JMS header fields:

ServiceRuntimeExceptions are not returned to asynchronous client applications. When a severe exception occurs during the processing of a JMS request message, it results in a runtime failure, causing the transaction that is processing this request message to roll back. The JMS request message is then delivered again. If the failure occurs early, during processing of the message as part of the SCA Export (for example, while deserializing the message), retries are attempted up to the maximum number of failed deliveries specified by the SCA Export's receive destination.

After the maximum number of failed deliveries is reached, the request message is added to the system exception destination of the Business Process Choreographer bus. If, however, the failure occurs during actual processing of the request by the Business Flow Manager's SCA component, the failed request message is handled by the failed event management infrastructure, that is, it may end up in the failed event management database if retries do not resolve the exceptional situation.


Message body

Operations exposed by BPEL processes or human tasks must comply with the document/literal wrapper style. The JMS message body is a String containing an XML document that represents the document/literal wrapper element of the operation. The generic operations of the JMS message interface propagate the document-wrapper element to and from the operation that is implemented by the BPEL process or human task.

The following example shows a simple valid request message body: 

<bfm:queryProcessTemplates 
     xmlns:bfm="http://www.ibm.com/xmlns/prod/websphere/business-process/services/6.0">
  <whereClause>PROCESS_TEMPLATE.STATE IN (1)</whereClause>
</bfm:queryProcessTemplates>

The following example shows a more complex, valid request message body. The client application has a sendMessage API operation for submitting a message to a specific process. The process input message is one of the API parameters; this message is the input message of a business operation exposed by a customer process. The process contains a receive activity that consumes the message.

The bfm:sendMessage element is the document wrapper element of the JMS API operation. It includes the cns:updateCustomer element, which is the document wrapper element for the operation that is implemented by the process. This process has, for example, a bpel:receive activity that references the cns:customerProcessPortType WSDL port type, and the updateCustomer WSDL operation. 

<bfm:sendMessage 
     xmlns:bfm="http://www.ibm.com/xmlns/prod/websphere/business-process/services/6.0">
  <processTemplateName>customerProcessTemplate</processTemplateName>
  <portType xmlns:cns="http://example.com/customerProcess">cns:customerProcessPortType</portType>
  <operation>updateCustomer</operation>
  <cns:updateCustomer xmlns:cns="http://example.com/customerProcess">
    <street>1600 Pennsylvania Avenue Northwest</street>
    <city>Washington, DC 20006</city>
  </cns:updateCustomer>
</bfm:sendMessage>

Access the Business Process Choreographer JMS API (deprecated)


Related tasks:
Checking the response message for business exceptions in JMS client applications (deprecated)