webMethods.io Integration: create a Cumulocity IoT trigger

[frederic.joulin (Frédéric Joulin)]

Overview

This article describes the step-by-step process to create a Cumulocity IoT trigger in webMethods.io Integration.

For the creation of Cumulocity IoT connectors, please refer to the document Create a Cumulocity IoT Connector

Prerequisites

• The user needs Cumulocity IoT credentials having admin permissions for “Application management”.
• Working webMethods.io Integration cloud tenant.
• The target Cumulocity IoT tenant must support the Notification 2.0 Enhancements (see Cumulocity IoT Notification 2.0 Enhancements for more information on this Cumulocity IoT feature)

Steps to follow

Creation of a new workflow with a Cumulocity IoT trigger

1. Login to webMethods.io Integration tenant.

2. Create a new project or choose an existing project if required.

3. Click on the Workflows and the Integrations tabs and add a new Workflow.
   

   
   
   
   

4. All workflows are named “Untitled workflow” by default and can be renamed within the editor.
   

   
   

5. Open the workflow’s trigger settings, select the Cumulocity IoT trigger in the list and click on [Next].
   

   
   
   
   

6. Provide a name for the trigger and select the type of Cumulocity IoT notification to be set.
   The trigger can be activated upon Cumulocity ioT Alarms, Events, Measurements or Inventory changes (changes to managed objects in Cumulocity IoT).
   

   

7. Select an Account for the connection to Cumulocity IoT or create a new one.
   

   

8. Configure the trigger by choosing the groups or devices to subscribe to.
   See section “API/Trigger Parameters” below for a detailed description of the parameters available for each type of notification.

9. Optionally the incoming notifications can be filtered by type.
   

   
   
   All notifications sent by Cumulocity IoT contain a “type” property.
   → If any filter value is provided, Cumulocity IoT will only send notifications whose “type” matches the filter.
   → If this field is left empty, no filter is applied and Cumulocity IoT will send all the notifications for the selected device or group.

Difference between Cumulocity IoT versions 10.13 and 10.16

Up to Cumulocity IoT version 10.13, the type filter is handled as a full string match, i.e. only notifications whose “type” exactly matches the provided text are sent.
From Cumulocity IoT version 10.16, the type filter is handled as a simplified OData expression with a combination of single quoted filter strings.

For example the type filter c8y_Temperature for Cumulocity IoT V10.13 must be expressed as the quoted string 'c8y_Temperature' for Cumulocity IoT V10.16.
Cumulocity IoT V10.16 also handles combinations of multiple values for the type filter, like 'c8y_Temperature' or 'c8y_Pressure'.

For more details about the expected format for the type filter, please refer to the Cumulocity IoT documentation Cumulocity IoT - OpenAPI Specification, property “subscriptionFilter.typeFilter” of the Request Body Schema.

10. A click on [Save] saves the trigger and moves on to the test window.
    
    
    
    At this point the trigger is fully configured and listening to matching notifications from Cumulocity IoT for test purposes.

Process a test notification

In order to test the trigger, an action must first be performed in Cumulocity IoT and then a click on [Test] will display the incoming notification message.

If no notification has been received, the following window indicating possible reasons is shown.
The trigger configuration can then either be corrected or another test be performed.

Skip tests

A click on [Skip] does not consider any incoming notification from Cumulocity IoT and displays a predefined message. The Cumulocity IoT trigger provides realistic default messages for alarms, events, measurements and inventory changes.

11. Optionally rules may be applied to filter the incoming Cumulocity IoT messages. With the application of filter rules, the trigger is only activated for matching incoming messages.
    This can be used for instance to activate an Alarm trigger only on alarm messages with a given severity level.
    
    
    
    
    

API/Trigger Parameters

Parameters for Cumulocity IoT Alarms

The Cumulocity IoT trigger allows to subscribe to alarms for various objects:

• All Devices: any alarm occurring on the target Cumulociity IoT instance with activate the trigger
• Specific Device: only alarms applying to the given device or managed object will activate the trigger
• Specific Group: alarms applying to any device belonging to the provided group will activate the trigger
  
  

1. When selecting All Devices, no further parameter is needed.
   The trigger will be activated for any alarm occurring in Cumulocity IoT.
2. When selecting Specific Device, the identifier of a managed object must be provided.
   It is possible to either select one of the devices from the dropdown list or to manually enter its identifier.
   If an identifier is entered manually, any identifier of an existing managed object is allowed, no matter if it’s a device or not. Any alarm attached to the provided managed object will activate the trigger.
   
   
3. When selecting Specific Group, the identifier of a group must be provided.
   It is possible to either select one of the groups from the dropdown list or to manually enter its identifier.
   Even if an identifier is entered manually, the corresponding group must exist in Cumulocity IoT
   
   

Parameters for Cumulocity IoT Events

The Cumulocity IoT trigger allows to subscribe to events for various objects:

• Specific Device: only events applying to the given device or managed object will activate the trigger
• Specific Group: events applying to any device belonging to the provided group will activate the trigger
  
  

1. When selecting Specific Device, the identifier of a managed object must be provided.
   It is possible to either select one of the devices from the dropdown list or to manually enter its identifier.
   If an identifier is entered manually, any identifier of an existing managed object is allowed, no matter if it’s a device or not. Any event attached to the provided managed object will activate the trigger.
   

   

2. When selecting Specific Group, the identifier of a group must be provided.
   It is possible to either select one of the groups from the dropdown list or to manually enter its identifier.
   Even if an identifier is entered manually, the corresponding group must exist in Cumulocity IoT
   

   

It is currently not possible to subscribe to all events due to limitations of the notification service

Parameters for Cumulocity IoT Measurements

The Cumulocity IoT trigger allows to subscribe to measurements for specific devices or managed objects.

The identifier of a managed object must be provided either by selecting one of the devices from the dropdown list or to manually enter its identifier.
If an identifier is entered manually, any identifier of an existing managed object is allowed, no matter if it’s a device or not. Any measurement attached to the provided managed object will activate the trigger.

It is currently not possible to subscribe to all measurements or measurements of a group of devices due to limitations of the notification service

Parameters for Cumulocity IoT Inventory Changes

The Cumulocity IoT trigger allows to subscribe to inventory changes for various objects:

• All Devices: any inventory change occurring on the target Cumulociity IoT instance with activate the trigger
• Specific Device: only changes to the given device or managed object will activate the trigger
• Specific Group: changes to any device belonging to the provided group will activate the trigger

1. When selecting All Devices, no further parameter is needed.
   The trigger will be activated for any change to the inventory of managed objects occurring in Cumulocity IoT.
2. When selecting Specific Device, the identifier of a managed object must be provided.
   It is possible to either select one of the devices from the dropdown list or to manually enter its identifier.
   If an identifier is entered manually, any identifier of an existing managed object is allowed, no matter if it’s a device or not. Any change to the provided managed object will activate the trigger.
   
   
3. When selecting Specific Group, the identifier of a group must be provided.
   It is possible to either select one of the groups from the dropdown list or to manually enter its identifier.
   Even if an identifier is entered manually, the corresponding group must exist in Cumulocity IoT
   
   

Summary / Next Steps

With this article you have all the required knowledge to create a Cumulocity IoT trigger in webMethods.io.
This is a first step to integrate and share Cumulocity device data with other systems and applications. For concrete use cases, please refer to Cumulocity integration with webMethods.io