Message formats for the IBM MQ Bridge to blockchain before IBM MQ 9.2.0 on z/OS®

Information on formatting of the messages that are sent and received by the IBM® MQ Bridge to blockchain.

Attention: The existing format for the message formats is obsolete. From IBM MQ 9.2.0, if you have a Hyperledger Fabric network, use the format of the messages described in Message formats for the IBM MQ Bridge to blockchain from IBM MQ 9.2.0.

An application requests that the IBM MQ Bridge to blockchain drives the Hyperledger Composer defined REST API to act on information that is held on the blockchain. The application does this by placing a request message on the bridge request queue. The results of the REST request are formatted by the bridge into a reply message. The bridge uses information that is contained in the ReplyToQ and ReplyToQMgr fields from the MQMD of the request message as the destination for the reply message.

The request and reply messages are text (MQSTR) messages in JSON format.

Request Message Format

Request messages contain three attributes:

method: The REST verb used to call the Hyperledger Composer REST API, such as POST, DELETE, or GET
path: The path to the Hyperledger Composer REST API. This is added to the base server URL. The path should begin with "api/".
body: The method-specific content. This is often a JSON structure.

The following example uses the POST method, to path api/Trader, to create a new Trader object. The body specifies the Traders class, as defined by the Hyperledger Composer model of the user, and also specifies the additional values required to create a new Trader object within the blockchain network.

{ "method": "POST",
  "path": "api/Trader",
  "body": {
    "$class" : "org.example.trading",
    "tradeId" : "Trader2",
    "firstName": "Jane",
    "lastName" : "Doe"

Reply Message Format

Reply messages have their correlation ID set to the message ID of the inbound message. Any user-defined properties are copied from the request message to the reply message. The user ID in the reply is set to the originator's user ID.

The statusCode is an HTTP status code. If the error is from IBM MQ or the bridge, then an appropriate statusCode is used.

statusType is a string, either SUCCESS or FAILURE.

For successful requests, the "data" element in the reply message contains the response from the invoked Hyperledger Composer REST API.

An example of successful processing:

{
   "statusCode": 200,
   "statusType": "SUCCESS",
   "data": [
      {
         "$class": "org.example.trading",
         "firstName": "John",
         "lastName": "Doe",
         "tradeId": "Trader1"
      },
      {
         "$class": "org.example.trading",
         "firstName": "Jane",
         "lastName": "Doe",
         "tradeId": "Trader2"
      }
   ]
}

All error responses have the same fields, regardless of whether they are generated by the bridge itself, from the calls to the Hyperledger Composer REST server, blockchain, or from the chaincode invocation. For example:

Bad JSON input message

{
   "statusCode": 400,
   "statusType": "FAILURE",
   "message": "[AMQBC021E] Error: Cannot parse input message or there are  
    missing fields in the message. Missing fields appear to be: "method"."
}

Request that failed to be processed by the Hyperledger Composer REST server

{
   "statusCode": 500,
   "statusType": "FAILURE",
   "message": "Error trying to invoke business network. Error: No valid responses 
    from any peers.\nResponse from attempted peer comms was an error: Error: chaincode 
    error (status: 500, message: Error: Failed to add object with ID 'Trader1' 
    as the object already exists)"
}

Applications can tell whether the request succeeded or failed by either looking at the statusType string, or from the existence of the data field. When there is an error in processing the input message, and the bridge does not send it to blockchain, the value that is returned from the bridge is an MQRC value, usually MQRC_FORMAT_ERROR.