IoT

Amazon Alexa

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

Availability: Workflows only

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.

Availability: Workflows only

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 webMethods.io 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 given on the top-right hand side of the dashboard window.

  

  A new window will appear 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 on the ‘ADD’ button. You can now see the added connection under ‘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)

NOTES

The Cumulocity connector is deprecated and will become obsolete in a later release. If you are creating new Workflows or FlowServices, it is recommended to use the alternative connector - Cumulocity IoT.

Deprecated connectors will continue to work as before and are fully supported by Software AG.

If you are using deprecated connectors in your existing Workflows and/or FlowServices, 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.

Availability: Workflows and FlowServices

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.

Availability: Workflows and FlowServices

API Versions: 10.13

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 webMethods.io 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 Software AG Cloud 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

• 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

Filters can be applied to triggers to respond to only specific notifications. For example, setting an alarm trigger to type c8y_UnavailabiltyAlarm triggers alarm for that type of events only. The given type must exactly match the type in the notifications, and wildcards are not allowed.

Notes:

• When specifying a device or a group, you can select the item in the dropdown list or enter its ID manually in the field.
  
• When specifying a device, you can enter the ID of any managed object. This can be useful for measurements as these can be attached to child devices in Cumulocity IoT.

FAQs

Is it possible to subscribe to smart groups of devices?

No, only subscriptions to normal groups are supported.

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

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.

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

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

Actions

Application API

• Retrieve all applications: Retrieve all applications on your tenant.
  Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

• Create an application: Create an application on your tenant.
  Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

• Retrieve a specific application: Retrieve 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.

  Info: 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: Retrieve applications by name.
  Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

• Retrieve applications by tenant: Retrieve applications subscribed or associated with a particular tenant (by a given tenant ID).
  Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

• Retrieve applications by owner: Retrieve all applications associated with a particular tenant (by a given tenant ID).
  Required roles: ROLE_APPLICATION_MANAGEMENT_READ.

• Retrieve applications by user: Retrieve all 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 all application attachments: Retrieve all application attachments. This method is not supported by microservice applications.
  Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

• Upload an application attachment: Upload an application attachment (by a given application ID). For the applications of type microservice and web application to be available for Cumulocity IoT platform users, an attachment in the ZIP file format must be uploaded. For a microservice application, the ZIP file must consist of the following details:
  cumulocity.json - File describing the deployment.
  image.tar - Executable Docker image for a web application. The ZIP file must include an index.html file in the root directory.
  Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN AND tenant is the owner of the application.

• Retrieve a specific application attachment: Retrieve 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: Retrieve the bootstrap user for a specific application (by a given ID). This only works for microservice applications.
  Required roles: ROLE_APPLICATION_MANAGEMENT_ADMIN.

• Retrieve the current application: Retrieve the current application. This only works inside an application, for example, a microservice.
  Required roles Microservice bootstrap user required.

• Update the current application: Update the current application. This only works inside an application, for example, a microservice. This method is deprecated as it is only used by legacy microservices that are not running on Kubernetes.
  Required roles: Microservice bootstrap user required.

• Retrieve the current application settings: Retrieve the current application settings. This only works inside an application, for example, a microservice.
  Required roles: Microservice bootstrap user OR microservice service user required.

• Retrieve the subscribed users of the current application: Retrieve the subscribed users of the current application.
  Required roles: Microservice bootstrap user required.

Measurements API

• Retrieve all measurements: Retrieve all 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. For more information about data streaming and response formats, see Measurements Specifics.
  
  Required roles: ROLE_MEASUREMENT_READ.

• Create a 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 multiple measurements - 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 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: Retrieves a specific measurement by a given ID.
  Required roles: ROLE_MEASUREMENT_READ OR owner of the source or MEASUREMENT_READ permission on the source.

• Remove a specific measurement: Removes a specific measurement by a given ID.
  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: Retrieves 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: Retrieve all alarms on your tenant, or a specific subset based on queries.

  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 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 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: Retrieve 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.

  Info: 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: Retrieve 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: Retrieve all subtenants of the current tenant.
  Required roles: ROLE_TENANT_MANAGEMENT_READ.

• Create a tenant: Create a subtenant for the current tenant.
  Required roles: (ROLE_TENANT_MANAGEMENT_ADMIN or ROLE_TENANT_MANAGEMENT_CREATE) and the current tenant is allowed to create subtenants.

• Retrieve the current tenant: Retrieve information about the current tenant.
  Required roles: ROLE_USER_MANAGEMENT_OWN_READ or ROLE_SYSTEM.

• Retrieve a specific tenant: Retrieve 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 subscribed applications: Retrieve 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 monthly device statistics: Retrieve monthly device statistics from a specific tenant (by a given ID).
  Required roles: ROLE_TENANT_STATISTICS_READ.

• Retrieve daily device statistics: Retrieve daily device statistics from a specific tenant (by a given ID).
  Required roles: ROLE_TENANT_STATISTICS_READ.

• Retrieve statistics of the current tenant: Retrieve usage statistics of the current tenant.
  Required roles: ROLE_TENANT_STATISTICS_READ.

• Retrieve a usage statistics summary: Retrieve usage statistics summary of a tenant.

• Retrieve a summary of all usage statistics: Retrieve a summary of all tenant usage statistics.
  Required roles: ROLE_TENANT_MANAGEMENT_READ.

• Retrieve usage statistics files metadata: Retrieve 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: Retrieve specific usage statistics file (by a given ID).
  Required roles: ROLE_TENANT_MANAGEMENT_ADMIN.

• Retrieve the latest usage statistics file: Retrieve 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: Retrieve all 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: Retrieve all 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: Retrieve 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 the login options: Retrieve 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 all system options: Retrieve all system options available on the tenant.

• Retrieve a specific system option: Retrieve a specific system option (by a given category and key) on your tenant.

Users API

• Retrieve the current user: Retrieve 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.

• Retrieve all users for a specific tenant: Retrieve all 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: Retrieve 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.

• Retrieve a user by username in a specific tenant: Retrieve 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: Retrieve 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: End 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: Retrieve all 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: Retrieve 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: Retrieve 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 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: Retrieve all 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: Retrieve 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: Retrieve all 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: Retrieve all 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: Retrieve 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: Retrieve all 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: Retrieve 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.

Audits API

• Retrieve all audit records: Retrieve all 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: Retrieve 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: Retrieve all 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. An event must be 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 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: Retrieve 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: Removes 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: Retrieve the attached file (binary) of a specific event by a given ID.
  Required roles: ROLE_EVENT_READ OR EVENT_READ permission on the source.

• Replace the attached file of a specific event: Upload and replaces the attached file (binary) of a specific event (by a given ID). The size of the attachment is configurable, and the default size is 50 MiB. The default chunk size is 5 MiB.
  Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN permission on the source.

• Attach a file to a specific event: Upload a file (binary) as an attachment of a specific event by a given ID. The size of the attachment is configurable, and the default size is 50 MiB. The default chunk size is 5 MiB. After the file has been uploaded, the corresponding event contains the fragment c8y_IsBinary similar to:

      "c8y_IsBinary":{ 
      "name": "hello.txt", 
      "length": 365, 
      "typ\": "text/plain" 
      }

  When using multipart/form-data, each value is sent as a block of data (body part), with a user agent-defined delimiter (boundary) separating each part. The keys are given in the Content-Disposition header of each part.

      POST /event/events/{id}/binaries 
      Host: https://<TENANAT_DOMAIN>
      Authorization: <Authorization>
      Accept: application/json 
      Content-Type: multipart/form-data;boundary="boundary" \
  
      --boundary
      Content-Disposition: form-data; name="object" 
  
      { "name":"hello.txt", "type": "text/plain" } 
      --boundary
      Content-Disposition: form-data; name="file"; filename="hello.txt"
      Content-Type: text/plain 
  
      <FILE_CONTENT>
      --boundary-- 

Required roles: ROLE_EVENT_ADMIN OR owner of the source OR EVENT_ADMIN 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: Retrieve all 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: Retrieve 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.

Retentions API

• Retrieve all retention rules: Retrieve all 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: Retrieve 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: Removes 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: Retrieve 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: Retrieve all 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: Retrieve 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: Retrieve a list of operations.

  Notes:

  • 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: Retrieve 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: Retrieve 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: Retrieve 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.

• Create device credentials: Create device credentials.
  Required roles: ROLE_DEVICE_BOOTSTRAP.

• Create a bulk device credentials request: Create a bulk device credentials request. Device credentials and basic device representation can be provided within a CSV file which must be UTF-8 or ANSI encoded. The CSV file must have two sections. The first section is the first line of the CSV file. This line contains column names (headers):

  Name	Mandatory	Description
  ID	Yes	The external ID of a device.
  CREDENTIALS	Yes	Password for the device’s user.
  AUTH_TYPE	No	Required authentication type for the device’s user. If the device uses credentials, this can be skipped or filled with BASIC. Devices that use certificates must set CERTIFICATES.
  TENANT	No	The ID of the tenant for which the registration is executed (only allowed for the management tenant).
  TYPE	No	The type of the device representation.
  NAME	No	The name of the device representation.
  ICCID	No	The ICCID of the device (SIM card number). If the ICCID appears in file, the import adds a fragment c8y_Mobile.iccid. The ICCID value is not mandatory for each row.
  IDTYPE	No	The type of the external ID. If IDTYPE does not appear in the file, the default value is used. The default value is c8y_Serial. The IDTYPE value is not mandatory for each row.
  PATH	No	The path in the groups hierarchy where the device is added. PATH contains the name of each group separated by \, that is: main_group/sub_group/…/last_sub_group. If a group does not exist, the import creates the group.
  SHELL	No	If this column contains a value of 1, the import adds the SHELL feature to the device (specifically the c8y_SupportedOperations fragment). The SHELL value is not mandatory for each row.

  Section two is the rest of the CSV file. Section two contains the device information. The order and quantity of the values must be the same as of the headers.

  A separator is automatically obtained from the CSV file. Valid separator values are: tabulation mark (\t), semicolon (;) and comma (,).

  Note: A bulk registration creates an elementary representation of the device. Then the device needs to update it to a full representation with its own status. The device is ready to use only after it is updated to the full representation. See Credentials Upload and Device Integration.

  A CSV file can appear in many forms (with regard to the optional tenant column and the occurrence of device information):

  • If a user is logged in as the management tenant, then the columns ID, CREDENTIALS, and TENANT are mandatory, and the device credentials will be created for the tenant mentioned in the TENANT column.

  • If a user is logged in as a different tenant, for example, as sample_tenant, then the columns ID and CREDENTIALS are mandatory (if the file contains the TENANT column, it is ignored and the device credentials will be created for the tenant that is logged in).

  • If a user wants to add information about the device, the columns TYPE and NAME must appear in the CSV file.

  • If a user wants to add information about a SIM card number, the columns TYPE, NAME, and ICCID must appear in the CSV file.

  • If a user wants to change the type of external ID, the columns TYPE, NAME, and IDTYPE must appear in the CSV file.

  • If a user wants to add a device to a group, the columns TYPE, NAME, and PATH must appear in the CSV file.

  • If a user wants to add the SHELL feature, the columns TYPE, NAME, and SHELL must appear in the CSV file and the column SHELL must contain a value of 1.

  It is possible to define a custom external ID mapping and some custom device properties which are added to newly created devices during registration:

  • To add a custom external ID mapping, enter the external ID type as the header of the last column with the prefix external, for example, to add an external ID mapping of type c8y_Imei, enter external-c8y_Imei in the last column header. The value of this external ID type should be set in the corresponding column of the data rows.

  • To add a custom property to a registered device, enter the custom property name as a header, for example, myCustomProperty, and the value would be in the rows below.

  The custom device properties mapping has the following limitations:

  • Braces {} used in data rows will be interpreted as strings of “{}”. The system will interpret the value as an object when some custom property is added, for example, put com_cumulocity_model_Agent.active into the headers row and true into the data row to create an object “com_cumulocity_model_Agent”: {“active”: “true”}”.

  • It is not possible to add array values through bulk registration.

  Example file:

      ID;CREDENTIALS;TYPE;NAME;ICCID;IDTYPE;PATH;SHELL
      id_101;abcd1234;type_of_device;Device 101;111111111;;csv device/subgroup0;1
      id_102;abcd1234;type_of_device;Device 102;222222222;;csv device/subgroup0;0
      id_111;abcd1234;type_of_device;Device 111;333333333;c8y_Imei;csv device1/subgroup1;0
      id_112;abcd1234;type_of_device;Device 112;444444444;;csv device1/subgroup1;1
      id_121;abcd1234;type_of_device;Device 121;555555555;;csv device1/subgroup2;1
      id_122;abcd1234;type_of_device;Device 122;;;csv device1/subgroup2;
      id_131;abcd1234;type_of_device;Device 131;;;csv device1/subgroup3;

  There is also a simple registration method that creates all registration requests at once; then each one needs to go through regular acceptance. This simple registration only makes use of the ID and PATH fields from the list mentioned.

  Required roles: ROLE_DEVICE_CONTROL_ADMIN.

• Retrieve a list of new device requests: Retrieve 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: Retrieve 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 URIs to collections of managed objects: Retrieve URIs and URI templates to collections of managed objects.
  Required roles: ROLE_INVENTORY_READ.

• Retrieve all managed objects: Retrieve all 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: Retrieve 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: Retrieve 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: Retrieve 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: Retrieve all 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: Retrieve all 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: Retrieve 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.

• Retrieve the stored files: Retrieve the stored files as collections of managed objects.

• Upload a file: Upload a file (binary) requires providing the following properties:

  • object: In JSON format, it contains information about the file.

  • file: Contains the file to be uploaded.

  After the file has been uploaded, the corresponding managed object contains the fragment c8y_IsBinary.

  Required roles: ROLE_INVENTORY_ADMIN OR ROLE_INVENTORY_CREATE.

• Retrieve a stored file: Retrieve 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.

• Replace a file: Upload and replace the attached file (binary) of a specific managed object by a given ID.
  Required roles: ROLE_INVENTORY_ADMIN OR owner of the resource OR MANAGE_OBJECT_ADMIN 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: Retrieve 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: Retrieve 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: Retrieve 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: Retrieve 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: Retrieve 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 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: Retrieve 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.

• 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.

Availability: Workflows and FlowServices

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows and FlowServices

Actions

• Search Places: Find any place or location

Initial State

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

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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.

Availability: Workflows only

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