How to use Cumulocity in your workflow

Cumulocity is an independent device and application management IoT platform that lets you connect and manage your devices efficiently, and control them remotely. Using its prime features such as data visualization, data collection, and real-time analytics, you can rapidly deploy your IoT devices with ease. 

Built.io Flow - Cumulocity Integrations

Built.io Flow recently teamed up with Cumulocity to make your IoT integration experience even smoother. With the newly introduced Cumulocity actions you can now easily manage your devices and use them to automate your routine tasks.

In this guide, we will understand how to connect your IoT devices with the Built.io Flow platform and use the data from those devices in workflows using the Cumulocity actions. 

Let’s say you want to control your smartphone remotely. To do so, we will connect it with Cumulocity using Built.io Flow.

Registering your Device with Cumulocity

To use Cumulocity actions, you need to first register your device (in this case, your smartphone) with Cumulocity. Follow the steps given below to achieve this:

Step 1: Download the Cumulocity Cloud Sensor app on your device. When you launch the app, you will be redirected to the Cumulocity website where you will be prompted to register your device with Cumulocity using one of the following options:

1. Scan a QR Code
2. Web-based Registration 

Step 2: Once you have scanned the QR code/completed registration, a unique device ID will be sent to your device. This device ID will be later used to connect your device with Built.io Flow. With this, your device is successfully registered with Cumulocity.

You can now start using the Cumulocity actions for this device, in your workflows.

Configuring Cumulocity Actions

To use your registered device in Cumulocity actions, follow the steps given below:

Step 1: Navigate to Built.io Flow canvas and drag-and-drop the Add Device Request and Accept Device Request actions listed under the Cumulocity connector. Next, drag the Delay action to the canvas and connect these actions as shown below:

We will start by adding the device on Cumulocity. To do so, we will configure the Add Device Request action.

Step 2: Double-click the Add Device Request action icon and click the Add New option given under the Connect to Cumulocity field to create a Cumulocity authorization. 

In the Device ID field, enter the unique device ID available in the Cumulocity Cloud Sensor app installed on your device.

Step 3: Once this is done, click NEXT. You can optionally check if the configured action is working as expected by clicking TEST in the next screen. (Learn how to test actions). After this, click DONE.

Since the Add Device Request action sometimes takes a couple of seconds to send and receive data, we will add a delay of five seconds to our workflow.

Step 4: Double-click the Delay action icon and enter 5 as input in the Time in Seconds field. Once this is done, click NEXT and click DONE.

Next, we will accept the add device request raised earlier using the Add Device Request action.

Step 5: Open the Accept Device Request action, select the existing Cumulocity authorization in the Connect to Cumulocity, and pass the id key parameter in the Device ID field by clicking on it. The id key is listed under the Add Device Request action output given on the right-hand side of the configuration window.

Once this is done, click NEXT, and click DONE.

Step 6: After this, save the workflow and execute it. On successful execution, you will see the workflow output in the debug panel of your canvas. You can also click on the action name to see the detailed output of each action.

At this point, if you click the Accept Device Request action name in the debug panel, you will see the value of the status key as “ACCEPTED”, which means your device is successfully added to Cumulocity.  

Now that your device is added to Cumulocity, whenever you access your Cumulocity account or Cloud Sensor app, you will be redirected to the Sensor smartphone dashboard screen where you can see the MAP, SIGNAL, and other details of your device. 

Once your device is added to Cumulocity, you can start using the Cumulocity listeners and other Cumulocity actions to create smart IoT integrations. Let’s quickly glance through the procedure to set up Cumulocity listeners for your workflow.

Configuring Cumulocity Listeners

The process of setting up the Cumulocity listener for your workflow is similar to setting up an external web service triggers.

Let’s understand how to do it with the help of an example. Let’s say you want to receive notifications on your Cisco Webex Teams space whenever your IoT device sends a warning. To do so, follow the steps given below:

Step 1: Create a blank workflow and double-click on the Start icon. Select Cumulocity from the list of trigger services and listeners that appear, and configure it as given below:

Cumulocity Listener: The value of this field is set to Subscribe by default.

Connect To Cumulocity: Select/add the Cumulocity authorization.

Event Type: Select the event type for which you want to set up the trigger. Currently, Alarm, Event, and Measurement event types are supported. Since we want to receive notification when our device sends a warning, we will select the Alarm event type.

Device ID: Enter the device ID of your IoT device available in your Cumulocity account or Cumulocity Cloud Sensor app.

Once this is done, click SAVE. This will set up the Cumulocity listener for the selected device. You can optionally TEST the configured listener to see if it is working as expected. After this, click DONE.

Since we want to receive device warnings on our Cisco Webex Teams space, We will now add the Cisco Webex Teams - Post New Message action to the workflow.

Step 2: Drag-and-drop the Cisco Webex Teams - Post New Message action on canvas and connect it to the Cumulocity listener, we just set up.

Step 3: Double-click the action icon to start configuring it. 

Select/add the Cisco Webex Teams authorization in the Authorize Cisco Webex Teams field and select the space on which you want to receive device notifications using the Space ID field. 

In the Message field, add the text key listed under the Trigger Data - Subscribe on the right-side of the configuration window. This key contains the notification message sent by your IoT device.

Once this is done, click NEXT and click DONE. 

With this, your workflow is set up. Now whenever your connected device sends a warning, you will receive the notification on your chosen Cisco Webex space.