quickstart guide: integrating onetransport data ......this quickstart guide explains how to...

Chordant, Inc. All Rights Reserved.

Quickstart Guide: Integrating

oneTRANSPORT Data Marketplace with

Node Red

This quickstart guide explains how to integrate oneTRANSPORT Data Marketplace with

your own application using Node Red. In this guide, you will learn to create a Node Red

flow that receives notifications of new data from oneTRANSPORT Data Marketplace

using the oneM2M standards-based APIs. The flow will check to see if the oneM2M

request is a result of validating a subscription or if it is a notification of new data. It will

then send the appropriate response back to oneTRANSPORT Data Marketplace. It will

also output that data to a dashboard. When you're done, your flow will look like this

workflow:

To follow this quickstart guide, you will need:

• An account on the oneTRANSPORT Data Marketplace service:

https://service.onetransport.io

• Access to a Node Red instance.

Sign in to Node Red

Sign in to your Node Red instance.

https://service.onetransport.io/


Create a new Flow

1. From the main Node Red menu, choose Flows > Add.

2. Double Click on the header of the new Flow and rename your flow to

oneTRANSPORT Integration.

Next, add a HTTP Input node that fires when a new web service request is called. Every

Node Red flow must start with a node that can be instantiated.


Check HTTP Request

1. On the pallet, enter "http" in the search box. Select the node:


2. Open the http node that is on the canvas (double click), and provide this

information for your trigger as shown and described:

Setting Value Description

Method POST The oneM2M standards defines this method as a

POST. oneTRANSPORT will POST data to this web

service.

URL /subscription This is the name of the endpoint that shall be used as

a web service.

Relative

Path

oneTRANSPORT web

service

The name of the node itself.

Together, the Method and URL define how your flow's node is instantiated. This

flow will process web service calls to the http input end point.

3. Deploy your flow. In Node Red, click on the Deploy button. Your flow is now live

but doesn't do anything other than make the http input node available as an end

point on the Internet. So, add a condition that responds when the web service

fires.


Add a condition

Now add a condition that checks the Response Body of the Request to see if the current

request is a subscription validation or a notification of new data.

When you create a subscription request in oneTRANSPORT Data Marketplace using

oneM2M APIs, the end point used for the subscription (the Request you just created) is

first called to ensure that it accepts the Subscription request. The same Request end

point is then called each time a new piece of data is added to oneM2M system for the

subscription.

1. Search the pallet for “switch” and drag the switch node onto the canvas. Connect

the switch node to the oneTRANSPORT web service node.

2. This will create an empty conditional switch node. Connecting the node to the end

of the oneTRANSPORT web service node means that when your web service is

called, the first thing that it does is go to the switch node.

When oneTRANSPORT sends a oneM2M subscription validation request to your end

point, you can identify that the Request is a subscription validation by checking the

request body for "vrq":true .


3. Provide this information for your switch as shown and described:


Name Subscription or

notification

request?

The descriptive name of the node.

Property msg.req.body This defines that the conditional checks shall be

carried out against the req.body object of the msg.

For a http input node, the req.body object is the

HTTP Request body

Condition contains The condition will carry out a comparison between

the Item and the Value

Value "vrq":true When oneM2M validates a subscription, the request

body contains “vrq”:true


So far you have added just a single condition which outputs to the first output. So

add another condition for everything else.

4. Select +Add and then select otherwise in the condition drop down box. Save

the node by clicking on Done.

You will see that the node now has two outputs. The flow will follow the first output if it

finds “vrq”:true in the request body (oneM2M Subscription Request), it will follow the

second output for oneM2M Notification requests.


Send a response for subscriptions

For a subscription validation response, oneM2M APIs have the following requirements:

• The HTTP Status Code sent as the response must be 201.

• There must be a response header named X-M2M-RSC and this value must be

2001.

• There must be a response header named X-M2M-RI and this value must be the

value of the request header named X-M2M-RI.

1. On the pallet enter "function" in the search box. Select the function node and

drag it on to the canvas. Then connect the 1st output of the Subscription or

notification request? node to the function node.


2. Open the function node and provide this information for your switch as shown:


Name Subscription Request The descriptive name of the node.

Function // This is the response sent

back to oneTRANSPORT.

msg.payload = "Subscription

Requested"

// Return the headers sent with

the Request to the Response.

msg.headers = msg.req.headers

return msg;

This code sets the HTTP Response

Body and the HTTP Response

Headers that shall be returned to

the HTTP Request.

Outputs 1 There will be just one output from

this function.

Select Done and the function shall be saved. You will now need to connect a node that

sends the response back to the HTTP Request.


3. On the pallet enter "http response" in the search box. Select the http response

node and drag it on to the canvas. Then connect the output of the Subscription

Request node to the function node.

4. Open the http response node and provide this information for your switch as

shown:



Name blank You can leave this blank as it will be named http (201) by

default

Status

Code

201 This is the HTTP response code sent back to oneTRANSPORT.

As explained earlier, oneM2M requires Subscription Request

to return a code of 201.

Header X-M2M-RSC The oneM2M standards require this header to be set as a

response to a Subscription Request.

Value 2001 The oneM2M standards require this header to be set to 2001

as a response to a Subscription Request.

You have now set up a flow that will provide a response to the oneTRANSPORT Data

Marketplace when a Subscription Request is made.

You will now follow similar steps to set up the response for a Notification.

Send a response for notifications

oneTRANSPORT Data Marketplace uses oneM2M APIs to send notifications of new data

to users that have subscribed to a particular Datasets Distribution.

The HTTP Request end point that you created is used for Notifications as well as

subscriptions. You created a condition that asks “Is this a subscription?” and followed

the steps required to send a response back to oneTRANSPORT Data Marketplace using

oneM2M APIs. You shall now create a response for Notifications. A Notification is sent

each time a new piece of data arrives in a oneM2M Container. The Notification will call

the Request end point that you have set up.


For a notification response, oneM2M APIS have the following requirements:

• The Status Code send as the response must be 200.

• There must be a response header named X-M2M-RSC and this value must be

2000.

• There must be a response header named X-M2M-RI and this value must be the

value of the request header named X-M2M-RI.

1. On the pallet enter "function" in the search box. Select the function node and

drag it on to the canvas. Then connect the 2nd output of the Subscription or

notification request? node to the function node.


2. Open the function node and provide this information for your switch as shown:


Name Notification The descriptive name of the

node.

Function // This is the response sent

back to oneTRANSPORT.

msg.payload = "Notification

Requested"

// Return the headers sent with

the Request to the Response.

msg.headers = msg.req.headers

return msg;

This code sets the HTTP

Response Body and the HTTP

Response Headers that shall be

returned to the HTTP Request.

Outputs 1 There will be just one output

from this function.

Select Done and the function shall be saved. You will now need to connect a node that

sends the response back to the HTTP Request.


3. On the pallet enter "http response" in the search box. Select the http response

node and drag it on to the canvas. Then connect the output of the Notification

node to the function node.

4. Open the http response node and provide this information for your switch as

shown and described:



Name blank You can leave this blank as it will be named http (200) by

default

Status

Code

200 This is the HTTP response code sent back to oneTRANSPORT.

As explained earlier, oneM2M requires Subscription Request

to return a code of 201.

Header X-M2M-RSC The oneM2M standards require this header to be set as a

response to a Notification.

Value 2000 The oneM2M standards require this header to be set to 2000

as a response to a Notification.

You have now set up a flow that will provide a response to oneTRANSPORT Data

Marketplace when a Notification is made.

You can now go ahead and extend this flow so that you can process the data as it

comes in from a oneTRANSPORT Data Marketplace Notification. To do this, you will

need to connect some additional nodes to the output of the function nodes as indicated

below:


In the example below, we send an email when a notification is received, and insert a

record into a MongoDB database.

If you do not have an application to integrate with at present, then add a debug node to

the output from the oneTRANSPORT web service node. You will then be able to

watch a Subscription Request and Notifications being processed in the Debug pane in

Node Red.

You will now create a subscription request in oneTRANSPORT Data Marketplace to send

data to the Node Red Flow that you created.

Sign in to the oneTRANSPORT Service web site

Sign in to the oneTRANSPORT service web site with your account credentials.

https://service.onetransport.io/


Create a subscription for data on oneTRANSPORT Data

Marketplace

1. From the oneTRANSPORT menu, choose Data Catalogue > Browse full catalog


2. Choose a Dataset that you would like to receive notifications for and choose Accept

Licence.

3. Review the license that is associated with this Dataset, and if you agree select agree and

accept > accept


4. Click on the Distribution that you would like to subscribe to, and this will load the

oneM2M Browser.

5. In the oneM2M Browser, select App > Container > Subscribe


6. Enter the details for the web service end point that you created within Node Red, and

the subscribe. This will send a subscription request through to the Node Red flow.

The result

• When you entered the URL for your Node Red Flow App HTTP Request end point

into oneTRANSPORT Data Marketplace, Node Red would have received the

subscription request. If you added Debug nodes, then you will see the output in

the Debug pane.

• Each time a new data transaction is entered into oneM2M on oneTRANSPORT

Data Marketplace for the Container that you have subscribed to, your end point

will be called, and you will receive output in the Debug pane.

Congratulations, you've now successfully built and run your Node Red integration with

oneTRANSPORT Data Marketplace using the oneM2M APIs!

Get support

• For oneTRANSPORT Data Marketplace questions email: [email protected]

• For Node Red questions, visit the Node Red Community.

mailto:[email protected]

https://nodered.org/about/community/

quickstart guide: integrating onetransport data ......this quickstart guide explains how to...

Documents