IBM Blockchain Developing Applications Workshop - Node-Red Integration Exercise Guide
Contents INSTALLING COMPOSER NODE-RED NODES... 4 INTEGRATE NODE-RED WITH COMPOSER BUSINESS NETWORK... 7 APPENDIX A. NOTICES... 19 APPENDIX B. TRADEMARKS AND COPYRIGHTS... 21 Page 2 IBM Blockchain Developer Workshop Node Red Integration v1.0
Node-Red and Composer Nodes Node-Red is a programming tool for wiring together hardware devices, APIs and online services. Per the Node-Red website (https://nodered.org/about/ ), Node-RED consists of a Node.js-based runtime that you point a web browser at to access the flow editor. Within the browser you create your application by dragging nodes from your palette into a workspace and start to wire them together. With a single click, the application is deployed back to the runtime where it is run. The palette of nodes can be easily extended by installing new nodes created by the community and the flows you create can be easily shared as JSON files. Composer provides three Node-Red nodes that can connect and interact with a Composer Business Network in many ways. The first is Hyperledger-Composer-Out, which allows you to create or update assets or participants and submit transactions. The second is Hyperledger-Composer-Mid, which allows you to get assets or participants from a registry. The third is Hyperledger-Composer-In, which allows you to subscribe to events from a blockchain. The Composer nodes can be found in the Node Package Manager (NPM) under the tag of node-red-contrib-composer. For the latest download and capabilities visit the NPM package at https://www.npmjs.com/package/node-red-contrib-composer. In the sections below we will install and configure the Composer Node-Red, specifically the Hyperledger- Composer-Out node to create participants and assets for the Trade Network. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 3
Installing Composer Node-Red Nodes 1. To get started with Node-Red we need to install it using NPM. Issue the following command to install Node-Red globally to the VM. npm install node-red -g 2. To launch Node-Red type node-red at the command line. The output to the screen should be like the text below. tecroot@tecroot-virtual-machine:~$ node-red 8 Oct 18:02:23 - [info] Welcome to Node-RED =================== 8 Oct 18:02:23 - [info] Node-RED version: v0.17.5 8 Oct 18:02:23 - [info] Node.js version: v6.11.3 8 Oct 18:02:23 - [info] Linux 4.10.0-35-generic x64 LE 8 Oct 18:02:24 - [info] Loading palette nodes 8 Oct 18:02:24 - [warn] ------------------------------------------------------ 8 Oct 18:02:24 - [warn] [rpi-gpio] Info : Ignoring Raspberry Pi specific node 8 Oct 18:02:24 - [warn] ------------------------------------------------------ 8 Oct 18:02:24 - [info] Settings file : /home/tecroot/.node-red/settings.js 8 Oct 18:02:24 - [info] User directory : /home/tecroot/.node-red 8 Oct 18:02:24 - [info] Flows file : /home/tecroot/.node-red/flows_tecroot-virtualmachine.json 8 Oct 18:02:24 - [info] Creating new flow file 8 Oct 18:02:24 - [info] Starting flows 8 Oct 18:02:24 - [info] Started flows 8 Oct 18:02:24 - [info] Server now running at http://127.0.0.1:1880/ 3. In the terminal output a message will indicate that Node-Red server is now running at http://127.0.0.1:1880/. Right click on the link in the terminal to launch or copy and paste the link into a browser. Page 4 IBM Blockchain Developer Workshop Node Red Integration v1.0
After opening the URL, you will see the Node-Red editor. The editor has several different sections to it. On the left, you will see many input and output nodes that come with the Node- Red by default. In the middle, you will see a flow editor where nodes will be wired together to create flows. On the far right is an info and debug tabs along with a Deploy button. More information on Node-Red can be found online at https://nodered.org/docs/ 4. 5. Return to the terminal and stop Node-Red by issuing the Ctrl + C command. Before we can create a flow to integrate into a Composer Business Network we first need to install the Composer Node-Red nodes. Normally, we would do this right in the Node-Red editor via Menu -> Manage palette -> Install tab -> node-red-contrib-composer. To maintain the correct levels of Composer in the lab we will instead install the Composer nodes from the command line. In a terminal change directory to the node_modules directory under the default install location for Node-Red, ie ~/.node-red/. cd ~/.node-red/node_modules/ 6. To install the version specific Composer nodes for this lab, issue the following command to install from NPM. npm install node-red-contrib-composer@0.0.6 7. To confirm the correct Composer versions have been installed, issue the following command. npm list node-red-contrib-composer 8. Restart Node-Red from the command and open the browser to URL http://127.0.0.1:1880/ $ node-red IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 5
9. To confirm the Composer nodes have been installed use the node search in the upper left corner of the editor by typing composer and the following nodes should be shown. 10. You have successfully installed the Composer Node-Red nodes. Page 6 IBM Blockchain Developer Workshop Node Red Integration v1.0
Integrate Node-Red with Composer Business Network Now that we have the Composer Node-Red nodes installed we can start to use them in an integration flow to a running business network. In the steps below we will create a flow that will read flat files containing JSON data structures and process them as participants and assets into the Composer Business Network. 1. To read from a directory on the file system, we will need another Node-Red node called filelister. Click on the menu icon install the nodes and select Manage palette. This would give us an option to 2. Search for node-red-contrib-fs under the Install tab. Click the install button at both screens as shown below. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 7
3. To confirm the node was installed search under the storage section of the node to find the node fs file lister as shown below. 4.. To start this flow, we will need to use the input node Inject. From the file editor drag the Inject node onto the flow editor, as shown below. The Inject node can initiate a flow with a specific payload value. The default payload is a timestamp of the current time and that is also the default name of the node. Page 8 IBM Blockchain Developer Workshop Node Red Integration v1.0
5. Double click on the node to edit. In the editor, under the Name field, enter the name Start. Click on the Done button to save the changes. 6. Next, drag the fs file lister node to the flow editor. The default name will be File Lister, as shown below. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 9
7. Double click on the File Lister node to edit it. In the Start Folder field add the directory path /home/tecroot/workshop/lab5/json/trader/. In the File Pattern field had the string *.json (make sure to include the dot). Lastly, update the Name file with the string Read JSON Files. Click the Done button to save. At this point you flow editor should look like the following. Page 10 IBM Blockchain Developer Workshop Node Red Integration v1.0
8. Next, find the change node and drag it onto the flow editor. The default name will be set msg.payload, as shown below. 9. Double click the change node to edit. Update the Name field to Set Filename. In the Rules section update the rules so both dropdowns have msg selected, along with the top text box to filename and the bottom text box to payload, as shown below. Click Done to save. 10. Next, drag the file in node highlighted below to the flow editor. The default name will be file, as shown below. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 11
11. Double click the file node to edit. Check the box next to Send message on error and update the Name field to Read JSON File, as shown below. The Filename field will be left blank as we have set the msg.filename value in the previous node, ie Set Filename. Click Done to save. 12. Next, drag the json node to the flow editor. The default name will be json, as shown below. 13. Double click the json node to edit. Update the Name field to Set JSON and check the box next to Format JSON string, as shown below. Click Done to save. Page 12 IBM Blockchain Developer Workshop Node Red Integration v1.0
14. Lastly, drag the Composer out node onto the flow editor, as show below. 15. Double click the Composer node to edit. Click on the pencil icon to add a new composer config node. 16. The Composer config node provides fields for a Connection Profile, Business Network, User ID and User Secret. As with the previous lab we will use the hlfv1 profile, trade-network for the Business Network, and ID and Secret of admin / adminpw. Update all the defaulted fields as shown below and click the Add button. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 13
17. The Composer Profile now lists hlfv1:trade-network. Update the Name field to Create Trader and leave the Action Type to Create. Click the Done button. 18. Double click on the Flow 1 tab at the top of the node flow to edit. Update the Name field to be Create Trader. Click the Done button. 19. From the flow editor connect each node together by connecting the end of the first node to the start of the next node. The flow should look like the following. Page 14 IBM Blockchain Developer Workshop Node Red Integration v1.0
20. Now that we have the flow completed we need to deploy the flow to the Node-Red runtime. Click on the Deploy button. A successfully deployed message should be displayed. 21. Now we are ready to invoke the Create Commodity flow by clicking the check box next to the Start node. 22. To check that the traders have been loaded into the trade-network the Composer CLI command of composer network list can be issued with the following parameters. composer network list -n trade-network -p hlfv1 -i admin -s adminpw As you can see from the output under the registries section, many new traders have been loaded IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 15
23. To create the same Node-Red flow for Commodities we will copy the existing flow for Traders and make some minor changes. To copy the flow, in the editor select all the nodes of the Trader flow and press Ctrl + C to copy. You should see a message at the top of the screen that says 6 nodes copied 24. Click a new editor tab by clicking the + button on the right side of the editor. 25. 26. Paste the copied nodes into the new flow editor tab using Ctrl + V. Rename the flow by double clicking current name tab to edit. Update the Name field to be Create Commodity. Click the Done button. Page 16 IBM Blockchain Developer Workshop Node Red Integration v1.0
27. You should now have a flow that looks like the image below. 28. Update the Name field in the Composer Node for Create Trader to Create Commodity. Click the Done button. 29. Double click on existing Read JSON Files node to edit it. In the Start Folder field update the directory path to /home/tecroot/workshop/lab5/json/commodity/. Click the Done button to save. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 17
30. The update flow should now look like the image below. Click on the Deploy button and then click the Start node to invoke the Create Commodity flow. 31. We can again use the Composer CLI command of composer network list to see the loaded commodities using the following command. composer network list -n trade-network -p hlfv1 -i admin -s adminpw As you can see from the output below, several new commodities have been loaded. 32. Congratulations! You have successfully used Node-Red nodes to integarte into a Composer Business Network. Page 18 IBM Blockchain Developer Workshop Node Red Integration v1.0
Appendix A. Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 19
products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM's future direction and intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. All references to fictitious companies or individuals are used for illustration purposes only. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. Page 20 IBM Blockchain Developer Workshop Node Red Integration v1.0
Appendix B. Trademarks and copyrights The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM AIX CICS ClearCase ClearQuest Cloudscape Cube Views DB2 developerworks DRDA IMS IMS/ESA Informix Lotus Lotus Workflow MQSeries OmniFind Rational Redbooks Red Brick RequisitePro System i System z Tivoli WebSphere Workplace System p Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of The Minister for the Cabinet Office, and is registered in the U.S. Patent and Trademark Office. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom. Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries. IBM Blockchain Developer Workshop Node Red Integration - V1.0 Page 21
NOTES
NOTES
Copyright IBM Corporation 2014. The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml.