Message formats for the IBM MQ Bridge to blockchain from IBM MQ Version 9.1.4

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

An application requests that the IBM MQ Bridge to blockchain drives the Hyperledger Fabric server 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 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 and contain four elements.

Request Message Format

Request messages contain the following attributes:

operation

String - case insensitive

submit for updates or evaluate for queries

network

String - sometimes known as a channel in Hyperledger Fabric

contract

String - the smart contract, or chaincode package, to be invoked

args

Array - usually of strings but some elements can be nested JSON objects.

The actual arguments to the contract, including the method name.

For example:

{
  "operation" : "Evaluate",
  "network"   : "mychannel",
  "contract"  : "marbles0",
  "args"      : [ "readMarble", "marble1" ]
}

Note: Apart from ensuring these elements exist, and that the message is valid JSON, no validation of the content is done by the bridge. The bridge relies on Hyperledger Fabric to process the request or return errors.

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. Parent topic: Running the IBM MQ Bridge to blockchain