Integration Guide: Sending Cumulocity IoT Alarms to Zendesk & Twilio using n8n

[Tamer_Mazen]

Use Case

Let’s imagine we work for a company called “SAG Demo”, which is using Cumulocity IoT to manage several field devices. For simplicity let’s assume we have one device registered in our Cumulocity IoT tenant. This device sends alarms with different severities when certain conditions are met. The alarms are important for our service technicians as they need to act. Therefore we would like to create a Zendesk Ticket, whenever an alarm is created. Also, we would like to send an SMS to a certain mobile number of our service technician, using an SMS provider “Twilio”, if the alarm severity is CRITICAL.

Solution Design in Cumulocity IoT

This use case can be addressed by implementing logic in Cumulocity IoT EPL Apps that processes device alarms. When an alarm is triggered, this EPL App can call the Zendesk API to generate a ticket as well and when the alarm severity is critical initiate a call to the Twilio API for SMS alerts.

As EPL Apps is a pro-code environment, to implement this logic a decent technical background is beneficial, and you would have to maintain the integration points with Zendesk and Twilio.

Now with minimum or no technical background, you can easily implement the same use case in 2 hours, all you have to know is how to use Cumulocity IoT Analytics Builder.

It is worth mentioning that, starting with release 10.17, Cumulocity IoT supports seamless integration with Twilio for SMS sending. However, the no-code approach mentioned in this guide can be applied with any other SMS provider, which does not have direct integration with Cumulocity IoT.

The following sections will illustrate how you can implement this use case with the No-Code approach, using n8n Platform.

n8n - Workflow automation tool

n8n (pronounced n-eight-n) helps you to connect any app with an API with any other, and manipulate its data with little or no code.

n8n allows you to build flexible workflows focused on deep data integration. And with sharable templates and a user-friendly UI, the less technical people on your team can collaborate on them too.

n8n offers the following:

• Code when you need, no code when you don’t: Connect APIs with no code to automate basic tasks. Or write vanilla JavaScript when you need to manipulate complex data.

• Build custom scenarios at speed: You can implement multiple triggers. Branch and merge your workflows and even pause flows to wait for external events.

• Integrate with any app: Interface easily with any API or service with custom HTTP requests.

• Independent instances for each environment: Avoid breaking live workflows by separating dev and prod environments with unique sets of auth data.

• 350+ native integrations: Connect to all your favorite apps. Or write your own integration with a general connector to the rest.

• Bulk operations: n8n nodes let you process data at scale with a built-in iteration functionality in every node.

• Painless debugging: See the execution data of every workflow. Integrate error nodes into workflows to catch errors and rerun individual nodes to test fixes quickly.

• Host on your own infrastructure: Fully on-prem for those that need the security.

  

The scope of this integration guide is to illustrate how you can use n8n to integrate Cumulocity IoT with the Zendesk Platform & Twilio SMS Provider, with a no-code approach.

Step-by-Step Guide

Prerequisites

This Integration guide is based on the following assumptions:

• Cumulocity IoT Release 10.18.
• To call n8n workflow from Analytics Builder, you will need to add a custom block “Webhook” to the list of Analytics Builder Blocks. Please check the following link to install the custom block to Analytics Builder of your Cumulocity IoT tenant:

GitHub - SoftwareAG/analytics-builder-blocks-contrib: Unsupported, not...

• 1 device sending alarms to Cumulocity IoT
• Existing account on n8n
• Existing account on Zendesk
• Existing account on Twilio

Device sends an Alarm

The trigger of this use case is an alarm sent from a device registered in Cumulocity IoT.

You can use a real device to send such an alarm or you can use Postman or CURL or any other tool to simulate a device sending an alarm to Cumulocity

To send a critical alarm you can use the following:

POST <Tenant URL>/alarm/alarms 
{ 
    "source": { 
        "id"        : "<Device Cumulocity ID>" 
        }, 
        "type".     : "TemperatureAlarm", 
        "text".     : "Temperature is High", 
        "severity"  : "CRITICAL", 
        "status".   : "ACTIVE", 
        "time"      : "2023-11-15T09:44:27.845Z" 
} 

Feel free to set alarm’s type, text, time and severity as you wish.

Please note that the severity must match one of the allowed values CRITICIAL, MINOR, MAJOR, WARNING

Cumulocity IoT Analytics Builder Model

The device will send alarms to Cumulocity IoT, so we need to implement an Analytics Builder Model, where it will listen to alarms coming from the device, build payload and fire n8n workflow to start integration with Zendesk & Twilio.

Following is how the final layout of the Analytics Builder model should look like and in the following steps we will illustrate each block in the model.

1. This is an Alarm Input block to catch new alarms from device.

   

2. This is a Managed Object Input block for the same device. It is used only to get the device name, the model will not fire to changes in the device name, as we will explain in step 6.

   

3. This is Extract block to extract alarm’s severity from the raised alarm.

   

4. This is Extract block to extract alarm’s text from the raised alarm.

   

5. This is an Expression block to build payload which will be sent to n8n webhook. The expression is as following:

   "{\"mobile\": \"+XXXXXXXXXXXXX\", 
     \"text\": \"" + input3 + "\" , 
     \"severity\" : \"" + input1 + "\", 
     \"device\" : \"" + input2  + "\" 
    }" 
   

   Where :
   mobile holds the mobile number where Twilio will send SMS to, please replace X with your mobile number

   • input 1 is the output of Step 3 
     

   • input 2 is the output of Step 2 
     

   • input 3 is the output of Step 4 
     

6. This is a Gate block which is used to allow the model to call n8n webhook only in case of alarm is raised.

   

7. This is the custom HTTP Webhook block which is used to a call n8n cloud webhook.

   

   Where

   Host: is the base URL of the n8n webhook, you will get it when you configure the webhook in n8n.

   Path: is the path part of n8n webhook URL, you will also get it, when you configure the webhook in n8n. Please note that n8n offers two URLs: One for testing whose path starts with /webhook-test/ and another one for production whose path starts with /webhook/.

   Authorization Header: is Base64 of the Basic authentication credentials which are configured in n8n.

Zendesk Configuration

For n8n Platform integration with Zendesk, you have to establish a connection from n8n towards Zendesk, and part of the required connection’s settings is Zendesk API Token.

In the following steps, we will show you how you can create the required Zendesk API Token.

1. Log in to your account on Zendesk using this URL https://<YourSubDomain>.zendesk.com/ , and replace <YourSubDomain>, with the one you have created during the registration process.

2. On the Top right corner, open the user profile sub-menu, and click View Profile.

   

3. In the Profile Page, click on Manage in Admin Center link, which will open in a new tab.

4. In Admin Center page, expand Apps and integrations sub menu, and click Zendesk API menu item.

   

5. In the API Token page, click Add API Token button, which will redirect to the new page.

   

   a. Add a description for the API Token.
   b. Copy the API Token and save it in a secure place, as once you have closed this page, you will not have access to the API Token again.
   c. Click the Save button. .

   

Twilio Configuration

Twilio only send SMS to verified mobile numbers, so you have to add the mobile number that will receive SMS in our use case to the list of verified Caller ID in Twilio, which will be shown in the following steps:

1. Log in to your account on Twilio.

2. Check out the Develop Tab in the left menu, and expand Manage sub Item.

   

3. Click on Verified Caller IDs link and a new page will be opened as follows.

   

4. Click Add a new Caller ID button, a popup window will be shown, enter your number and click the Verify number button.

   

5. Once your number is verified, it will be added to Verified Caller ID list.

In next section n8n Workflow, you will configure the Twilio node. To do so you will need to set an account SID, auth token and your Twilio phone number. Following are steps to get those parameters.

1. Log in to your account on Twilio.

2. Go down to Account Info section, have a copy of Account SID, Auth Token and My Twilio phone number, as you will use them when you configure the Twilio node in n8n workflow.

   

n8n Workflow

1. Log in to your n8n account.

2. Click the Add workflow button.

3. A new workflow editor will be opened.

4. Set workflow name to Cumulocity_Zendesk_Twilio_Integration, or set it to any other name of your choice.

   

5. Click the + Add first step.

6. A side menu will be shown on the right.

   

7. Search for webhook node, and select the Webhook trigger.

   

8. A new pop-up window will be opened to set the webhook node configuration.

   

9. As shown in the previous screenshot, n8n Platform has created two URLs for the workflow, the first one is for testing during configuring the workflow “Test URL”, and the later one is used for Production “Production URL”, and it is used when you activate the workflow

10. Now set the webhook node configuration as follows:

    a. For Authentication choose Basic Authentication.

    b. Choose Create new Credentials Credential for Basic Auth.

    c. A new pop-up window will be opened.

    • Set Credential name n8n_cred.
    • Set the user of your choice.
    • Set the password of your choice.
    • Click the Save button.
    

11. When you click the Save button, Credential for Basic Auth will be populated with n8n_cred.

12. For HTTP method choose POST.

13. For Path, you can set your own path, in our case I will leave the default value.

14. For Respond choose When Last Node Finishes.

15. For Response Code leave default value to 200

16. For Response Data choose All Entries

17. Click the Add Option, and select Row Body and set it to ON.

18. The configuration should be as following now:

    

19. Click Back to Canvas on the top left.

20. Now we will test the webhook node using the Test URL.

    a. Go to Cumulocity IoT Analytics Builder and open the model that you have created in Cumulocity IoT Analytics Builder Model section, and update the webhook configuration with n8n Test URL & Base64 of the credential that you have created in n8n webhook node.

    b. Then Save the model and set it to Active.

    c. In n8n open Webhook node configuration and click Listen For Test Event button.

    d. Use Postman or CURL or any other tool and create an alarm for the device.

    e. If everything is configured correctly, the output will be shown on the right side of webhook configuration.

    

    f. In the output window click on the JSON tab, to view the incoming payload from Cumulocity IoT.

    

    g. If you check the last part of the incoming JSON payload, you will find the payload, which has been defined in Cumulocity IoT Analytics Builder Model section, is shown as the value of property “value”.

21. If you have similar output from the previous step, you can consider that n8n webhook node is configured in the workflow.

22. Now, we need to extract the Cumulocity IoT payload from the value property of the original JSON payload, and to do that, we have to add a new code node and connect it to the output of the webhook node.

23. On the output of the webhook node, click the + icon which will open a window to choose the next node.

24. In the search box, write code and select the Code node.

25. With a Code node you can write down JavaScript or Python code to process the output of the previous node, which is the webhook node in our case. Also, the Code node gives you the ability to use AI to generate the required code in JavaScript or Python.

26. To comply with the no-code approach in this guideline, we did the following:
    a. We asked AI to extract the value of “body.value” property in the JSON Payload, by using the following prompt parse json of item.json.body.value.value, then click Generate Code button.

    

    b. AI will create the following code using JavaScript

    

    You can copy and paste this code directly to Code tab

    const items = $input.all(); 
    const parsedData = items.map((item) => { 
     	const bodyValue = item?.json?.body?.value?.value; 
     	const parsedValue = JSON.parse(bodyValue); 
        return parsedValue; 
    }); 
    return { parsedData }; 
    

    c. Click the Execute node button on the top right, and choose JSON tab in the output window. You will notice that the payload which was sent by Cumulocity IoT is in JSON format.

    

27. Back to the canvas again, and click + icon on the output of the Code node to choose the next node.

28. In the search box, write zendesk and select the Zendesk node.

    

29. Then select Create Ticket Action.

    

30. A configuration window for the Zendesk node will be opened. You will notice that the output of the previous node appears on the left side as input to Zendesk node.

    

    To configure the Zendesk node, you have to do the following:

    a. For Credentials to connect with, select Create New Credentials, a new popup window will be shown, and you have to fill in the following fields:

    • Set name of Zendesk credentials as zendesk_cred.
    • For Subdomain, use the subdomain, that you entered during creating an account on Zendesk.
    • For Email, use the same email, which you used during creating an account on Zendesk.
    • For API Token, use the same API Token, which you have created in Zendesk Configuration section.
    • Click the Save button.
    

    b. For Description, it is Ticket’s Description in Zendesk and you can set it as Fixed or Dynamic text based on the incoming Payload. In our case will use the late option.
    Choose Expression Option, and build text as follows:

    There is {{  $json.body.value.value.severity }} alarm raised from device  {{ $json.body.value.value.device }} with Text  {{ $json.body.value.value.text }} 
    

    The placeholders are selected from the left side input of the node, by selecting the JSON tab, and drag and drop parameter keys to the Description box.

    c. Switch On JSON Parameters.

    d. In addition to Description field, you can set any other Zendesk Ticket fields like “Subject”

    {"subject": "{{ $json.body.value.value.severity }} Alarm {{ $json.body.value.value.text }}"  } 
    

    e. Zendesk node configuration should look like.

    

    f. Click the Execute Node button, and if all configurations are correct a new ticket will be created in Zendesk. The node output will be as follows

    

    g. Open Zendesk and navigate to the dashboard. You will find a new ticket has been created.

    

    h. In n8n click Back to Canvas and click the Save button to save workflow.

31. We are done with the first part of the use case by creating a Zendesk ticket whenever an Alarm is created.

32. Now we need to add a condition to send an SMS to a certain mobile if the alarm severity is CRITICAL severity.

33. Click + icon on the output of the Zendesk node to choose the next node.

34. In the search box, write if and select the IF node.

    

35. In the configuration of IF node do the following:

    a. On the left side, select Code node from Input and switch to JSON Tab.
    b. Click Add Condition button, and select String.
    c. For Value 1, drag severity from left
    d. Set Operation to Equal.
    e. For Value 2, set it to CRITICAL.
    

    

    f. Click Execute node.
    g. In n8n click Back to Canvas and click the Save button to save workflow.

36. IF node has two outputs, the first one is when the condition evaluates to true, and the latter is when the condition evaluates to false.

37. For false evaluation Output click + icon on the output of the node to choose the next node.

38. In the search box, write No operation and select the No operation, do nothing node.

39. Click the Save button.

40. For true evaluation Output click + icon on the output of the node to choose the next node.

41. In the search box, write twilio and select the Twilio node.

    

42. Then select Send an SMS/MMS/WhatsApp message.

    

43. Then the configuration window for the Twilio node will be opened. You will notice that the output of the previous node appears on the left side as input to IF node.

    

    To configure the Twilio node you have to do the following:

    a. For Credentials to connect with selecting Create New Credentials, a new popup window will be shown and you have to fill in the following fields:

    • Set name of Twilio credentials as twilio_cred.

    • For Auth Type choose Auth Token.

    • For Account SID use Account SID, which you have collected in Twilio Configuration section.

    • For Auth Token use Auth Token, which you have collected in Twilio Configuration section.

    • Click the Save button.

      

    b. For Resource set it to SMS.

    c. For Operation set it to Send.

    d. For From phone number set it to My Twilio phone number, which you have collected in Twilio Configuration section.

    e. For To phone number, set it mobile property from Cumulocity IoT Payload.

    • Select Code node from Input nodes. Choose JSON tab.
    • Choose Expression Option.
    • Drag mobile property to the field.
      The text should look like

    {{ $('Code').item.json.parsedData[0].mobile }} 
    

    f. For Message, set it to:

    {{ $('Code').item.json.parsedData[0].severity }} Alarm is raised from device   {{ $('Code').item.json.parsedData[0].device }}  , Ticket ID  {{ $('Zendesk').item.json.id }} 
    

    where placeholders are from Code & Zendesk input nodes

    g. Twilio node’s configuration should look like

    

    h. Click the Execute Node button and if all configurations are correct SMS will be sent to To mobile number.

    

    i. Check if the mobile number; that you set in Cumulocity IoT Payload has received an SMS.

    j. Or check in Twilio by navigating to Monitor tab on the left, then click Messaging. On the right pane, you will see list of sent SMS.

    k. In n8n click Back to Canvas and click the Save button to save workflow.

44. The final use case workflow should look like this.

    

45. Now and before activating the workflow, make sure to use the Production URL of n8n webhook in Analytics Builder Webhook block.

46. Activate n8n workflow.

Congratulations! You finished this guide and created an integration to Zendesk & Twilio using the n8n Integration Platform and Cumulocity IoT Analytics Builder.

n8n Installation Options

n8n has multiple installation options:

• Cloud
• Enterprise self-hosted
• Community self-hosted

You can install the self-hosted options using npm or Docker.

For more information please check the following links:
Self-hosting n8n
n8n Community Edition