webMethods.io Integration: create a Cumulocity IoT trigger

Summary

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

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. Create a new Account for the connection to Cumulocity IoT - see below - or select an existing one.
8. Configure the trigger by choosing the groups or devices to subscribe to. See below for a detailed description of the parameters for Alarms, Events, Measurements and Inventory.
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 having this exact type. -> If this field is left empty, no filter is applied and Cumulocity IoT will send all the notifications for the selected device or group. 💡 You can refer to the tooltip for examples of filter values.
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. 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. 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.

Creation of the connection to Cumulocity IoT

For webMethods.io to access Cumulocity IoT resources, an Account has to be created with the Cumulocity IoT credentials.
Note that the Cumulocity IoT Accounts in webMethods.io Integration are shared between Cumulocity IoT triggers and connectors.

For Cumulocity IoT Accounts, only the properties below are taken into account. All other properties are ignored and their default value can be left unchanged.

• Account Name: This is the name that will be displayed in the list of Cumulocity IoT connections in both trigger and connector settings.
• Server URL: This is the URL of the target Cumulocity IoT instance. ℹ️ Only the root path is to be provided (like https://mytenant.cumulocity.com for instance) with no "/" at the end.
• Username / Password: Credentials of the Cumulocity account to be used. Note that these credentials require admin permissions for "Application management".
• Cumulocity Application Name: This is the name of an internal Cumulocity IoT micro application that will be created / reused for data access. Unless there is any specific usage requirement, the default name "wmio-connector-app" can be used.

ℹ️ Cumulocity Application Name and the account credentials:
the Cumulocity IoT triggers and connectors in webMethods.io Integration do not access Cumulocity IoT with the provided account credentials at run time.
Instead of this, upon creation of a new Cumulocity IoT Account:

1. the credentials are used to create / reuse the microservice application in Cumulocity IoT with the provided Application Name - hence the required admin permissions for "Application management".
2. The microservice application is granted the required rights for the subscription to Cumulocity IoT notifications.
3. A "Service User" for the microservice application is kept [u]internally in webMethods.io and is not visible by anyone[/u]. This Service User is then used by webMethods.io to access Cumulocity IoT during the execution of the workflows. In turn, this means that the user credentials used to create the account can be modified or deleted without any impact on the execution of the workflows

After the successful creation of the Cumulocitiy IoT Account, the new Account is available for selection in the trigger settings.

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

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.

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

Read full topic