Enable business processes to react to blockchain events

Note: IBM Blockchain Platform now utilizes Hyperledger Fabric for end-to-end development. Users may use Hyperledger Composer at their choice, but IBM will not provide support for it.

Part 1 of our series showed how the combination of business process management (BPM) and blockchain technology greatly simplifies distributed, collaborative processes between multiple enterprises, via a shared ledger used by all the participants. Rather than individually storing relevant data in individual information systems and synchronizing between parties bilaterally, the single shared ledger instance is updated, and its information becomes visible to all participants (based on their authorization).

Now in this Part 2, we go beyond mere data sharing through blockchain, and explore blockchain’s “active behavior”: its capability to notify participants about successful completion of a transaction, by sending events.

Collaboration models

Figure 1 shows a typical B2B interaction, represented as a BPMN (Business Process Model and Notation) collaboration diagram, where three participants communicate to achieve an overall business goal. Each participant is assumed to autonomously run a private process of its own (those processes are not shown). Private processes interact through bilateral messages, ensuring exchange of information and synchronization between participants.

Figure 1. Multi-party collaboration (represented as a BPMN diagram)

The resulting collaboration is sometimes called a choreography, because the individual participants act autonomously, according to their own internal rules. Still, the exchange of messages is happening in a pre-defined way, according to a contract between participants. The minimal process adhering to this contract is sometimes called the public process of a participant, to indicate that it can be observed by other participants. Its actual implementation is through a private process, which may include additional steps internal to the participant.

The drawback of this model is the need for multiple communication channels, one per bilateral communication. Also, messages are transient, and not visible to other participants apart from sender and receiver.

Replacing the messaging infrastructure with a blockchain-based distributed ledger addresses those issues. A participant can trigger a transaction in the business network implemented through the ledger, which in turn will send notifications to any other interested participant. Thus, the blockchain framework effectively becomes the B2B messaging layer. Note that this basically is a different view of the same technology: We can either focus on the capability of a blockchain to persist data in a shared, distributed way with non-repudiation and audit capability, or we can focus on its ability to trigger transactions and push transaction results to participants as events, thus becoming a messaging layer.

Figure 2 shows a blockchain in the middle, surrounded by the participants and including their private processes. Note that the messaging is replaced by the ledger. The actual rules that determine which transaction can be called, and which events are triggered, become part of the business network definition and the definition of the network’s smart contracts.

Figure 2. Multi-party collaboration with blockchain

Now, in order to implement such B2B interactions using blockchain as the B2B messaging layer, your processes need to be able to react to blockchain events. The remainder of this tutorial shows you how to use Hyperledger Composer and IBM Business Process Manager (IBM BPM) to make your processes react to blockchain events.

Introducing the Event Bridge

In Part 1, we used Hyperledger Composer REST Server to query data on the blockchain and invoke transactions from an IBM BPM process.

A long-awaited enhancement to Hyperledger Composer REST Server was introduced recently: events support. This means that the blockchain event mechanism is now exposed via Hyperledger Composer REST Server. Hyperledger Composer REST Server can publish events that occur on a business network, so that connected applications can subscribe to them.

So, Hyperledger Composer REST Server can now publish events. And IBM BPM can handle message events to start or continue processes based on these events. So far, so good. However, part of the equation is missing. We need a way to listen for events published by Hyperledger Composer REST Server and transform them into message events that IBM BPM can understand.

Our solution for this missing link is what we call an Event Bridge. The Event Bridge listens for events emitted by Hyperledger Composer REST Server and calls the appropriate undercover agent in IBM BPM to start or continue a process instance that reacts to the event.

We based our example on the vehicle lifecycle business network that is provided as a sample network with Hyperledger Composer. In this network, a private person places an order for a vehicle on the blockchain. The initiated transaction creates an order for the manufacturer and broadcasts an event. The manufacturer needs to react to this event by initiating the actions required to schedule the vehicle for manufacturing and to update the status of the order on the blockchain.

This tutorial shows you the steps to react to blockchain events in a IBM BPM process:

1. We first explore how events are implemented in Hyperledger Composer and how they work.
2. We configure Hyperledger Composer REST Server to publish events for consumption by the Event Bridge.
3. We develop the Event Bridge to listen to events published by the Hyperledger Composer REST Server.
4. We implement an undercover agent in IBM BPM that is triggered by the Event Bridge and — in response to the event — and starts a process instance.
5. We extend the Event Bridge to trigger the undercover agent through a REST service and provide the event message (in this scenario, the order details) to the process.
6. We explain how to extend the process so that the order details can be reviewed by the manufacturer and the necessary actions can be kicked off.
7. We show how to enable business processes to react on Blockchain events by using intermediate events.

So, this tutorial is for you, whether you are familiar with Hyperledger Composer and the blockchain event mechanism and want to learn how to handle those events in an IBM BPM process – or you are an expert in IBM BPM and want to learn how Hyperledger Composer events work and how they can be consumed in IBM BPM.

What you need for this tutorial

To follow along with this tutorial, you need the following prerequisites:

• IBM BPM V8.5.7 2017.03 or later.
  If you don’t have the required level of IBM BPM, consider using IBM BPM on Cloud instead. Start your free trial.
• A business network.
  This tutorial uses the vehicle lifecycle network provided with Hyperledger Composer, where the participants contribute to the lifecycle of a vehicle. To set up the business network, follow the instructions to deploy the vehicle lifecycle network.
• Hyperledger Composer REST server.
  Hyperledger Composer includes the composer-rest-server package, which provides an easy way to set up a REST API server to work with the business network. After you deploy the business network, follow the instructions to generate the REST API. These instructions also describe how you can inspect and execute the REST APIs that are generated from the business network.
• Node and npm.
  The Event Bridge is implemented using Node.js, so you need recent versions of node and npm on your system.

To explore the REST API for the vehicle lifecycle network, navigate to:
http://your-hyperledger-composer-rest-server:3000/explorer

In the REST API Explorer, you can see the participants in the business network, including Manufacturer, PrivateOwner, Regulator, and ScrapMerchant. In addition, there are two Assets defined: Order and Vehicle. You can perform several transactions, including SetupDemo, PlaceOrder, UpdateOrderStatus, and PrivateVehicleTransfer.

To initially create participants and assets for the vehicle business network, perform the POST /SetupDemo transaction.

Now, use the REST API Explorer to simulate a manufacturer’s ordering application that allows a private owner to submit an order to the manufacturer. Navigate to the POST /PlaceOrder transaction and submit an order using the following data:

{
  "$class": "org.acme.vehicle.lifecycle.manufacturer.PlaceOrder",
  "orderId": "9999",
  "vehicleDetails": {
    "$class": "org.vda.VehicleDetails",
    "make": "Arium",
    "modelType": "Rose",
    "colour": "red"
  },
  "manufacturer": "org.acme.vehicle.lifecycle.manufacturer.Manufacturer#Arium",
  "orderer": "org.acme.vehicle.lifecycle.PrivateOwner#anthony",
  "timestamp": "2017‑11‑03T15:26:05.528Z"
}

This transaction creates a new order in the asset registry and emits a PlaceOrderEvent event.

Now explore how this event is implemented in the vehicle lifecycle network. The event is defined in the manufacturer.cto model file and consists of two properties – orderId and vehicleDetails:

event PlaceOrderEvent {
  o String orderId
  o VehicleDetails vehicleDetails
}

The transaction that creates the PlaceOrderEvent event is defined in manufacturer.js. In order for the event to be published, this transaction implements three functions and sets the required properties of the event:

            
var factory = getFactory() // allows events to be created as part of the transaction
var placeOrderEvent = factory.newEvent(‘org.acme.vehicle.lifecycle.manufacturer’,‘PlaceOrderEvent’) // creates the PlaceOrderEvent in the specified namespace.
placeOrderEvent.orderId = order.orderId; // sets event properties, as defined in manufacturer.cto
placeOrderEvent.vehicleDetails = order.vehicleDetails;
emit(placeOrderEvent) // emits the event

In our scenario, we want the Hyperledger Composer REST Server to publish events for consumption by the Event Bridge application. This step requires additional configuration on the REST Server.

Configure Hyperledger Composer REST Server to publish events emitted from a business network, so that the Event Bridge that you implement in Step 3 can subscribe to these events. At the time of writing, the REST Server supports publishing events over WebSockets. Therefore, you need to enable WebSockets in Hyperledger Composer REST Server:

1. Export the corresponding environment variable:
   export COMPOSER_WEBSOCKETS=true
2. Restart Composer REST Server.
   

In this step, you implement the Event Bridge. For now, the Event Bridge only subscribes to events that are published by the Hyperledger Composer REST Server and write the event message (payload) to the console. In Step 5, you extend the Event Bridge to invoke a process instance in IBM BPM.

The Event Bridge implementation is done in Node.js. The initial implementation of the Event Bridge establishes a connection to the Hyperledger Composer REST Server using the WebSocket protocol. If a PlaceOrderEvent event occurs, the script writes the event message to the console:

var WebSocketClient = require('websocket').client;
 
var client = new WebSocketClient();
client.connect('ws://your‑hyperledger‑composer‑rest‑server:3000/');
 
client.on('connectFailed', function(error) {
    console.log('Connect Error: ' + error.toString());
});
 
client.on('connect', function(connection) {
    console.log('Connection established');
    connection.on('error', function(error) {
        console.log("Connection Error: " + error.toString());
    });
    connection.on('close', function() {
        console.log('Connection Closed');
    });
    connection.on('message', function(message) {
        var jsonString = JSON.parse(message.utf8Data);
        
        if (jsonString.$class == "org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent") {
            console.log("PlaceOrderEvent received: '" + message.utf8Data + "'");
        }    
    });    
});

To run the script, complete the following steps:

1. Install the required websocket module:
   npm install websocket
2. Run the script:
   node EventBridge.js
3. Check the console for the following message:
   Connection established
4. Place an order on the blockchain as shown in Step 1. (Tip: Because order IDs must be unique, don’t forget to use a different value here.)
5. Check that the console shows the message of the event, including the orderId and vehicleDetails:

   
   PlaceOrderEvent received: 
   '{"$class":"org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent","orderId":"99998","vehicleDetails":
   {"$class":"org.vda.VehicleDetails","make":"Arium","modelType":"Rose","colour":"red"},"eventId":"5fdd65ab9a02fcc7c0bfc1caf80055320247e6ee4e83b5b65aef1f18dfbac1d2#0","timestamp":"2017‑11‑03T15:26:05.528Z"}'
   

   Show more

In this step, we’ll show you how to implement the undercover agent in IBM BPM. An undercover agent provides the ability to invoke a process using REST:

1. In Process Designer, create a new process app, provide a name (for example, Order Processing) and an acronym (for example, OP).
2. In the library, click the plus sign (+) next to Events and select Undercover Agent.
3. Provide a name and select On Event as the Schedule Type.
4. On the Undercover Agent page in the Scheduler section, make sure Message is selected as the Event Marker.
5. In the library, click the + sign next to Processes and create a process.
6. Provide a name, such as Process Order.
7. On the Variables tab for the process, create three Variables: an Input variable of type NameValuePair and two Private variables of type String.
8. On the Definition tab, add a Script Task (init), a User Task (Review Order), and a Subprocess (do whatever is needed) to the process and wire them together.
9. Implement the Start event.
   In the Properties tab, click Implementation. For the Start Event Type, select Message, and for the Attached message undercover agent, select the undercover agent that you just created. Because we want to use the message data in the process, also check Consume message.
10. Click Data Mapping and map Output(NameValuePair) to the Input variable, and name(String) and value(String) to the private variables you created earlier.
11. Implement the init script task.
    In the Properties tab, click Script. To check that the event message is successfully received, log the value of the message.
12. Save your work and create a snapshot of the process app.
13. Make the undercover agent accessible from outside IBM BPM by activating the process app in the Process Admin console.

Your undercover agent is now ready to receive event messages.

Tip: Before moving to the next step, test your undercover agent using the REST API Tester provided with IBM BPM.

a. Access the REST API Tester.
b. Expand Business Process Manager REST API and then Process API.
c. Select Send Message.
d. Select the POST method.
e. For the message, use the following format. Replace processApp and ucaname, if necessary, to match the names you used.

<eventmsg>
  <event processApp="OP" ucaname="OrderProcessingUCA">
  </event>
  <parameters>
    <parameter>
      <key>Input</key>
      <value type="NameValuePair">
        <name>message</name>
        <value>Hello from REST API Tester</value>
      </value>
    </parameter>
  </parameters>
</eventmsg>

Congratulations, your undercover agent is working!

So far, the Event Bridge that we developed in Step 3 can detect an event emitted from the Hyperledger Composer REST Server. In our scenario, when the PlaceOrderEvent event occurs, we want to start an IBM BPM process instance for the manufacturer to process the order. We therefore need to extend the connection.on('message') function in EventBridge.js to perform the necessary REST call. When constructing the URL, add the encoded event message to the URL as the message value.

The request includes:

• The constructed URL. Replace the host name with the host name of your IBM BPM server.
• Method: 'POST'
• Headers, including ‘Content-Type’: ‘application/json’, ‘Authorization’ : ‘Basic credentials‘ where credentials are the Base64-encoding of username:password of your BPM server

Note: To demonstrate the essentials of the Event Bridge (subscribe to blockchain events and initiate a BPM process), the sample is simple and easy to understand. If you use the sample in your environment, you may want to replace the rejectUnauthorized: false option and add the content of the CA certificate file of your BPM server, so that server’s identity can be verified. See https://github.com/request/request for more details.

connection.on('message', function(message) {
var jsonString = JSON.parse(message.utf8Data);

if (jsonString.$class == "org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent") {
console.log("PlaceOrderEvent received: '" + message.utf8Data + "'");
console.log("Starting IBM BPM process to process order... ");

// replace username:password and hostname
var base64encoded = Buffer.from("username:password").toString('base64');
var urlcomplete = 'https://bpmserver:9443/rest/bpm/wle/v1/process?action=sendMessage&message=<eventmsg><event processApp="OP" ucaname="OrderProcessingUCA"></event><parameters><parameter><key>Input</key><value type="NameValuePair"><name>message</name><value>' + encodeURIComponent(message.utf8Data) + '</value></value></parameter></parameters></eventmsg>';

// if class of event : "org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent" call the BPM UCA to process the order.
request({
url: urlcomplete,
method: 'POST',
headers: {'Content‑Type': 'application/json', 'Authorization' : 'Basic ' + base64encoded},
rejectUnauthorized: false
}, function (err, resp, body) {
if (err){
console.log("resp = " + resp);
}
else{    
console.log("StatusCode: "+resp.statusCode);
if (resp.statusCode == 200) {
console.log(body);
}
}  
});
};
    });

The server request requires three more npm components that need to be added to the EventBridge.js:

var request = require('request');
var response = require('response');
var https = require('https');

To run the script, complete the following steps:

1. Install the required npm modules:
   npm install request
npm install response
npm install https
2. Run the script:
   node EventBridge.js
3. Check that the console shows the following message:
   Connection established
4. Place an order on the blockchain as shown in Step 1. (Tip: Because order IDs must be unique, don’t forget to use a different value here.)
5. Check that the console shows the event payload, including the orderId and vehicleDetails:

                   
   PlaceOrderEvent received: 
   '{"$class":"org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent","orderId":"99995","vehicleDetails
   ":{"$class":"org.vda.VehicleDetails","make":"Arium","modelType":"Rose","colour":"red"},"eventId":"a7ca458a434f45f3f73a95db3248a2258eea216e983cf4985860ba6713c92cba#0","timestamp":"2017‑
   11‑03T15:26:05.528Z"}'
   

   Show more
6. Check that the console also shows the following message:

   
   Starting IBM BPM process to process order... 
   StatusCode: 200
   {"status":"200","data":{"messageSent":true}}
   

   Show more
7. Check that Process Portal has a Review Order task, which indicates that a process instance has started.
8. Check that the SystemOut.log files shows:

   
   message received: 
   {"$class":"org.acme.vehicle.lifecycle.manufacturer.PlaceOrderEvent","orderId":"99995","vehicleDetails"
   :{"$class":"org.vda.VehicleDetails","make":"Arium","modelType":"Rose","colour":"red"},"eventId":"a7ca458a434f45f3f73a95db3248a2258eea216e983cf4985860ba6713c92cba#0","timestamp":"2017‑
   11‑03T15:26:05.528Z"}
   

   Show more

Your Event Bridge now receives events and starts an IBM BPM process instance in response to the event!

You can now extend the IBM BPM process. Parse the event message, pass the data to the human service, and arrange the order details in the user interface so that the business person can conveniently review the order. Finally, update the order status on the blockchain by performing the corresponding transaction.

Your friend and helper for this step is the service discovery in Process Designer. It discovers the model and operations available in the business network and generates an external service that can be used in a process.

1. Download the swagger.json on your Hyperledger Composer REST Server:
   http://your-hyperledger-composer-rest-server:3000/explorer/swagger.json.
   This OpenAPI Specification describes the operations and model used by the business network.
2. In your process application, click the plus sign (+) next to Services, and create an external service.
3. Select Java, REST, or Web service.
4. Browse to select the swagger.json file you downloaded in step 1 and click Next.
5. On the panel that shows operations to include in the generated external service, deselect all operations except Order, Vehicle, and UpdateOrderStatus:
6. Create a new server. Click Finish.
7. Explore the discovered Business Objects:
8. Explore the discovered operations:
9. Explore the attached process app or check out Part 1 of this series to learn how to use discovered data types and operations in the process.

You can follow the same procedure and react to blockchain events using intermediate message events in IBM BPM. Intermediate message events allow a message event to be received during the process execution. For this type of events, you can also use an undercover agent to trigger a message event. Instead of the “Start event,” use the component “Intermediate message event” in the process diagram. In addition, for the event message to be passed to the correct process instance, you need to assign a correlation value to an output value of the undercover agent.

Follow these steps to define intermediate message events.

In this example, the parameter name of the undercover agent output is assigned to the variable orderId:

In EventBridge.js, you define the URL that is used in the request to trigger the undercover agent like the following example:

var urlcomplete = 'https://bpmserver:9443/rest/bpm/wle/v1/process?action=sendMessage&message=<eventmsg><event processApp="OP" ucaname="OrderProcessingUCA"></event><parameters><parameter><key>Input</key><value type="NameValuePair"><name>' + jsonString.orderId + '</name><value>' + encodeURIComponent(message.utf8Data) + '</value></value></parameter></parameters></eventmsg>';

In this sample, an event message with the parameter <name>9876</name> will be passed to the process instance where the variable tw.local.oderId is 9876.

Conclusion

Blockchain events can be easily exposed in Hyperledger Composer REST Server, so that connected applications can subscribe to the events using the WebSockets protocol. In this tutorial, you learned how to implement the Event Bridge that listens to events emitted by the Hyperledger Composer REST Server and calls the appropriate undercover agent in IBM BPM. You also learned how to configure the undercover agent that is triggered by the Event Bridge and — in response to the event — starts a process instance to kick off the necessary actions.

You can clone this GitHub repository to use the Event Bridge sample: https://github.com/ibmbpm/bpm-blockchain-events/tree/master.

We’re eager to learn about your experiences and any further requirements you might have for integrating IBM BPM and blockchain. For more ways to connect, see the links in our bios (Larissa and Matthias).

Acknowledgments

We’d like to thank Ute Tanneberger and Thomas Duerr for their careful review of this tutorial, and their valuable comments and corrections. Further thanks to Thomas and also Benjamin Wende for the thorough code review. Many thanks to Helen O’Shea and Joshua Horton for their helpful comments and editorial suggestions.