IoT

Amazon Alexa

Amazon Alexa is an intelligent voice assistant that powers Amazon Echo – voice-enabled smart speaker developed by Amazon.com.

Actions

Response for Alexa: Form a custom response for Alexa

Cisco Meraki

Cisco Meraki offers products for a wide range of wired and wireless networks. It lets you add, remove and monitor your networks and the devices associated with those networks.

Actions

Add Contact in a Network: Add a new contact in the specified network
Add VLAN in a Network: Add a VLAN in the specified network
Delete VLAN in a Network: Delete the specified VLAN from the network
Force Check-in a Set of Devices: Check-in one or more devices
Get Network Traffic Data: Retrieve the traffic data of the specified network
List Air Marshal Scan Results: Retrieve the list of air marshal scan results
List Clients of a Device: Retrieve the list of clients associated with the specified device
List Contacts in a Network: Retrieve the list of contacts in the specified Systems Manager network
List Devices Enrolled in an SM Network: Retrieve the list of devices enrolled in the specified Systems Manager network
List Devices in a Network: Retrieve the list of devices associated with the specified network
List Networks in an Organization: Retrieve the list of networks associated with the specified organization
List Organizations: Retrieve the list of organizations to which the user has access.
List VLANs in a Network: Retrieve the list of VLANs associated with the specified network
Lock a Set of Devices: Lock one or more devices associated with the specified network

Common Questions

How do I add an API key to connect Cisco Meraki with IBM webMethods Integration

To retrieve the API key of your Cisco Meraki account, do the following:

Log in to your Cisco Meraki account, and click on the My Profile tab provided on the upper-right corner of the dashboard window.

A new window appears with the details of your account. Scroll down and locate the API Key given under the API access section.

You can also Revoke or Regenerate the given API key, as per your requirements.

Once you have entered the API key in the connection window, click ADD. You can now see the added connection under the Connect to Cisco Meraki field. Once added, this connection will be available in all Cisco Meraki actions.
Why am I not able to check-in my devices using Force Check-in a Set of Devices action.

Devices that are not added under Systems Manager network, can not be checked-in using the Force Check-in a Set of Devices action. Please ensure that your devices are added under SM network before attempting the check-in.
How does a Batch Token work in List Device Enrolled in an SM Network action.

The List Devices Enrolled in an SM Network action fetches a maximum of 1000 devices in a single result. If a network has more than 1000 devices, this action returns the list of 1000 devices along with the batch token for the next 1000 devices. You can use this batch token in the next request to retrieve the list of 1000 devices associated with it.

Cumulocity (Deprecated)

Note

The Cumulocity connector is deprecated and will become obsolete in a later release. If you are creating new Workflows or Flow services, it is recommended to use the alternative connector - Cumulocity IoT.
Deprecated connectors will continue to work as before and are fully supported.
If you are using deprecated connectors in your existing Workflows and/or flow services, they will work as expected.
No new feature enhancements will be made for deprecated connectors.

Cumulocity lets you build your IoT applications. Your data points can be configured very quickly due to its open, API-driven, and application-centric design.

API Versions: 0.9

API Types: REST

Authentication and Authorization: Basic

Key Capabilities: Custom field support

Prerequisites

Cumulocity API login and password information
Cumulocity account you are using has privileges to connect to the Cumulocity API
Cumulocity objects and usage familiarity

Triggers

Alarm: Triggers when a alarm for a specific device is set-off
Event: Triggers when a specific event occurs
Measurement: Triggers when the measurement event occurs for the specified device.

Actions

copyApplication: Creates a new application based on already existing one. Properties are copied to newly created application
createAlarm: Creates a new alarm
createApplication: Creates a new application
createAuditRecord: Creates a new audit record
createExternalId: Creates an external ID
createManagedObject: Creates a new managed object
createMeasuement: Creates a new measurement
deleteAlarmColelction: Deletes an alarm collection
deleteEvent: Deletes an event
deleteEventCollection: Deletes an event collection
deleteExternalId: Deletes an external ID. Single external ID, represented by type of the external ID and the value of the external ID, both as strings
deleteManagedObject: Deletes a managed object
deleteMeasurement: Deletes a measurement
deleteModule: Deletes a module
deleteOperationCollection: Deletes a collection of operations
gatAlarmCollection: Retrieves an alarm collection
getApplicationByTenant: Retrieves applications of a tenant
getApplicationByUser: Retrieves applications of a user
getAuditRecord: Retrieves an audit record
getAuditRecordCollection: Retrieves collection of audit records
getBinariesCollection: Retrieves collection of binaries
getBulkOperationCollection: Retrieves collection of bulk operations
getEvent: Retrieves an event
getEventCollection: Retrieves collection of events
getExternalIdsOfGlobalID: Represents a collection of external IDs for a specified global ID
getManagedObject: Retrieves a managed object
getManagedObjectCollection: Retrieves collection of a managed objects
getManagedObjectCollectionByQuery: Retrieves managed objects found by query
getManagedObjectForType: Retrieves a read-only collection of all managed objects of a particular type
getManagedObjectsForFragmentType: Read-only collection of all managed objects with a particular fragment type or capability
getManagedObjectsForIDs: Read-only collection of managed objects fetched for a given list of IDs, for example, “?ids=41,43,68“
getMeasuementCollection: Retrieves collection of measurements
getModuleCollection: Retrieves collection of modules
getModuleStatements: Retrieves a module file with statements
getSeriesFromMeasurement: Retrieves a series from measurements
updateAlarm: Updates an alarm
updateBulkOperation: Updates a module
updateModule: Updates a bulk operation

Custom Actions

Cumulocity connector lets you create your own custom actions for performing specific tasks. The actions you create look and work exactly like the other predefined actions do.

To know more about how to create custom actions, see Creating Custom Actions.

Cumulocity IoT

Cumulocity lets you build your IoT applications. Your data points can be configured very quickly due to its open, API-driven, and application-centric design.

API Versions: 10.16

API Types: REST

Authentication and Authorization:

The credentials of a dedicated Cumulocity IoT microservice Service User are used at runtime.
The microservice is created after adding a new connection or account.

Note

If a microservice exists, the credentials of the microservice are retrieved and stored in IBM webMethods Integration.

The credentials of a local Cumulocity IoT user must be provided for creating a new connection or account. The user must have administrative permissions for Application management. You cannot use a IBM webMethods iPaaS user.

Note

The Application management permission is typically assigned to the Admin and Tenant management roles. Also, the local Cumulocity IoT user is required for creating connections only, and is not used during runtime.

Prerequisites:

Cumulocity IoT account with administrative permissions for Application management.
Cumulocity IoT objects and usage familiarity.

Triggers

Cumulocity IoT triggers can be created for different types of Cumulocity IoT notifications:

Alarm: Triggers when an alarm is raised. The trigger can be set up for:
- all devices on the Cumulocity IoT tenant
- a specific device or managed object
- a group of devices
Event: Triggers when a specific event occurs. The trigger can be set up for:
- a specific device or managed object
- a group of devices
Measurements: Triggers when a measurement occurs for a specified device or managed object.
Inventory: Triggers when changes occur on managed objects. The trigger can be set up for:
- all devices on the Cumulocity IoT tenant
- a specific device or managed object
- a group of devices

FAQs

No, only subscriptions to normal groups are supported.

This is not allowed due to performance limitations. The alternative is to create a group in Cumulocity IoT with the devices you want to monitor and subscribe to this group.

You can select Specific Device and then enter manually the ID of the managed object in the field.

Actions

Cumulocity IoT actions are available as follows:

Application API

Retrieve all applications: Get all the applications on your tenant.
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Retrieve a specific application: Get a specific application (by a given ID).
Required roles: ROLE_APPLICATION_MANAGEMENT_READ OR current user has explicit access to the application.
Update a specific application: Update a specific application (by a given ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Delete an application: Delete an application (by a given ID). This method is not supported by microservice applications.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN AND tenant is the owner of the application.

Important

With regards to a hosted application, there is a caching mechanism in place that keeps the information about the placement of application files such as html, javascript, css, and fonts. In normal circumstances, removing a hosted application causes the subsequent requests for application files to fail with an HTTP 404 error. This is because the application is removed, and its files are immediately removed on the node serving the request and at the same time the information is propagated to other nodes. But in rare cases there might be a delay with this propagation. In such situations, the files of the removed application can be served from those nodes up until the aforementioned cache expires. For the same reason, the cache can also cause HTTP 404 errors when the application is updated as it retains the path to the application files of the old version. The cache is filled on demand, so there should not be issues if application files were not accessed prior to the delete request. The expiration delay of the cache can differ, but must not take more than one minute.
Copy an application: Copy an application (by a given ID). This method is not supported by microservice applications. A request to the clone resource creates a new application based on an already existing one. The properties are copied to the newly created application and the prefix clone is added to the properties name, key, and contextPath in order to be unique. If the target application is hosted and has an active version, the new application will have the active version with the same content.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.
Retrieve applications by name: Get the applications by name.
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Retrieve applications by tenant: Get the applications subscribed or associated with a particular tenant (by a given tenant ID).
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Retrieve applications by owner: Get all the applications associated with a particular tenant (by a given tenant ID).
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Retrieve applications by user: Get all the applications for a particular user (by a given username).
Required roles: (ROLE_USER_MANAGEMENT_OWN_READ AND is the current user) OR (ROLE_USER_MANAGEMENT_READ AND ROLE_APPLICATION_MANAGEMENT_READ).
Retrieve a specific version of an application: Get the selected version of an application in your tenant. To select the version, use only the version or only the tag query parameter.
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Retrieve all versions of an application: Get all the versions of an application in your tenant.
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Delete a specific version of an application: Delete a specific version of an application in your tenant, by a given tag or version.
Required roles: ROLE_APPLICATION_MANAGEMENT_READ.
Replace an application version’s tags: Replace the tags of a given application version in your tenant.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.
Retrieve all application attachments: Get all the application attachments. This method is not supported by microservice applications.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.
Retrieve a specific application attachment: Get a specific application attachment (by a given application ID and a given binary ID). This method is not supported by the microservice applications.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.
Delete a specific application attachment: Delete a specific application attachment (by a given application ID and a given binary ID). This method is not supported by the microservice applications.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN AND tenant is the owner of the application.
Retrieve the bootstrap user for a specific application: Get the bootstrap user for a specific application (by a given ID). This only works for microservice applications.
Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Measurements API

Retrieve all measurements: Get all the measurements on your tenant, or a specific subset based on queries. In case of running range queries between an upper and lower boundaries (dateFrom – dateTo), the oldest registered measurements are returned first. It is possible to change the order using the query parameter revert=true.

For large measurement collections, querying older records without filters can be slow as the server must scan from the beginning of the input results set before returning the results. For scenarios where older measurements must be retrieved, it is recommended to use range queries based on the time stamp reported by a device. The scope of query can also be reduced by providing a source device.
Create a measurement with measurement: Create a measurement. A measurement must be associated with a source (managed object) identified by ID, type of measurement, and the time when it was measured by the device (for example, a thermometer).

Each measurement fragment is an object (for example, c8y_Steam) containing the actual measurements as properties. The property name represents the name of the measurement (for example, Temperature) and it contains two properties:
- value - The value of the individual measurement. The maximum precision for floating point numbers is 64-bit IEEE 754. For integers, it is a 64-bit two’s complement integer.
- unit - The unit of the measurement. For more information about the conversions of units, see System of units and Naming conventions of fragments sections in the Cumulocity IoT Concepts guide.
Important

Property names used for fragment and series must neither contain whitespaces nor the special characters . , * [ ] ( ) @ $. This is required to ensure correct processing and visualization of measurement series on UI graphs.
Create measurements with measurement collection: Create multiple measurements at once by sending a measurements array containing all measurements to be created. The content type must be in the format: application/vnd.com.nsn.cumulocity.measurementcollection+json.

Note

For more details about fragments with specific meanings, see Device management library and Sensor library.

Required roles: ROLE_MEASUREMENT_ADMIN OR owner of the source OR MEASUREMENT_ADMIN permission on the source.
Remove measurement collections: Remove the measurement collections specified by query parameters. The delete requests are not synchronous. The response is returned before the delete request has been completed. This may happen especially when there are a lot of measurements to be deleted.

Important

If no parameter is provided in the endpoint, then all measurements are deleted. This action is not recommended.

Required roles: ROLE_MEASUREMENT_ADMIN.
Retrieve a specific measurement: Get a specific measurement by a given ID. Tenants where time series is enabled, measurements can be searched using the query parameters.
Required roles: ROLE_MEASUREMENT_READ or owner of the source or MEASUREMENT_READ permission on the source.
Remove a specific measurement: Delete a specific measurement by a given ID. Tenants where time series is enabled, measurements cannot be deleted by ID. You can remove expired time series measurements data from the Operational Store by query or using the retention rules.
Required roles: ROLE_MEASUREMENT_ADMIN or owner of the source or MEASUREMENT_ADMIN permission on the source.
Retrieve a list of series and their values: Get a list of series (all or only those matching the specified names) and their values within a given period of a specific managed object (source). A series is any fragment in measurement that contains a value property. It is possible to retrieve aggregated results using the aggregationType parameter. If the aggregation is not specified, the result contains no more than 5000 values.

Important

Devices must send dates from the same time zone to be able to aggregate correctly.

Required roles: ROLE_MEASUREMENT_READ or owner of the source or MEASUREMENT_READ permission on the source.

Alarms API

Retrieve all alarms: Get all the alarms on your tenant, or a specific subset based on queries.The results are sorted by the newest alarms first.

Query parameters: The query parameter withTotalPages works only when the user has the ROLE_ALARM_READ role, otherwise it is ignored.
Required roles: The role ROLE_ALARM_READ is not required, but if a user has this role, all alarms on the tenant are returned. If a user has access to alarms through inventory roles, only those alarms are returned.
Update alarm collections: Update the alarm collections specified by query parameters. At least one query parameter is required to prevent all alarms from being accidentally updated. Currently, only the status of alarms can be modified.

Note

It takes up to 0.5 seconds for the platform to process the request, and the Update operation continues as a background process.

Required roles: ROLE_ALARM_ADMIN.
Create an alarm: Create an alarm. An alarm must be associated with a source (managed object) identified by ID. In general, each alarm consists of the following components:
- status indicating whether the alarm is Active, Acknowledged, or Cleared.
- time stamp indicating when the alarm is last updated.
- severity of the alarm such as Critical, Major, Minor, or Warning.
- history of changes to the event in the form of audit logs.
Alarm suppression - If the source device is in maintenance mode, the alarm is neither created nor reported to the Cumulocity IoT event processing engine. When sending a POST request to create a new alarm and if the source device is in maintenance mode, the self-link of the alarm is:
```
"self": "https://<TENANT_DOMAIN>/alarm/alarms/null" 
```
Alarm de-duplication - If an Active or Acknowledged alarm with the same source and type exists, no new alarm is created. Instead, the existing alarm is updated by incrementing the count property and the time property. Any other changes are ignored, and the alarm history is not updated. Alarms with status Cleared are not de-duplicated. The first occurrence of the alarm is recorded in the firstOccurrenceTime property.

Required roles: ROLE_ALARM_ADMIN OR owner of the source OR ALARM_ADMIN permission on the source.
Remove alarm collections: Remove the alarm collections specified by query parameters.

Important

If no parameter is provided in the endpoint, then all alarms are deleted. This action is not recommended. Also, the delete requests are not synchronous and the response can be returned before the delete request has been completed.

Required roles: ROLE_ALARM_ADMIN.
Retrieve a specific alarm: Get a specific alarm by a given ID.
Required roles: ROLE_ALARM_READ or owner of the source or ALARM_READ permission on the source.
Update a specific alarm: Update a specific alarm by a given ID. Only text, status, severity, and custom properties can be modified. Requests containing non-modifiable properties are rejected.

Note

Changes to alarms generate a new audit record. The audit record includes the username and application that triggered the update, if applicable. If the Update operation does not change anything, that is, the request body contains data that is identical to that already present in the database, the operation is ignored and no notifications are sent.

Required roles: ROLE_ALARM_ADMIN or owner of the source or ALARM_ADMIN permission on the source.
Retrieve the total number of alarms: Get the total number of active alarms on your tenant.
Required roles: The role ROLE_ALARM_READ is not required, but if a user has this role, all alarms on the tenant are counted. Otherwise, inventory role permissions are used to count the alarms and the limit is 100.

Tenants API

Retrieve all subtenants: Get all the subtenants of the current tenant.
Required roles: ROLE_TENANT_MANAGEMENT_READ.
Retrieve the current tenant: Get the information about the current tenant.
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Retrieve a specific tenant: Get a specific tenant (by a given ID).
Required roles: ROLE_TENANT_MANAGEMENT_READ and the current tenant is its parent or is the management tenant.
Update a specific tenant: Update a specific tenant (by a given ID).
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent, and the current tenant is allowed to create subtenants) or is the management tenant.
Remove a specific tenant: Remove a specific tenant by a given ID.

Important

Deleting a subtenant cannot be reverted. Hence, for security reasons, the Remove action is available only in the management tenant. You cannot delete tenants from any other tenants, but the management tenant. Administrators in Enterprise tenants are only allowed to suspend active subtenants only, and not delete them.

Required roles: ROLE_TENANT_MANAGEMENT_ADMIN and is the management tenant.
Retrieve TFA settings of a specific tenant: Get the two-factor authentication settings of a specific tenant (by a given tenant ID).
Required roles: (ROLE_TENANT_MANAGEMENT_READ) OR (ROLE_USER_MANAGEMENT_READ) and (the current tenant is its parent or is the management tenant or the current user belongs to the tenant) or the user belongs to the tenant and (ROLE_USER_MANAGEMENT_OWN_READ).
Retrieve subscribed applications: Get the subscribed applications (by a given tenant ID).
Required roles (ROLE_TENANT_MANAGEMENT_READ OR ROLE_TENANT_ADMIN) and (the current tenant is its parent or is the management tenant).
Subscribe to an application: Subscribe a tenant (by a given ID) to an application.
Required roles: (ROLE_APPLICATION_MANAGEMENT_ADMIN and is the application owner and is the current tenant) OR ((ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent or is the management tenant)).
Unsubscribe from an application: Unsubscribe a tenant (by a given tenant ID) from an application (by a given application ID).
Required roles: (ROLE_APPLICATION_MANAGEMENT_ADMIN and is the application owner and is the current tenant) or ((ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_UPDATE) and (the current tenant is its parent or is the management tenant)).
Retrieve all stored certificates: Get all the trusted certificates of a specific tenant (by a given ID).
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).
Add a new certificate: Add a new trusted certificate to a specific tenant (by a given ID) which can be further used by the devices to establish connections with the Cumulocity IoT platform.
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).
Add multiple certificates: Add multiple trusted certificates to a specific tenant (by a given ID) which can be further used by the devices to establish connections with the Cumulocity IoT platform.
Required roles (ROLE_TENANT_MANAGEMENT_ADMIN) OR (ROLE_TENANT_ADMIN) and (is the current tenant).
Retrieve a stored certificate: Get the data of a stored trusted certificate (by a given fingerprint) of a specific tenant (by a given ID).
Required roles (ROLE_TENANT_MANAGEMENT_ADMIN) or (ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).
Update a stored certificate: Update the data of a stored trusted certificate (by a given fingerprint) of a specific tenant (by a given ID).
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).
Remove a stored certificate: Remove a stored trusted certificate (by a given fingerprint) from a specific tenant (by a given ID).
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and (is the current tenant or is the management tenant).
Provide the proof of possession for an already uploaded certificate: Provide the proof of possession for a specific uploaded certificate (by a given fingerprint) for a specific tenant (by a given ID).
Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the current tenant.
Confirm an already uploaded certificate: Confirm an already uploaded certificate (by a given fingerprint) for a specific tenant (by a given ID).
Required roles:(ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the management tenant.
Generate a verification code for the proof of possession operation for the given certificate: Generate a verification code for the proof of possession operation for the certificate (by a given fingerprint).
(ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_ADMIN) and is the current tenant.
Retrieve monthly device statistics: Get the monthly device statistics from a specific tenant (by a given ID).
Required roles: ROLE_TENANT_STATISTICS_READ.
Retrieve daily device statistics: Get the daily device statistics from a specific tenant (by a given ID).
Required roles: ROLE_TENANT_STATISTICS_READ.
Retrieve statistics of the current tenant: Get the usage statistics of the current tenant.
Required roles: ROLE_TENANT_STATISTICS_READ.
Retrieve a usage statistics summary: Get the usage statistics summary of a tenant.
Retrieve a summary of all usage statistics: Get a summary of all tenant usage statistics.
Required roles: ROLE_TENANT_MANAGEMENT_READ.
Retrieve usage statistics files metadata: Get the usage statistics summary files report metadata.
Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.
Generate a statistics file report: Generate a test statistics file report for a given time range. There are two types of statistics files:
- REAL: generated by the system on the first day of the month and includes statistics from the previous month to till date.
- TEST: generated by the user with a time range specified in the query parameters: dateFrom and dateTo.
Required roles: ROLE_TENANT_MANAGEMENT_ADMIN OR ROLE_TENANT_MANAGEMENT_CREATE.
Retrieve a usage statistics file: Get a specific usage statistics file (by a given ID).
Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.
Retrieve the latest usage statistics file: Get the latest usage statistics file with real data for a given month. There are two types of statistics files:
- REAL: generated by the system on the first day of the month and includes statistics from the previous month to till date.
- TEST - generated by the user with a time range specified in the query parameters, dateFrom and dateTo.
Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.
Retrieve all options: Get all the options available on the tenant.
Required roles: ROLE_OPTION_MANAGEMENT_READ.

Create an option: Create an option on your tenant. Options are category-key-value tuples that store tenant configurations. Some categories of options allow the creation of new ones, while others are limited to predefined set of keys. Any option of any tenant can be defined as “non-editable” by the “management” tenant; once done, any PUT or DELETE requests made on that option by the tenant owner will result in a 403 error (Unauthorized).

Default option categories

access.control

Key	Default value	Predefined	Description
allow.origin	*	Yes	Comma separated list of domains allowed for running CORS. Wildcards are allowed, for example, .cumuclocity.com.

alarm.type.mapping

Key	Predefined	Description
ALARM_TYPE	No	Overrides the severity and alarm text for the alarm with type <ALARM_TYPE. The severity and text are specified as \|. If either part is empty, the value is not overridden. If the severity is None, the alarm is suppressed. For example, CRITICAL\|temperature too high.

Encrypted credentials

Adding a credentials. prefix to the key makes the value of the option encrypted. When the option is sent to a microservice, the credentials. prefix is removed and the value is decrypted. For example:

        { "category": "secrets",
          "key": "credentials.mykey",
          "value": "myvalue" 
        }

In the example, the request contains an additional header Mykey: myvalue.

Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Retrieve all options by category: Get all the options (by a specified category) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_READ.
Update options by category: Update one or more options (by a specified category) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.
Retrieve a specific option: Get a specific option (by a given category and key) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_READ.
Update a specific option: Update the value of a specific option (by a given category and key) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_ADMIN and the option is editable.
Remove a specific option: Remove a specific option (by a given category and key) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.
Retrieve all login options: Get all the login options available in the tenant.
Create a login option: Create an authentication configuration on your tenant.
Required roles: ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN.
Retrieve a specific login option: Get a specific login option in the tenant by the given type or ID.
Required roles: ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) or (ROLE_USER_MANAGEMENT_OWN_ADMIN or ROLE_USER_MANAGEMENT_CREATE) and tenant access to login option is not restricted by management tenant).
Update a specific login option: Update a specific login option in the tenant by a given type or ID.
Required roles ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) and tenant access to login option is not restricted by management tenant).
Delete a specific login option: Delete a specific login option in the tenant by a given type or ID.
Required roles: ((ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN) and tenant access to login option is not restricted by management tenant).
Update a tenant’s access to the login option: Update the tenant’s access to the authentication configuration.
Required roles: ROLE_TENANT_MANAGEMENT_ADMIN and is the management tenant.
Retrieve all system options: Get all the system options available on the tenant.
Retrieve a specific system option: Get a specific system option (by a given category and key) on your tenant.
Required roles: ROLE_OPTION_MANAGEMENT_ADMIN.

Users API

Retrieve the current user: Get the reference of the current user.
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Update the current user: Update the current user.
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Update the current user’s password: Update the current user’s password.

Important

If the tenant uses OAI-Secure authentication, the current user will not be logged out. Instead, a new cookie will be set with a new token, and the previous token will expire within a minute.

Required roles: ROLE_USER_MANAGEMENT_OWN_ADMIN.
Generate secret to set up TFA: Generates a secret code to create a QR code to set up the two-factor authentication functionality using a TFA app/service. For more information about the feature, see the User Guide in the Cumulocity IoT documentation for Two-factor authentication (TFA).
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Returns the activation state of the two-factor authentication feature: Retrieves the activation state of the two-factor authentication feature for the current user.
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Activates or deactivates the two-factor authentication feature: Activates or deactivates the two-factor authentication feature for the current user. For more information about the feature, see the User Guide in the Cumulocity IoT documentation for Two-factor authentication (TFA).
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Verify TFA code: Verifies the authentication code that the current user received from a TFA app/service and uploaded to the platform to gain access or enable the two-factor authentication feature.
Required roles: ROLE_USER_MANAGEMENT_OWN_READ OR ROLE_SYSTEM.
Retrieve all users for a specific tenant: Get all the users for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.
Create a user for a specific tenant: Create a user for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND has access to roles, groups, device permissions and applications.
Retrieve a specific user for a specific tenant: Get a specific user (by a given user ID) for a specific tenant (by a given tenant ID). Users in the response are sorted by username in ascending order. Only objects that the user is allowed to see are returned to the user. The user password is never returned in a GET response. Authentication mechanism is provided by another interface.
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.
Update a specific user for a specific tenant: Update a specific user (by a given user ID) for a specific tenant (by a given tenant ID). Any change in user’s role, device permission, and group details create corresponding audit records with type User and activity User updated. The audit records include information about the properties updated. When a user is updated with changed permissions or groups, a corresponding audit record is created with type User and activity User updated.
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND has access to device permissions and applications.
Delete a specific user for a specific tenant: Delete a specific user (by a given user ID) for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND not the current user.
Update a specific user’s password of a specific tenant: Update a specific user’s password (by a given user ID) of a specific tenant (by a given tenant ID). Changing the user’s password creates a corresponding audit record of type “User” and activity “User updated” specifying that the password has been changed.

Important

If the tenant uses OAI-Secure authentication, the target user will be logged out.

Required roles: ROLE_USER_MANAGEMENT_ADMIN to update root users in a user hierarchy or users that are not in any hierarchy. ROLE_USER_MANAGEMENT_ADMIN to update non-root users in a user hierarchy and whose parents have access to assigned roles, groups, device permissions and applications. ROLE_USER_MANAGEMENT_CREATE to update descendants of the current user in a user hierarchy and whose parents have access to assigned roles, groups, device permissions and applications.
Retrieve the TFA settings of a specific user: Get the two-factor authentication settings for the specified user.
Required roles: ROLE_USER_MANAGEMENT_READ or(ROLE_USER_MANAGEMENT_CREATE and is parent of the user) or is the current user.
Retrieve a user by username in a specific tenant: Get a user by username in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.
Retrieve the users of a specific user group of a specific tenant: Get the users of a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR (ROLE_USER_MANAGEMENT_CREATE AND has access to the user group).
Add a user to a specific user group of a specific tenant: Add a user to a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.
Remove a specific user from a specific user group of a specific tenant: Remove a specific user (by a given user ID) from a specific user group (by a given user group ID) of a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user.
Terminate a user’s session: Ends a user’s session after logging out. A user must enter valid credentials again to get access to the platform. The request is responsible for removing cookies from the browser and invalidating internal platform access tokens.
Retrieve all user groups of a specific tenant: Get all the user groups of a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.
Create a user group for a specific tenant: Create a user group for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Retrieve a specific user group for a specific tenant: Get a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID). Required roles: ROLE_USER_MANAGEMENT_ADMIN OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user.
Update a specific user group for a specific tenant: Update a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Delete a specific user group for a specific tenant: Delete a specific user group (by a given user group ID) for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Retrieve a user group by group name for a specific tenant: Get a user group by group name for a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to groups.
Get all user groups for specific user in a specific tenant: Retrieve all the user groups for a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.
Retrieve all user roles: Get all the user roles.
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to the user role.
Retrieve a user role by name: Get a user role by name.
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND the current user has access to the role with this name.
Retrieve all roles assigned to a specific user group in a specific tenant: Get all the roles assigned to a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ.
Assign a role to a specific user group in a specific tenant: Assign a role to a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Unassign a specific role for a specific user group in a specific tenant: Unassign a specific role (given by a role ID) for a specific user group (by a given user group ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Assign a role to specific user in a specific tenant: Assign a role to a specific user (by a given user ID) in a specific tenant (by a given tenant ID). When a role is assigned to a user, a corresponding audit record is created with type User and activity User updated.
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user.
Unassign a specific role from a specific user in a specific tenant: Unassign a specific role (by a given role ID) from a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND has access to roles.
Retrieve all inventory roles: Get all the inventory roles.
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE.
Create an inventory role: Create an inventory role.
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Retrieve a specific inventory role: Get a specific inventory role (by a given ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND has access to the inventory role.
Update a specific inventory role: Update a specific inventory role (by a given ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Remove a specific inventory role: Remove a specific inventory role (by a given ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Retrieve all inventory roles assigned to a user: Get all the inventory roles assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is the parent of the user.
Assign an inventory role to a user: Assign an existing inventory role to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN AND (is not in user hierarchy OR is root in the user hierarchy) OR ROLE_USER_MANAGEMENT_ADMIN AND is in user hierarchy AND has parent access to inventory assignments OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user AND has current user access to inventory assignments AND has parent access to inventory assignments.
Retrieve a specific inventory role assigned to a user: Get a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_READ OR ROLE_USER_MANAGEMENT_CREATE AND is the parent of the user.
Update a specific inventory role assigned to a user: Update a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.
Remove a specific inventory role assigned to a user: Remove a specific inventory role (by a given ID) assigned to a specific user (by a given user ID) in a specific tenant (by a given tenant ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN AND (is not in user hierarchy OR is root in the user hierarchy) OR ROLE_USER_MANAGEMENT_ADMIN AND is in user hierarchy AND has parent access to inventory assignments OR ROLE_USER_MANAGEMENT_CREATE AND is parent of the user AND is not the current user AND has current user access to inventory assignments AND has parent access to inventory assignments.
Returns all device permissions assignments: Get all device permissions assignments if the current user has READ permission.
Required roles: ROLE_USER_MANAGEMENT_READ orROLE_USER_MANAGEMENT_CREATE
Updates the device permissions assignments: Update the device permissions assignments if the current user has ADMIN permission or CREATE permission and all device permissions.
Required roles: ROLE_USER_MANAGEMENT_ADMINorROLE_USER_MANAGEMENT_CREATE.

Audits API

Retrieve all audit records: Get all the audit records registered on your tenant, or a specific subset based on queries.
Create an audit record: Create an audit record.
Required roles: ROLE_AUDIT_ADMIN OR ROLE_SYSTEM OR AUDIT_ADMIN permission on the resource.
Retrieve a specific audit record: Get a specific audit record by a given ID.
Required roles: ROLE_AUDIT_READ OR AUDIT_READ permission on the source.

Realtime Notifications API

Responsive communication: The Real-time notification API enables responsive communication from Cumulocity IoT over restricted networks towards clients such as web browser and mobile devices. All clients subscribe to channels to receive messages. These channels are updated with the output of Operations. In addition, particular system channels are used for the initial handshake with clients, subscription to channels, removal from channels, and connection. The Bayeux Protocol over HTTPS or WSS is used as communication mechanism.

Events API

Retrieve all events: Gets all the events on your tenant. In case of running range queries between an upper and lower boundaries (dateFrom–dateTo or createdFrom–createdTo), the oldest registered measurements are returned first. It is possible to change the order using the query parameter revert=true.
Required roles: ROLE_EVENT_READ.
Create an event: Create an event which is associated with a source (managed object) identified by an ID. In general, each event consists of:
- type to identify the nature of the event.
- time stamp to indicate when the event is last updated.
- description of the event.
- managed object which originated the event.
Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.
Remove event collections: Remove the event collections specified by query parameters. The delete requests are not synchronous. The response is returned before the delete request has been completed. This may happen especially when the deleted event has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested event is deleted after all associated data has been deleted.

Important

If no parameter is provided in the endpoint, then all measurements are deleted. This action is not recommended.

Required roles: ROLE_EVENT_ADMIN.
Retrieve a specific event: Get a specific event by a given ID.
Required roles: ROLE_EVENT_READ OR owner of the source OR EVENT_READ permission on the source.
Update a specific event: Update a specific event by a given ID. Only the text description and custom fragments of an event can be updated.
Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.
Remove a specific event: Remove a specific event by a given ID.
Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.
Retrieve the attached file of a specific event: Get the attached file (binary) of a specific event by a given ID.
Required roles: ROLE_EVENT_READ OR EVENT_READ permission on the source.
Remove the attached file from a specific event: Remove the attached file (binary) from a specific event by a given ID.
Required roles: ROLE_EVENT_ADMIN or owner of the source or EVENT_ADMIN permission on the source.

Notifications 2.0 API

Retrieve all subscriptions: Get all the subscriptions on your tenant or a specific subset based on queries.
Required roles: ROLE_NOTIFICATION_2_ADMIN.
Create a subscription: Create a new subscription, for example, a subscription that forwards measurements and events of a specific type for a given device. In general, each subscription may consist of the following components:
- managed object to which the subscription is associated.
- context under which the subscription is to be processed.
- name of the subscription.
- applicable filter criteria.
- option to only include specific custom fragments in the forwarded data.
Required roles: ROLE_NOTIFICATION_2_ADMIN.
Remove subscriptions by source: Remove subscriptions by source and context.

Note

The request results in an error if there are no query parameters. The source parameter is optional only if the context parameter equals tenant.

Required roles: ROLE_NOTIFICATION_2_ADMIN.
Retrieve a specific subscription: Get a specific subscription by a given ID.
Required roles: ROLE_NOTIFICATION_2_ADMIN.
Remove a specific subscription: Remove a specific subscription by a given ID.
Required roles: ROLE_NOTIFICATION_2_ADMIN.
Create a notification token: Create a new JWT (JSON web token) access token that can be used to establish a successful WebSocket connection to read a sequence of notifications. In general, each request obtains an access token that consists of the following details:
- subscriber name that the client wants to be identified with.
- subscription name. This value must be associated with an already existing subscription (that is, the obtained token provides the ability to read notifications for the subscription that is specified here).
- token expiry duration.
Required roles: ROLE_NOTIFICATION_2_ADMIN.
Unsubscribe a subscriber: Unsubscribe a notification subscriber using the notification token. Once a subscription is made, notifications are stored until they are consumed by all subscribers who have previously connected to the subscription. For non-volatile subscriptions, this can lead to notifications being stored indefinitely if they are not consumed by the application. However, if a tenant is deleted, these notifications are removed. This can consume significant space in permanent storage for sources that generate notifications frequently. Therefore, unsubscribe a subscriber that is no longer active.

Retentions API

Retrieve all retention rules: Get all the retention rules on your tenant.
Required roles: ROLE_RETENTION_RULE_READ.
Create a retention rule: Create a retention rule on your tenant.
Required roles: ROLE_RETENTION_RULE_ADMIN.
Retrieve a retention rule: Get a specific retention rule by a given ID.
Required roles: ROLE_RETENTION_RULE_READ.
Update a retention rule: Update a specific retention rule by a given ID.
Required roles: ROLE_RETENTION_RULE_ADMIN AND (the rule is editable, OR it is the tenant management).
Remove a retention rule: Remove a specific retention rule by a given ID.
Required roles: ROLE_RETENTION_RULE_ADMIN AND the rule is editable.

Identity API

Retrieve URIs to collections of external IDs: Get the URIs and URI templates for associating external identifiers with unique identifiers.
Required roles: ROLE_IDENTITY_READ.
Retrieve all external IDs of a specific managed object: Get all the external IDs of an existing managed object (identified by ID).
Required roles: ROLE_IDENTITY_READ or owner of the resource or MANAGED_OBJECT_READ permission on the resource.
Create an external ID: Create an external ID for an existing managed object (identified by ID).
Required roles: ROLE_IDENTITY_ADMIN or owner of the resource or MANAGED_OBJECT_ADMIN permission on the resource.
Retrieve a specific external ID: Get a specific external ID of a particular type.
Required roles: ROLE_IDENTITY_READ or owner of the resource or MANAGED_OBJECT_READ permission on the resource.
Remove a specific external ID: Remove a specific external ID of a particular type.
Required roles: ROLE_IDENTITY_ADMIN or owner of the resource or MANAGED_OBJECT_ADMIN permission on the resource.

DeviceControl API

Retrieve a list of operations: Get a list of operations.
Note
- The embedded operation object contains deviceExternalIDs, only when queried with an agentId parameter.
- The embedded operation object is filled with deviceName, but only when requesting the resource: Get a collection of operations.
- Operations are returned in the order of their ascending IDs.
Required roles: ROLE_DEVICE_CONTROL_READ.
Create an operation: Create an operation.
Required roles: ROLE_DEVICE_CONTROL_ADMIN OR owner of the device OR ADMIN permissions on the device.
Delete a list of operations: Delete a list of operations. The DELETE method allows for deletion of operation collections.
Required roles: ROLE_DEVICE_CONTROL_ADMIN.
Retrieve a specific operation: Get a specific operation (by a given ID).
Required roles: ROLE_DEVICE_CONTROL_READ OR owner of the resource OR ADMIN permission on the device.
Update a specific operation status: Update a specific operation (by a given ID). You can only update its status.
Required roles: ROLE_DEVICE_CONTROL_ADMIN OR owner of the resource OR ADMIN permission on the device.
Retrieve a list of bulk operations: Get a list of bulk operations.
Required roles: ROLE_BULK_OPERATION_READ.
Create a bulk operation: Create a bulk operation.
Required roles: ROLE_BULK_OPERATION_ADMIN.
Retrieve a specific bulk operation: Get a specific bulk operation (by a given ID).
Required roles: ROLE_BULK_OPERATION_READ.
Update a specific bulk operation: Update a specific bulk operation (by a given ID).
Required roles ROLE_BULK_OPERATION_ADMIN.
Delete a specific bulk operation: Delete a specific bulk operation (by a given ID).
Required roles: ROLE_BULK_OPERATION_ADMIN.
Retrieve a list of new device requests: Get a list of new device requests.
Required roles: ROLE_DEVICE_CONTROL_READ.
Create a new device request: Create a new device request.
Required roles: ROLE_DEVICE_CONTROL_ADMIN.
Retrieve a specific new device request: Get a specific new device request (by a given ID).
Required roles: ROLE_DEVICE_CONTROL_READ.
Update a specific new device request status: Update a specific new device request (by a given ID). You can only update its status.
Required roles: ROLE_DEVICE_CONTROL_ADMIN.
Delete a specific new device request: Delete a specific new device request (by a given ID).
Required roles: ROLE_USER_MANAGEMENT_ADMIN.

Inventory API

Retrieve all managed objects: Get all the managed objects, for example, devices, assets, and so on, registered in your tenant, or a subset based on queries.
Create a managed object: Create a managed object, for example, a device with temperature measurements support or a binary switch. In general, each managed object may consist of:
- A unique identifier that references the object.
- The name of the object.
- The most specific type of the managed object.
- Time stamp showing the last update.
- Fragments with specific meanings, for example, c8y_IsDevice, c8y_SupportedOperations.
- Any additional custom fragments.
For example, you want to describe electric meters from different vendors. Depending on the make of the meter, one may have a relay and one may be capable to measure a single phase or three phases (for example, a three-phase electricity sensor). A fragment C8y_ThreePhaseElectricitySensor would identify such an electric meter. Device characteristics are identified by storing fragments for each of them.

Note

For more details about fragments with specific meanings, see Device Management Library and Sensor Library.

Required roles: ROLE_INVENTORY_ADMIN OR ROLE_INVENTORY_CREATE.
Retrieve the total number of managed objects: Get the total number of managed objects, for example, devices, assets, and so on, registered in your tenant, or a subset based on queries.
Required roles: ROLE_INVENTORY_READ is not required, but if the current user does not have this role, the response will contain the number of inventory objects accessible for the user.
Retrieve a specific managed object: Get a specific managed object (for example, device, group, template) by a given ID.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Update a specific managed object: Update a specific managed object (for example, device) by a given ID. For example, if you want to specify that your managed object is a device, you must add the fragment c8y_IsDevice.
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.
Remove a specific managed object: Remove a specific managed object (for example, device) by a given ID.

Note

Inventory DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted managed object has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested managed object is deleted after all associated data has been deleted.

Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.
Retrieve the latest availability date of a specific managed object: Get the date when a specific managed object (by a given ID) sent the last message to Cumulocity IoT.
Required roles: ROLE_INVENTORY_READ.
Retrieve all supported measurement fragments of a specific managed object: Get all the measurement types of a specific managed object by a given ID.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Retrieve all supported measurement fragments and series of a specific managed object: Get all the supported measurement fragments and series of a specific managed object by a given ID.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Retrieve the username and state of a specific managed object: Get the device owner’s username and state (enabled or disabled) of a specific managed object (by a given ID).
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Update the user’s details of a specific managed object: Update the device owner’s state (enabled or disabled) of a specific managed object (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source OR MANAGE_OBJECT_ADMIN permission on the source.
Search for stored files: Retrieve metadata information about stored files. Search for files by query parameters. This will not download the files.
Retrieve a stored file: Get a stored file (managed object) by a given ID.
Required roles: ROLE_INVENTORY_READ OR owner of the resource OR MANAGE_OBJECT_READ permission on the resource.
Remove a stored file: Remove a managed object and its stored file by a given ID.
Required roles: ROLE_INVENTORY_ADMIN OR owner of the resource OR MANAGE_OBJECT_ADMIN permission on the resource.
Retrieve all child additions of a specific managed object: Get all child additions of a specific managed object by a given ID, or a subset based on queries.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Assign a managed object as child addition: Assign a managed object as child. The possible ways to assign child objects are:
- Assign an existing managed object (by a given child ID) as child addition of another managed object (by a given ID).
- Assign multiple existing managed objects (by given child IDs) as child additions of another managed object (by a given ID).
- Create a managed object in the inventory and assign it as a child addition to another managed object (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR ((owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child)).
Remove specific child additions from its parent: Remove specific child additions (by given child IDs) from its parent (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).
Retrieve a specific child addition of a specific managed object: Get a specific child addition (by a given child ID) of a specific managed object (by a given ID).
Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).
Remove a specific child addition from its parent: Remove a specific child addition (by a given child ID) from its parent (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).
Retrieve all child assets of a specific managed object: Get all child assets of a specific managed object by a given ID, or a subset based on queries.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Assign a managed object as child asset: Assign a managed object as child asset. The possible ways to assign child objects are:
- Assign an existing managed object (by a given child ID) as child asset of another managed object (by a given ID).
- Assign multiple existing managed objects (by given child IDs) as child assets of another managed object (by a given ID).
- Create a managed object in the inventory and assign it as a child asset to another managed object (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR ((owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child)).
Remove specific child assets from its parent: Remove specific child assets (by given child IDs) from its parent (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).
Retrieve a specific child asset of a specific managed object: Get a specific child asset (by a given child ID) of a specific managed object (by a given ID).
Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).
Remove a specific child asset from its parent: Remove a specific child asset (by a given child ID) from its parent (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).
Retrieve all child devices of a specific managed object: Get all child devices of a specific managed object by a given ID, or a subset based on queries.
Required roles: ROLE_INVENTORY_READ OR owner of the source OR MANAGE_OBJECT_READ permission on the source.
Assign a managed object as child device: Assign a managed object as child device. The possible ways to assign child objects are:
- Assign an existing managed object (by a given child ID) as child device of another managed object (by a given ID).
- Assign multiple existing managed objects (by given child IDs) as child devices of another managed object (by a given ID).
- Create a managed object in the inventory and assign it as a child device to another managed object (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR ((owner of the source OR MANAGE_OBJECT_ADMIN permission on the source) AND (owner of the child OR MANAGE_OBJECT_ADMIN permission on the child).
Remove specific child devices from its parent: Remove specific child devices (by given child IDs) from its parent (by a given ID).
Required roles ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).
Retrieve a specific child device of a specific managed object: Get a specific child device (by a given child ID) of a specific managed object (by a given ID).
Required roles: ROLE_INVENTORY_READ OR MANAGE_OBJECT_READ permission on the source (parent).
Remove a specific child device from its parent: Remove a specific child device (by a given child ID) from its parent (by a given ID).
Required roles: ROLE_INVENTORY_ADMIN OR owner of the source (parent) OR owner of the child OR MANAGE_OBJECT_ADMIN permission on the source (parent).

Cumulocity IoT OEE

Cumulocity IoT OEE allows you to easily integrate the OEE data of your machine park with your or other business systems. You can update the OEE App with shift and production plans.

API Versions: 10.10.0.3

API Types: REST

Authentication and Authorization: Basic

Prerequisites:

Cumulocity OEE login and password information.
Required permission for reading is ROLE_OEECONFIGURATOR_READ.
Required permission for creating, editing, or deleting is ROLE_OEECONFIGURATOR_ADMIN.

The connector authenticates via an application in the Cumulocity tenant. During initial setup of the connection, this application is created automatically.

Actions

getShiftplan: Retrieves the Shiftplan for the given locationId. The response is empty if no Shiftplan is provided before by using the createShiftplan method.
createShiftplan: Creates the Shiftplan for the locationId. The tenantId is indirectly retrieved within the service using the credentials. Do not specify a tenantId in the body. If a Shiftplan exists for the given tenant and location, the new Shiftplan will be merged internally, and obsolete Timeslots will be removed. The resulting Shiftplan is sent to the Apama service. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
deleteShiftplan: Deletes the Shiftplan for the given locationId. The response is empty if no Shiftplan is provided before by using the createShiftplan method. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
getProductionplanlist: Retrieves the Productionplanlist for the given deviceId. The response is empty if no Productionplan is provided before by using the createProductionplanlist method.
createProductionplanlist: Creates a list of Productionplanlist for the deviceId defined in the Productionplan. The tenantId is indirectly retrieved within the service using the credentials. Do not specify a tenantId in the body. If a Productionplan exists for the given tenant and device, the new Productionplan will be merged internally, and obsolete Timeslots will be removed. The resulting Productionplan is sent to the Apama service. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
deleteProductionplanlist: Deletes the Productionplanlist for the given deviceId. The response is empty if no Productionplan is provided before by using the createProductionplanlist method. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
getAllConfigurations: Retrieves all the configurations defined in the tenant.
createConfiguration: Adds a new machine or line configuration to the tenant. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
getConfiguration: Retrieves the configuration with the given configurationId.
updateConfiguration: Updates the configuration with the given configurationId. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
deleteConfiguration: Deletes the configuration with the given configurationId. Required permission: ROLE_OEECONFIGURATOR_ADMIN.
getSupportedMeasurementsByCategory: Retrieves all the supported message descriptors for the given deviceId and chosen category.
getSupportedMeasurements: Retrieves all the supported measurements for the given deviceId.

Dweet

Dweet.io helps you connect to wide range of devices such as sensors, machines, robots, gadgets through its APIs.

Actions

Get Latest Dweets: Retrieve latest dweet for a thing
Get Dweet History: Retrieve list of all the dweets saved for a particular thing
Create Dweet: Create a new Dweet

Fitbit

Fitbit provides fitness tracking devices and other wireless-enabled wearable technology devices that can improve your health by tracking your activity, exercise, food, weight and sleep.

Actions

Get Activities: Get activities and activity log entries of a user for a given day
Get Activity Stat: Get the user’s lifetime activity statistics
Get Blood Pressure: Get average value and log entries of user’s blood pressure for a given day
Get Body Measurement: Get the user’s body measurements for a given day
Get Devices: Get list of devices connected to a user
Get Goals Daily: Get the user’s daily activity goals
Get Goals Weekly: Get the user’s weekly activity goals
Get Heart Rate: Get average value and log entries of user’s heart rate for a given day
Get Sleep: Get summary and log details of user’s sleep for a given day
User Details: Get the profile information of the user

Gimbal

Gimbal is a location and proximity-based mobile engagement platform that lets you synchronize device information, working status, battery and modes in real-time.

Actions

Application Details: Fetch the details of a specific application
Communication Details: Fetch the details of a specific communication
Delete Communication: Delete a specific communication
Delete Place: Delete a specific place
Geofence Delete: Delete a specific geofence
Geofence Details: Retrieve the details of a specific geofence
Get Applications: Retrieve the configuration details of a specific application
Get Communications: Retrieve the details of a specific communication
Get Geofences: Retrieve the details of all geofences
Get Places: Retrieve details of all places
Place Details: Retrieve the details of a specific place

Google Maps

Google Maps is a web mapping service that provides accurate, reliable location information in real-time, helping you with easy and hassle-free navigation.

Actions

Get Direction: Retrieve the direction to reach any place or location
Get Distance Matrix: Retrieve the travel distance and time for a matrix of origins and destinations

Google Places

Google Places is an online service that helps you to provide accurate information such as location name, addresses, ratings, reviews, contact information, and atmosphere to users.

Actions

Search Places: Find any place or location

Initial State

Initial State provides data analytics for the Internet of Things (IoT).

Actions

Send Events Data: Send multiple events data to any bucket available
Create Bucket: Create a new bucket

Keen.io

Keen.io is a set of powerful APIs that allows you to build your own analytics products.

Actions

Get Projects: Get the list of all existing projects
Get Project Details: Get more details about a project
Get Events Collection Details: Get more details about a particular events collection
Get Events: Get the list of all events of a project
Delete Events Collection: Delete the existing events collection
Create Event: Create a new event in your account

LIFX

LIFX is a line of wi-fi enabled bulbs that can be controlled through a wide range of wi-fi equipped devices.

Actions

Get Lights: Retrieve the details of the specified light(s)
Set Light State: Set the state of a specific light or all lights
Set Toggle Power: Turn on/turn off a specific light or all lights

Nest

Nest Labs is a home automation company that provides programmable smoke detectors and thermostats.

Triggers

State Change: Triggers when the state changes

Actions

Get Thermostat Device Info: Get more details about a specific nest thermostat device
Get Temperature of Thermostat: Get the current temperature of a Nest thermostat
Set Temperature of Thermostat: Set the temperature of any installed Nest thermostat
Get All Thermostat Devices Info: Get the list and details of all the installed Nest thermostat devices
Get State of Structure: Get the current state of the structure
Set State of Structure: Set the current state of the structure

Philips Hue

Philips Hue is a wireless lighting system that lets you easily control LED lamps and white bulbs from your phone or tablet.

Actions

Create User: Create a new user
Get All Lights: Retrieve the details of the specified light(s)
Get Bridges: Get information associated with the specified bridge(s)
Set Light State: Set the state of a specific light or all lights

Plotly

Plotly is a technical computing company that helps you to create, deploy and share interactive web apps, graphs and visualizations in any programming language.

Actions

Create Graph: Create a new graph

Tesla

Tesla is an electric vehicle and clean energy company that designs, develops, manufactures, and sells fully electric vehicles and energy storage systems.

Actions

Auto Park: Auto park the Tesla
Flash Lights: Flash the lights of Tesla
Get Driving and Position State: Get the driving and position state of the Tesla
Get Vehicle State: Get vehicle state of Tesla
Honk Horn: Honk the horn of Tesla
List all Vehicles: List all vehicles
Lock Doors: Lock doors of the Tesla
Move Pano Roof: Move pano roof of the Tesla
Open Charge Port: Open the charge port of the Tesla
Open Trunk: Open the trunk of Tesla
Remote Start: Remote start the Tesla
Set Charge Limit to Max Range: Set charge limit to maximum range
Set Charge Limit to Standard: Set charge limit to standard
Set Temperature: Set temperature
Set Valet Mode: Set valet mode for Tesla
Start Charging: Start charging the Tesla
Start HVAC System: Start the HVAC system for Tesla
Stop Charging: Stop charging the Tesla
Stop HVAC System: Stop the HVAC system for Tesla
Unlock Doors: Unlock the doors of Tesla
Wake Up Car: Wake up car

Amazon Alexa

Actions

Cisco Meraki

Actions

Common Questions

Cumulocity (Deprecated)

Triggers

Actions

Custom Actions

Cumulocity IoT

Triggers

FAQs

Is it possible to subscribe to smart groups of devices?

Is it possible to subscribe events for all devices on the Cumulocity IoT tenant?

How can I subscribe to a managed object that is neither a device nor a group?

Actions

Application API

Measurements API

Alarms API

Tenants API

Users API

Audits API

Realtime Notifications API

Events API

Notifications 2.0 API

Retentions API

Identity API

DeviceControl API

Inventory API

Cumulocity IoT OEE

Actions

Dweet

Actions

Fitbit

Actions

Gimbal

Actions

Google Maps

Actions

Google Places

Actions

Initial State

Actions

Keen.io

Actions

LIFX

Actions

Nest

Triggers

Actions

Philips Hue

Actions

Plotly

Actions

Tesla

Actions