quickstart guide: integrating onetransport data ......this quickstart guide explains how to...
TRANSCRIPT
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.
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
Check HTTP Request
1. On the pallet, enter "http" in the search box. Select the node:
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
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 .
Chordant, Inc. All Rights Reserved.
3. Provide this information for your switch as shown and described:
Setting Value Description
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
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
2. Open the function node and provide this information for your switch as shown:
Setting Value Description
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.
Chordant, Inc. All Rights Reserved.
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:
Chordant, Inc. All Rights Reserved.
Setting Value Description
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.
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
2. Open the function node and provide this information for your switch as shown:
Setting Value Description
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.
Chordant, Inc. All Rights Reserved.
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:
Chordant, Inc. All Rights Reserved.
Setting Value Description
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:
Chordant, Inc. All Rights Reserved.
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.
Chordant, Inc. All Rights Reserved.
Create a subscription for data on oneTRANSPORT Data
Marketplace
1. From the oneTRANSPORT menu, choose Data Catalogue > Browse full catalog
Chordant, Inc. All Rights Reserved.
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
Chordant, Inc. All Rights Reserved.
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
Chordant, Inc. All Rights Reserved.
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.