Archived | Use blockchain to manage legal documents stored in an enterprise content repository

Archived content

Archive date: 2019-05-01

This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.

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.

This is Part 3 in our tutorial series on using blockchain technology with IBM Business Process Manager. Blockchain is a shared, immutable ledger for recording the history of business transactions. It ushers in a new generation of transactional applications that establish trust, accountability, and transparency in the exchange of physical or digital assets.

Part 1 showed how the combination of business process management (BPM) and blockchain technology simplifies distributed, collaborative processes between multiple enterprises. A shared ledger is used by all the participants, and smart contracts govern transactions. 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).

In Part 2, we went beyond mere data sharing through blockchain. We explored blockchain’s “active behavior”: its capability to notify participants about the successful completion of a transaction, by sending events.

Overview of this tutorial

In this tutorial, you’ll see how to use both IBM Business Process Manager and IBM Enterprise Content Manager to facilitate transactions with physical contracts via a blockchain network. We’ll use a Letter of Credit transaction to demonstrate how you can coordinate payment for goods, based on contract documents that are stored in a content repository.

A Letter of Credit is a method of payment and an important part of international trade. Both the buyer and seller rely on the security of banks to ensure that payment is received and goods are provided. In a Letter of Credit transaction, the goods are consigned to the order of the issuing bank, meaning that the bank will not release control of the goods until the buyer has either paid or undertaken to pay the bank for the documents. For more background on Letter of Credit documents and blockchain, check out this short video.

Common problems in Letter of Credit document transactions

When blockchain technology is NOT part of the scenario, as shown in Figure 1, common problems include:

  • Inconsistent or undocumented processes
  • Unnecessary manual work
  • Limited, ineffective automation of workflows and business policies
  • Poor visibility of the end-to-end process
  • Slow, inefficient exception handling
Figure 1. A Letter of Credit transaction without blockchain technology

However, when blockchain technology IS part of the scenario, the common problems are mitigated or removed entirely, as shown in Figure 2. Blockchain introduces timely, accurate process performance. By using a distributed ledger as the underlying system of record, all participants can achieve significant business process improvements.

Figure 2. A Letter of Credit transaction with blockchain technology

Let’s look at the various parties in a network that use a shared ledger for Letter of Credit document transactions. The four participants are: Buyer, Seller, Buyer’s Bank, and Seller’s Bank. Participants retrieve documents and update information on the ledger, and react to events when others submit documents. In this tutorial, we focus on the Buyer’s Bank. The Buyer’s Bank reviews the entire transaction and pays the Seller’s Bank, which pays the Seller (payment authorization through blockchain), as shown in Figure 3.

Figure 3. Participants in the network

A perfect match: IBM BPM, IBM ODM, IBM ECM, and IBM Blockchain

Our scenario focuses on the internal business process of the Buyer’s Bank as it participates in and interacts with a blockchain network. Instead of manually reviewing and verifying the documents, the Buyer’s Bank can use IBM Business Process Manager (IBM BPM) to automate the document verification process. The IBM Operational Decision Manager (IBM ODM) decision service uses the document metadata stored on the blockchain to verify whether the document is valid in the context of the blockchain transaction. If the verification fails, the process assigns a person (a knowledge worker) to perform a manual document review. The document used for this review is retrieved from the IBM Enterprise Content Management (IBM ECM) document store.

The process is kicked off by a blockchain transaction as shown in step 4 ( Seller’s Bank reviews the documents and submits them to Buyer’s Bank through blockchain) shown in Figure 2. In the process, the Buyer’s Bank validates the documents by comparing information about them in IBM ECM with document metadata stored in blockchain (for example, using the document hash value to ensure that the documents have not been updated, or comparing specific document properties to ensure that they are consistent with the information stored in the ledger). Additionally, IBM ODM decision verifies whether documents are valid in the context of the blockchain transaction.

Figure 4. How the Buyer’s Bank interacts with the blockchain and IBM ECM to validate the documents


IBM Business Process Manager (IBM BPM)

IBM BPM is a business process management platform. It includes tooling and runtimes for process design and execution, along with capabilities for monitoring and optimizing work that is executed within the platform. It enables process owners and business users to engage directly in improving their business processes.

IBM Blockchain

IBM Blockchain is based on Hyperledger Fabric from the Linux Foundation. Hyperledger Fabric is a business blockchain framework that includes an extensive, open development toolset and framework to help you develop use cases and deploy blockchain solutions. It allows you to model your business network as shown in Figure 5.

Figure 5. Modeling a business network using Hyperledger Fabric

For our Letter of Credit scenario, you can use IBM Blockchain Platform’s developer tools, based on Hyperledger Composer, to create a Business Network Definition, which is packaged in a .bna (Business Network Archive) file. The developer environment allows you to deploy .bna files to a local or cloud-based blockchain network for further development and sharing. Resources in Hyperledger Composer such as assets, participants (actors), and transactions are expressed using the Composer Modeling Language. Participants include Seller, Buyer, Seller’s Bank, and Buyer’s Bank. Assets include trades and documents that are stored or processed as transactions. A sample Letter of Credit data model is shown in Listing 1.

Listing 1. A sample Letter of Credit data model (.bna file)

    "tradeId": "string",
    "term": "string",
    "state": "string",
    "docId": "string",
    "buyerId": "string",
    "sellerId": "string",
    "buyerBankId": "string",
    "sellerBankId": "string", 

    "$class": "",
    "actorId": "string",
    "name": "string", 
    "role": "string",

    "$class": "",
    "documentId": "string",
    "name": "string", 
    "type": "string",
    "version": "string",
    "registry": "string",
    "hash": "string",
    "valid": true,
    "submittedBy": "string", 

You can download the sample Letter of Credit .bna file (letter_of_credit.bna) from GitHub. The model file contains the JavaScript logic (smart contract) to execute the transactions, including verifying the correct transaction id and the correct authorization for actors to perform the transaction in the Letter of Credit scenario.

Figure 6. A sample Letter of Credit smart contract

You can generate the REST API after you deploy the business network on Hyperledger Composer.

Figure 7. A sample Letter of Credit REST API

Finally, you need a swagger definition file to discover the service from IBM BPM. You can download this Letter of Credit Swagger file (letter_of_credit.json) from GitHub.

IBM Operational Decision Manager (IBM ODM)

IBM ODM is a digital process automation tool that captures, automates, and governs frequent, repeatable business decisions.

Figure 8. IBM ODM functionality


In IBM BPM (shown in Figure 10), the starting service for our scenario is Retrieve Trade Service Flow.

Figure 9. BPM services

This service essentially retrieves information on the Letter of Credit tradeId, docId, all participants in this trade, and the state in blockchain as shown in Figure 11.

Figure 10. Information to be retrieved

The docId is channeled to Retrieve Document Service Flow. The service flow calls blockchain to retrieve document information based on docId with an information value of Name, Rendition file format, Versioning, URL registry, Hash code, and validity. When the document file value matches correctly, it will channel toward retrieving the content of the document. The activity task is Content Integration Task from the ECM server with an operation of get document content, which returns the content. The content returned from the ECM server is in binary format, so it’s converted to a text string with the script shown in Listing 2:

Listing 2. Conversion script (binary to text)

var str = tw.local.content;
var byteValue =;
var content64 =;
var value = new java.lang.String(content64, "UTF‑8");
tw.local.outputContent = value;

In this Letter of Credit document example, the sample data are stored in the format shown in Figure 12:

Figure 11. How sample data are stored

The sample script to extract value from the data format is shown in Listing 3:

Listing 3. How sample data are stored

var str = tw.local.outputContent;
var content = str.split(",");

var shipped_date_value= content[0].split("=");
tw.local.shippedDate = shipped_date_value[1];

var processing_date_value= content[1].split{"=");
tw.local.processingDate = processing_date_value[1];

var amount_claim_value= content[2].split("=");
tw.local.claimAmountClaim = amount_claim_value[1];

var received_date_value= content[3].split("=");
tw.local.receivedDate = received_date_value[1];

The output content is made available to Validate Document Service Flow. This service flow verifies the metadata code and invokes ODM Decision Service with the business rules (shown previously) to verify the status of the document. If the status verification were invalid, it would flow to Invalid Document Service Flow, which sends a transaction to blockchain with status “Invalidate Document” and the document’s valid status is set to false. If the status verification is valid, it would flow to Validate Letter of Credit Human Service as shown in Figure 13:

Figure 12. A valid status verification

All the text data in the content are mapped to the appropriate fields in the user interface, so the Buyer’s Bank can make the decision whether to approve. If not approved, it flows to Invalid Service Flow. If approved, it flows to Transaction Validate LOC Service Flow and then to Payment Service Flow to complete the process.


IBM Business Process Manager users can take advantage of the latest blockchain technology seamlessly. You can define and implement your own business processes rules and integrate with blockchain to manage assets. This Letter of Credit scenarioused blockchain to store validity metadata regarding a physical legal contract stored in an enterprise content repository, thus allowing the system to verify that the contract has not been changed or altered.

Next steps

Ready to start developing your own blockchain use case?