IBM Cloud Actions

An example integration where a Data Connector forwards events to an IBM Cloud Action.

Overview

This example uses a Data Connector to forward the events of all devices in a project to an IBM Cloud Action. When receiving the HTTPS POST request, our action will verify both the origin and content of the request using a Signature Secret, then decode the data.

Prerequisites

The following points are assumed.

You have a Role of Project Developer or higher in your DT Studio project.
You are familiar with the Introduction to Data Connectors and know how to Create a Data Connector.
You are familiar with the IBM Cloud Functions documentation.

IBM Cloud Platform

While there are many advantages to using a local environment for development, this guide will use the browser portal to minimize setup requirements.

Create a Cloud Action

In the cloud functions dashboard, create and deploy a new Action with one of the following runtimes.

Python 3.11
Node.js 16

Edit Source Code

Once deployed, replace the code of your new Action with that matching your runtime. The implementation is explained in detail on the Data Connector Receiving Events page.

import base64
import hashlib
import jwt


def verify_request(body, token, secret):
    # Decode the token using signature secret.
    try:
        payload = jwt.decode(token, secret, algorithms=["HS256"])
    except Exception as err:
        print(err)
        return False

    # Verify the request body checksum.
    m = hashlib.sha1()
    m.update(base64.b64decode(body.encode('ascii')))
    checksum = m.digest().hex()
    if payload["checksum"] != checksum:
        print('Checksum Mismatch')
        return False

    return True


def main(request):
    # Extract necessary request information.
    token = request['__ow_headers']['x-dt-signature']
    body = request['__ow_body']
    secret = request['DT_SIGNATURE_SECRET']

    # Validate request origin and content integrity.
    if not verify_request(body, token, secret):
        return {'statusCode': 400}
    #
    # Further processing here.
    #

    return {'statusCode': 200}

const crypto = require('crypto')
const jwt = require('jsonwebtoken')
  
function verifyRequest(body, token, secret) {
    // Decode the token using signature secret.
    let decoded
    try {
        decoded = jwt.verify(token, secret)
    } catch(err) {
        console.log(err)
        return false
    }
    
    // Verify the request body checksum.
    let shasum = crypto.createHash('sha1')
    let checksum = shasum.update(JSON.stringify(body)).digest('hex')
    if (checksum !== decoded.checksum) {
        console.log('Checksum Mismatch')
        return false
    }
    
    return true
}

function main(params) {
    // Extract necessary request information.
    let buff   = new Buffer.from(params['__ow_body'], 'base64')
    let body   = JSON.parse(buff)
    let token  = params['__ow_headers']['x-dt-signature']
    let secret = params['DT_SIGNATURE_SECRET']
    
    // Validate request origin and content integrity.
    if (verifyRequest(body, token, secret) === false) {
        return {statusCode: 400}
    }
    
    //
    // Further processing here.
    //

    return { statusCode: 200 }
}

Add Parameter

Parameters are default values stored safely on IBM's servers. Once a request is received, it is merged with the incoming dictionary. Add a new parameter with the following Name and Value.

Name: DT_SIGNATURE_SECRET
Value: A unique password. We will use it later, so write it down.

Configure Endpoint

Under the Endpoints tab, toggle Enable as Web Action and Raw HTTP handling. Copy the HTTP Method URL and save it for later as we will use it when configuring our Data Connector.

Data Connector

To continuously forward the data to our newly created Cloud Action, a Data Connector with almost all default settings is sufficient. If you are unfamiliar with how Data Connectors can be created, refer to our Creating a Data Connector guide. The following configurations should be set.

Endpoint URL: The HTTP Method URL found in the previous step.
Signature Secret: The value of DT_SIGNATURE_SECRET parameter set earlier.

Depending on your integration, it can also be smart to disable the event types you are not interested in. For instance, the NetworkStatusEvent is sent every Periodic Heartbeat and will by default be forwarded by the Data Connector if not explicitly unticked.

Test the Integration

If the integration was correctly implemented, the Success counter for your Data Connector should increment for each new event forwarded. This happens each Periodic Heartbeat or by touching a sensor to force a new event.

If instead the Error counter increments, a response containing a non-200 status code is returned.

Verify that the Data Connector endpoint URL is correct.
IBM Cloud provides a host of tools that can be used to monitor Functions. Check the logs for any tracebacks that could explain why an error is returned.

Next steps

Your sensor data is now in the IBM Cloud environment, and you can start using it in their various services. Fortunately, IBM has some well-documented guides to get you started.

PostgreSQL Database

A database should be tailored to each specific use case. However, if you're uncertain, PostgreSQL (Postgres) is a good place to get started. The following guides will show you how to create a new Postgres database, then connect your Cloud Action to execute queries.

Last updated 1 year ago