Table of Contents

Sample 1 : Calculations

Sample 2 : Raspberry Pi GPIO

Sample 3 :


Sample 1 : Calculations

Chan N. Nguyen has built a nice BPEL tutorial and deployed several services which can be easily orchestrated to illustrate BPEL concepts.

Calculation Services

Chorus.js allows you to create simple services (or stub more complex services) using a simple API/Service Definition Language. Our model is a bit different from WSDL. One of the core design goals of Chorus.js is to deal effectively with versioning which is a very hard problem to crack in distributed systems and has not been dealt with effectively so far. Hence, an API (or a Service) is a set of versions, each version can have a different interface. The unit of reuse of our SDL is the operation, not the interface like in WSDL. A version may also have “variants”, but we’ll introduce this concept at a later time. Each operation has a set of messages (input, output and faults), each message is composed of parts which have a type (e.g an Entity definition). Entities themselves can be versioned and referenced as such from the message definitions.


This is the kind of code generated by Chorus.js from an API/Service definition:

[code language=”js”]

var express = require(‘express’);
var sr = express.Router();

var log4js = require(‘log4js’);

appenders: [
{ type: ‘console’ },
{ type: ‘file’, filename: ‘logs/compute.log’, maxLogSize:20480, backups:3, category: ‘services’ }

var logger = log4js.getLogger();

sr.get(‘/add’, function(req,res) {

var a = req.query.a ;
var b = req.query.b ;
var mult = parseFloat(a) + parseFloat(b);
res.set( {"Content-Type" : "application/json;charset=UTF-8"} );
var respMessage = ‘{"addResponse":{"ouput":"’+ mult.toString() + ‘"}}’ ;
logger.trace("[SERVICE] response from /services/add:"+respMessage);

The SDL sample contains 5 APIs: add, subtract, multiply, divide and square.

[table caption=”Downloads for this section”]
API definition,computation.cord
Generated API implementation,compute_v1_0.js

Your First Orchestration

Let’s start with a very simple orchestration, an orchestration that invokes a single API, the “multiply” API. The orchestration definition is as follows:



The concepts are relatively simple:

  • A process definition declares the services and variables it uses
  • It’s root activity is in this case a sequence (of activities)
  • The sequence is as follows:
    • wait to receive a request
    • assign the values to the multiply request
    • assign the response (from the multiply service) to the orchestration’s reply
    • return the reply
  • That’s it folks!

Chorus.js is orchestration for humans.

[table caption=”Downloads for this section”]
calculateArea’s Cord,calculateArea.cord

If you use docker, we have prepared an image that contains node, mongodb and this sample.
You can either run our install script in the directory in which you want to install and run this sample:

$ cd /directory/of/the/sample
$ curl | sh

or you can enter the same instructions manually:

$ cd /directory/of/the/sample
$ mkdir logs

[copy the sample files in the calculatearea directory]

$ npm install
$ node calculateArea_v1.js

At that point you should see in the terminal window:

[2014-05-26 05:33:15.537] [WARN] [default] - [ENDPOINT] calculateArea_calculateRectangleArea_receive
[2014-05-26 05:33:15.540] [WARN] [default] - [ENDPOINT] calculateArea_calculateArea_invoke
[2014-05-26 05:33:15.544] [WARN] [default] - [SERVER] listening on port 3000

Note that Chorus.js expects MongoDB to be listening on the standard port: 27017 and that you created a database named “chorus”. You can use Robomongo to manage your MongoDB instances.

Now you can test everything is running properly by POSTing some values to the orchestration:

curl -H "Content-Type: application/json" -d '{ "input" : { "a" : "60" , "b" : "200" }}' http://localhost:3000/calculateArea/v1/receive/calculateRectangleArea 


If all goes well, you should see a record like that one in the chorus database. This is the context of the API orchestration.


Now, let’s implement the full calculation Chan Nguyen used in his BPEL tutorial. Here we’ll use a single sequence to perform the entire orchestration. In the next section we will use a (parallel) flow like in his sample.

The formula of the calculation is:


And the new process definition is as follows:


Of course, Chorus.js generated the PlantUML sequence diagram:



The new cord definition can be downloaded here.

Sample 2: Raspberry Pi GPIO

Here is a fun project you can do with an entry level Raspberry Pi board. In this project you’ll learn how to create a set of APIs which control the Raspberry Pi GPIOs and an orchestration which turns on and off a LED connected to one of the output ports of the board’s GPIO.

We use a a kit such as this one.

Disclaimer: Unless you know what you are doing, there is a great probability to damage your board if you connect pins incorrectly

Here is what our project looks like:



Chorus.js generates a complete environment (APIs+Orchestration) which is deployed to and therefore runs on the Raspberry Pi.


Figure 2.1 Architecture of the Raspberry Pi project

sd          Figure 2.2. API Orchestration

Let’s start by implementing a service that will control the LED. Conveniently, there are several node.js modules which can be used to read or write to the board’s IOs. We used the rpi-gpio module.

The service implements three operations: turnOn, turnOff and read

serviceFigure 2.3. The service definition

We introduce here a new module concept: the service definition references the gpio module which is defined as follows:


This code is added to the generated service code. The name of the module is used as:

var moduleName = requires('moduleName') ;

If the name of the module is different, you need to use add a module statement such as above:

var gpio = requires('rpi-gpio') ;

You can then invoke these functions from the operation implementation:


You can also take a look at the message and entity definitions:



You are now ready to orchestrate these APIs:


The last step is to define the environment in which the service and the orchestration will be deployed:


[table caption=”Downloads for this section”]
switch’s Cord,raspberrypi.cord


You are now ready to deploy the files to your Raspberry Pi. We use the Arch Linux distribution. We successfully installed Node.js and MongoDB

All you need to do is add the rpi-gpio module:

$ npm install rpi-gpio

You may run into an error if the time is not initialized properly on your raspberry pi. Depending on its configuration it will not pick up the time from the network and npm will fail if the computer time is set to 1970.

We highly recommend that you install the GPIO utility to be able to troubleshoot your electronics. The “gpio reset” command is pretty handy…

After that, just type

$ npm start

and you should see something like that:


You can curl a request like that one:

POST /turnOnOff/v1/receive/switchRequest HTTP/1.1
Content-Type: application/json
{ "input" : { "IOPort" : "18"}}

Here are some more details to complete the project. Our GPIO service uses 4 pins:

  • Pin 1: 3.3V
  • Pin 6: GND
  • Pin 12: BCM GPIO18 (configured as an input)
  • Pin 24: BCM GPIO08 (configured as an output)

We turned off the ability to read/write other pins, but the code is easy enough to modify to use the port value passed in the API invocation should you want to extend the project.

Raspberry Pi boards come in different sizes and shapes. We recommend that you check your connector rather than trusting our schematics.


The input as such is configured with a switch to change its value:


A LED is mounted on the output. The cord should turn the LED on, then off.



Leave a Reply