Administration

The Administration application enables account administrators to manage their users, roles, tenants, applications and business rules and lets them configure a number of settings for their account.

Overview

The following sections will walk you through all functionalities of the Administration application in detail. For your convenience find an overview on the content of this document below.

SECTION CONTENT
Home Screen Providing information on your capacity usage and subscribed applications.
Managing Users How to create users, edit, disable or delete them.
Managing Permissions How to create and edit global roles and inventory roles, how to assign them to users, and how to grant application access.
Managing own applications How to manage and configure own applications in your Cumulocity account.
Applying business rules How to set up real-time event processing scripts and reprioritize alarms by alarm mappings.
Changing settings How to change account settings like application settings or password policy and TFA settings, how to manage the properties library and how to configure settings for the Enterprise Edition.
Managing data retention How to manage and configure retention rules for your data and how to manage stored files in the file repository.

Home screen

The Home screen of the Administration application provides

  • a welcome message,
  • quick links to the main parts of the Administration application,
  • your capacity usage for the current and for the last month,
  • the optional applications you are subscribed to.

Home screen

The capacity sections show:

  • API requests: The total number of API requests, counting whenever some function in Cumulocity is invoked, regardless of whether the function is invoked from a device (for example, sending a measurement) or from an application (for example, viewing the list of devices).
  • Device API requests: Counting only when the API is called from a device (for example, sending a measurement).
  • Storage: The total amount of data stored in your account. This amount can be changed by retention policies and by the amount and size of stored files.
  • Storage quota: If the storage limit per device is set, the user is restricted to a maximum data usage.
  • Root devices: The number of root devices connected to your account, excluding child devices.
  • Devices: The total number of devices connected to your account. This is the sum of the devices listed in the All devices page of the Device Management application and their direct and indirect child devices.
  • Users: The sum of all users configured in this account, active and inactive.

Managing users

The user management functionality allows you to manage the users within your tenant and provides the following options:

  • Creating users
  • Assigning user names and set passwords
  • Storing user details
  • Choosing basic login options
  • Enabling additional login security by using Two-Factor Authentication (TFA)

Info: The user needs to have a role with the user management permission ADMIN or CREATE to be able to do so.

Info: If your tenant is configured for using SSO (Single Sign-On) in SAG Cloud, new users should be created under My Cloud, accessible through the application switcher in the upper right corner, so that they are able to use the SSO feature. For users created in My Cloud, password reset in Cumulocity is disabled.

Viewing users

To view all users in your tenant, click Users in the Account menu in the navigator.

Expanded view

A user list will be displayed, providing the following information for each user:

  • The user name that is used to access the tenant.
  • The name and email of the user, if set.
  • The global roles assigned to the user.
  • The strength of the password set for the user.

To filter the list, you can use the search field at the left of the top menu bar. For details on the search functionality, refer to Searching in the Introduction.

Moreover you can filter by global roles. Select the desired roles from the dropdown list and click Apply to limit the users shown in the list to users with the selected roles.

Initially, the User page only shows the top-level users. To see all users in your account at once, click Expand all at the right of the top bar. This will expand all top-level users, showing their sub-users. Click Collapse all to just show the top-level users again. For details on user hierarchies, refer to Managing user hierarchies.

Creating users

To add a user to your tenant, click Add user at the right of the top menu bar.

Add new user

At the left of the New user window provide the following information to identify the user:

Field Description
Username Serves as a user ID to identify the user at the system. Note that the username cannot be changed once the user has been created. This field is mandatory.
Login alias In addition to the user name, an optional alias can be provided to be used to log on. Other then the username, this alias may be changed if required.
Active Enable/disable the user account here. If the user account is disabled the user cannot login.
E-mail A valid email address. This is required to enable the user to reset the password. This field is mandatory.
First name First name of the user. When the user is logged in, this name appears at the right of the top bar on the User button.
Last name Last name of the user.
Telephone A valid phone number. The phone number is required if the user is configured to use two-factor authentication.
Owner Another user that manages ("owns") the new user. Select a user from the dropdown list and click Done to confirm. Refer to Managing user hierarchies for details on user hierarchies.
Delegated by Can be activated to delegate user hierarchies and permissions to the user. Refer to Managing user hierarchies for details on delegation.

Select the login options for the user.

  • If you select User must reset the password on next login, you need to provide a password which the user needs to reset on the next login.
    Enter a password and confirm it. While entering the password, the strength of the password will be shown. See Logging into the Cumulocity platform for further information on password strength.
  • If you select Send password reset link as e-mail, the user will receive an email message with a link to set a password. The email will be sent to the email address configured above.

On the right of the page, select the global roles for the user. Details on global roles are described in Managing Permissions.

Click Save to create the user.

Info: By default, manually created users always have the "Own_User_Management" permissions set to active.

Modifying users

Click the menu icon at the right of a user entry to open a context menu which provides further functionalities.

Context menu

Info: You need a role with user management permission to perform these options.

Click Edit to edit an existing user. All fields except Username and Send password reset link as e-mail can be modified. For details an each field, refer to Creating users. Click Change password to change the password. After editing, click Save to apply your settings.

To copy roles, click Copy inventory roles from another user. In the upcoming window, select a user from the list and click Copy. At the top you can select if you want to merge the roles with the existing user roles (the default) or if you want to replace the existing user roles.

Click Delegate to delegate your user hierarchies and permissions to a user, or click Undelegate to remove a delegation. Refer to Managing User Hierarchies for details on delegation.

Click Disable to disable an active user, or click Enable to enable a user that has been disabled.

Click Delete to delete a user.

Managing permissions

Permissions define what a user is allowed to do in Cumulocity applications. To manage permissions more easily, they are grouped in so-called "roles". Every user can be associated with a number of roles, adding up permissions of the user.

The following types of roles can be associated with users:

  • Global roles: Contain permissions that apply to all data within a tenant.
  • Inventory roles: Contain permissions that apply to groups of devices.
  • Application access: Enables a user to use an application.

Viewing global roles

Click Roles in the Account menu to display a list of configured roles.

In the Global roles tab you can find the roles which grant permissions on a general level. There are several default global roles defined, but you can define your own according to your needs.

Context menu

The roles "admins" and "devices" have a special status:

Role Description
admin All permissions are enabled. The initial administrator, the first user created in a tenant, has this role.
devices Typical permission setup for devices. After registration, a device automatically has this role. Edit this role if your devices require less or more permissions, or assign other roles to your devices.

Furthermore, the following roles are configured as a starting point:

Role Description
CEP Manager Can access all smart rules and event processing rules.
Cockpit User Can access the Cockpit application. In addition, you should add a role providing access to devices.
Device management User Can access the Device Management application. The user will be able to use the simulator and to run bulk operations. In addition, you should add a role providing access to devices.
Global Manager Can read and write all devices.
Global Reader Can read all devices.
Global User Manager Can manage all users.
Shared User Manager Can manage sub-users. The subscription plan needs to include user hierarchies to be able to manage sub-users.
Tenant Manager Can manage tenant-wide settings, such as own applications, data brokerage, data retention, options and tenant statistics.

You may see the following legacy roles:

Role Description
business Can access all devices and their data but has no management permission in the tenant.
readers Can read all data (including users, in contrast to "Global Readers").

Creating and editing global roles

You can edit the existing global roles and you can create new global roles to meet your particular needs.

To edit a global role, simply click on its card. To create a new global role, click Add Role in the Global roles tab.

In the role page you will see a list of permission types on the left and a list of applications to be accessed on the right.

The following screenshot shows the settings for the "admins" role.

Admin example

Permission levels

For each type, you can select the following permission levels:

  • Read: Read the specified data.
  • Create: Create new data like users and inventory data and edit users within your hierarchy.
  • Update: Modify and delete the specified data (not including "Read").
  • Admin: Create, update or delete the specified data.

Info: "Create" permissions are related to the concept of ownership in Cumulocity. If you have created an object, you are the owner of it and can manage it without requiring any further permissions. For example, if you have "Create" permission for "Inventory", you can create devices and groups, and fully manage these devices and groups. You cannot manage any devices or groups that you did not create yourself, unless you also have the "Change" permission or an additional inventory role (see below). This concept helps to assign minimal permissions to devices. It also enables you to limit user management permissions to sub-users, if you subscribed to user hierarchies.

Select the checkbox at the top of a column to set the respective level to all permission types.

Permission categories

The following permission categories are available by default:

Category Description
Alarms View or edit alarms for devices.
Application management View or edit the applications available in this account.
Audits View or create audit logs for devices.
Bulk operations View or create bulk operations.
CEP management View or edit CEP rules.
Data broker Send data to other tenants or receive data from other tenants.
Device control View or edit commands for devices resp. send commands to devices. Also used for device registration.
Events View or create events for devices.
Identity View or edit identifiers for devices.
Inventory View or edit inventory data.
Measurements View or create measurements for devices.
Option management View or edit account options such as password policies.
Retention rules View or edit retention rules.
Simulator Configure simulated devices.
Tenant management View, create, edit or delete subtenants.
Tenant statistics View the usage data for this account, as shown on the Home screen of the Administration application.
User management View or edit users, user groups and permissions.
Own user management View or edit your own user.

There may be additional permissions visible depending on the features in your subscription plan. These are documented along with the respective feature.

Info: When new features with new permissions are added to Cumulocity, these are not automatically added to existing roles. If you notice that you cannot use a new feature that was recently announced, check your permissions.

Assigning global roles to users

You can assign global roles to users either directly in the user list, or by opening the page for a particular user and adding them there.

In the user list, click the Global roles column of a particular user to open a list of global roles. Select or clear the respective checkboxes and click Apply to save your settings.

Apply global role

Alternatively, click on a user in the list to open its details. Select or clear the checkboxes for the relevant global roles at the right and click Save at the bottom of the page to save your settings.

Attach global role

Viewing inventory roles

Inventory roles contain permissions that you can assign to groups of devices. For example, an inventory role can contain the permission to restart a device. You can assign this inventory role to a group of devices "Region North" and to a user "smith". The result is that the user "smith" can restart all devices that are in the group "Region North" or any of its subgroups.

To view the currently configured inventory roles, click Roles in the Account menu and switch to the Inventory roles tab.

Context menu

In the Inventory roles tab you can manage user permissions for particular groups and/or its children. There are several default inventory roles defined, but you can define your own according to your needs.

The following default inventory roles are available in new tenants as a starting point:

Role Description
Manager Can read all data of a group but cannot perform operations. In addition, can manage inventory data (including dashboards) and alarms.
Operations: All Can send operations to devices in a group (e.g. software updates, remote configurations).
Operations: Restart Device Can restart devices in a group.
Reader Can read all data of a group.

Creating and editing inventory roles

You can edit the existing inventory roles and you can create new inventory roles to meet your particular needs.

To edit an inventory role, simply click on its card. To create a new inventory role, click Add Role in the "Inventory roles" tab.

At the top of the page you can edit the name of the inventory role. Click on the name, edit it and click the green checkmark to save your edits.

Role details

Permissions are grouped into the following categories:

Category Description
Alarms Permissions related to working with alarms from devices.
Audits Permissions related to audit logs.
Events Permissions related to working with events from devices.
Inventory Permissions for viewing and editing devices.
Measurements Permissions related to measurements.
Device control Permissions to remote control devices.
Full access Complete access to the associated devices, mainly to simplify configuration.

Info: Service providers will see an additional permission "Support" in their "management" tenant. This permission lets users of the service provider give support to their customer's users. See Supporting users in other tenants below.

Add a permission to the role by clicking the plus icon next to the desired category.

In the Type field, specify a type to further restrict the type of data that this permission applies to.

For example, assume that your device sends measurements related to device management, such as "c8y_SignalStrength", and actual production measurements. You want a user to only see the device management measurements. In this case, enter "c8y_SignalStrength" as type.

By default, the Type field contains an asterisk "*" selecting all types.

Info: For further information on possible types, check your device documentation, the Cumulocity sensor library or the device management library. The type being used here is the so-called "fragment type", not the "type" property. You need to enter all fragment types send in a measurement to make the measurement visible; similar for other types of data.

In the Permission field, select a permission level from the dropdown list:

  • Read - to view objects
  • Change - to modify objects (does not include "read" permission)
  • All - to read AND modify objects

Role permissions

Important: When you add a permission, you may see a small exclamation mark. The exclamation mark indicates that the permission that you have just added is not effective, because another, "higher" permission set for the user already includes the respective permission. Check if you have set, for example, "Full access" or if there is another permission in the same section with "*" as type and "All" as permission.

warning message

As another example, assume that you are using tracking devices. You want to allow your user to see all devices, but not to change anything. In addition, the user should be able to follow tracks of devices on a map. Tracks are recorded using an event with fragment type "c8y_Position" (see Sensor library). To do so, assign read permission on inventory as well as on events with type "c8y_Position" as shown in the image below.

Permission example

Assigning inventory roles to users

Inventory roles are assigned to a user and a group of devices.

To assign inventory roles, click User in the Account menu, select a user in the user list and switch to its Inventory roles tab.

In the Inventory roles tab you will see a tree of device groups. To assign an inventory role, click on the arrow right from a device group. Select the relevant roles and click Apply. For details on the roles hover over the info icon next to it or refer to Viewing inventory roles.

Important: If a user already has a global role containing inventory permissions, the user will be able to see or change all devices regardless of what inventory roles you set here.

Inventory roles

Inventory roles are inherited from groups to all their direct and indirect subgroups, and to the devices in these groups. If you select, for example, a role with read permissions on alarms for a group of devices, the user will be able to see alarms of all devices in this group and all its subgroups.

If a user has inventory access to a group of devices, the user will also have that access to all dashboards for that group of devices in the Cockpit application.

You can also copy inventory roles from another user. To copy roles, click Copy inventory roles from another user. In the upcoming window, select a user from the list and click Copy. At the top you can select if you want to merge the roles with the existing user roles (the default) or if you want to replace the existing user roles. Copying roles makes it easier to manage the permissions of many users as you can create a reference user and then copy the permissions from there.

Copy roles

Granting application access

In the Application Access tab you assign applications to the user.

The Application Access tab shows a list of all available applications in your tenant in alphabetical order. Select the applications for the user and click Save. For more information on application management, see Administration > Managing applications.

Application access

Info: If a user has global permission to read all applications, an information box will be shown.

Troubleshooting permissions

If you try to perform actions without sufficient permissions, an error message will occur.

To help troubleshooting permissions, click the the User button at the right of the top bar. From the context menu, select Access denied requests. In the upcoming window details on the denied accesses are provided. An administrator user or the support can help in fixing the permissions.

The example shows a user, who tried to create a simulator without the necessary permissions, hence, a warning message is shown.

Access error message

Viewing audit logs

Audit logs show the operations that users have carried out.

To view the audit log list, click Audit logs in the Account menu. For each log entry, the following information is provided:

Column Description
Server time Server time when the operation was processed.
Change Type of operation, e.g. "Alarm created", Smart rule deleted". Below it, the user who processed it is displayed.
Description Provides further information depending on the operation, e.g. the device name, alarm text, operation status.
Device time Device time when the operation was processed. This can differ from the server time.

Only the last 100 logs are visible. Click Load more at the bottom of the list to view more log entries.

Audit logs

Info: The audit log list is not automatically refreshed after a realtime update for operations. Click Reload at the right of the top menu bar to update the list to the latest operations.

Filtering logs

In order to easily search through logs, you may filter logs for

  • the type, i.e. alarm, operation, Smart Rule,
  • a date range providing a "From" and/or a "To" date,
  • the user.

To apply filters, click the filter icon next to the filter fields. To discard filters, click the delete icon (only visible if filters are set).

Managing applications

In addition to the applications provided in your account (per default or as subscription), you can also manage own applications.

Own applications may be

  • duplicates of subscribed applications (in order to be able to customize them)
  • web-based UI applications, either deployed as standalone applications or as plugins deployed into a specific application (e.g. a widget to the Cockpit dashboard)
  • server-side business logic deployed through microservices

If you are subscribed to the required application ("apama-small"), you additionally can upload custom Apama CEP rules as application.

Your applications are available through the application switcher in the top bar which allows to easily switch between applications.

App switcher

You manage your applications under Own applications, accessible through the Applications menu.

In the Own applications page you will find a list of the applications available in your account.

Own applications

To display further information on the application, simply click its card. For details on the fields, refer to Application properties below.

To directly open an application from here, click Open on the respective application card.

Click Add application in the Own applications page, to add an application to your account, see Adding applications.

Click the menu icon at the top right of an application to open a context menu from where you can Edit or Remove an application.

Adding applications

To add an application, click Add application in the Own applications page. In the upcoming dialog choose one of the following methods:

If you are subscribed to the required application ("apama-small"), you will also see the option Upload custom Apama rule to upload own Apama CEP rules as application.

Add application methods

Uploading web applications

In order to upload a web application, follow these steps:

  1. Click Add application in the Own applications page.
  2. In the upcoming dialog, select Upload zip file.
  3. Simply drop a zip file or browse for it on your computer.

Uploading zip file

After successfully uploading the zip file to the platform the application is being created.

Uploading microservices

In order to upload a microservice, follow these steps:

  1. Click Add application in the Own applications page.
  2. In the upcoming dialog, select Upload zip file.
  3. Simply drop a zip file or browse for it on your computer.

Uploading zip file

After successfully uploading the zip file to the platform the application is being created.

Info: In case of microservices, the package must contain the manifest file and docker image of the microservice. Refer to Microservice package reference in the Reference guide in order to prepare and deploy the microservice package.

Linking to external applications

In order to add an application which links to an external application, follow these steps:

  1. Click Add application in the Own applications page.
  2. In the upcoming dialog, select External application.

    External application

  3. In the next window, enter the name of the application. The name will be shown as title of the application.
  4. Enter an application key, used to identify this application.
  5. Enter the external URL where the application can be reached.
  6. Finally, click Save to create the application.

For details on the fields, see also Application properties below.

Duplicating applications

Duplicating an application might be useful if you want to customize a subscribed application according to your needs.

Duplicating a subscribed application creates a copy of the application as an own application, with a link to the original application.

Info: If you want your "own application" to overrule a subscribed standard application, the path of the "own application" needs to be set to the path of the original subscribed application.

In order to duplicate an application, follow these steps:

  1. Click Add application in the Own applications page.
  2. In the upcoming dialog, select Duplicate existing application.
  3. Select the desired application from the dropdown list.

    Duplicate application

  4. In the next window, provide a name for the application. By default, the name of the original application is provided, extended by a number.
  5. Provide an application key, used to identify this application. By default, the key of the original application is provided, extended by a number.
  6. Provide the application path as part of the URL to invoke the application. By default, the path of the original application is provided, extended by a number. If you set it to the path of the original subscribed application, your own application will overrule the subscribed application.
  7. Finally, click Duplicate to create the application.

For details on the fields, see also Application properties below.

Uploading custom Apama rules

Info: To be able to upload custom Apama CEP rules as applications to Cumulocity you need to be subscribed to the application "apama-small".

In order to upload custom Apama CEP rules, follow these steps:

  1. Click Add application in the Own applications page.
  2. In the upcoming dialog, select Upload custom Apama rule.
    Upload CEP rules

  3. The file to be uploaded must be a single mon file, containing a set of event definitions and monitors. Drop the mon file or browse for it on your computer.

After successfully uploading the file to the platform an application of type "Apama CEP rule" is being created.

Uploading zip file

For details on the fields, see also Application properties below.

Info: You cannot add a plugin to an application of type "Apama CEP rule".

Application properties

Click on an application card to view the application properties.

Microservice application

Each application will show the following properties:

Field Description Hosted (Web app) Microservice External CEP rule
Name Application name. Will be shown as title of the application in the top bar and in the application switcher. Automatically created Automatically created, based on the zip file name Specified by the user Automatically created, based on the mon file name
ID Unique ID to identify the application Automatically provided Automatically provided Automatically provided Automatically provided
Application key Used to identify the application and to make the application available for subscription, see the Concepts Guide. Automatically created Automatically created based on the zip file name Specified by the user Automatically created based on the mon file name
Type Application type Hosted application Microservice External Apama CEP rule
Path Part of the URL invoking the application Automatically created Automatically created as .../service/<microservice name> Specified by the user. For example, if you use "hello" as application path, the URL of the application will be "/apps/hello". Not available

Info: ID, application key, type and path cannot be changed.

Editing and removing applications

Edit

To edit an application, simply click the application or click Edit in its context menu, accessible through the menu icon.

In the Properties tab, several fields can be modified, depending on the application type (see Application properties).

Important: Never change the system application names (e.g. "Device Management", "Cockpit"). Otherwise, tenant initialization will fail.

Remove

To remove an application, click the menu icon and from the context menu select Remove.

If you remove an application that overwrites a subscribed application, the currently subscribed application becomes available to all users. Additionally, the users will then also benefit from future upgrades of the subscribed application.

It is not possible to remove subscribed applications. This can only be done by the owner of the subscribed application.

Adding and removing plugins

Important: This plugin functionality is deprecated and only available in versions earlier then 9.16.

In order to configure and extend the functions provided with an application, you can add plugins to it.

Info: Because the application itself is modified when adding a plugin, plugins can only be added to own applications. When adding a plugin to a subscribed application, the application must be duplicated first into an own application. This process is supported by the Administration Application wizard.

To add additional plugins, click Add Plugin on the card of the desired application in the "Own applications" page.

The "Plugin" tab for the application will open up, showing all existing plugins and allowing to add plugins by simply dropping the respective ZIP file or browsing for it on your computer.

Plugins

To remove a plugin, hover over it and click Remove at the right.

The following tables list the navigator and menu items with their respective plugins.

Navigator Item Plugin
Welcome Welcome screen
Home Cockpit Home
Smart Rules Smart Rules UI
Groups Groups Hierarchy
Data Explorer Data Point Explorer UI
Data Point Library Data Point Explorer UI
Reporting Reporting
Reports Dashboard (Note: that there are two plugins with this name. Select the one with the description: "Reports are stand alone dashboards without a context".)
Alarms Alarm Management
Menu Item Plugin
Info Not possible to disable
Subassets Not possible to disable
Permissions Device Permission Management Plugin
Data Explorer Data Point Explorer UI

Be aware of the "UI" at the end of the plugin names.

Restoring to an older application version

Users can restore previous versions of an application from an archive:

  1. Open the application by clicking on it.
  2. Switch to the Archives tab.
  3. Open the context menu for the desired version by clicking the menu icon and select Set as active to make it the active version.
  4. Click Remove to remove the version from the archive.

Info: The Archive tab is not available for subscribed applications, as only the owner of the application can perform this action.

Uploading archives

Multiple archive file versions can be stored in Cumulocity when they were created by uploading either a zip file or a mon file. Each version is called an archive. You can upload different versions at the same time and switch between these versions.

To upload an archive, follow these steps:

  1. Open the application by clicking on it.
  2. Switch to the "Archives" tab.
  3. Click Upload archive and browse for the archive on your computer or simply drop the archive file.
  4. Click Upload to upload the archive to your Cumulocity account.

Upload archive

Once uploaded, the recently uploaded version is automatically the active version, i.e. the version of the application that is currently being served to the users of your account. This version cannot be deleted.

To change the active version, open the context menu in the version you want to activate and select Set as active.

Managing business rules

Event processing

Using event processing, you can specify realtime business logic that is automatically run by Cumulocity as soon as new data arrives or existing data is modified. The logic is deployed in so-called "modules" which consist of a set of CEP statements.

Info: A user-friendly way to specify realtime business logic is provided in the Cockpit application through the so-called "Smart Rules". Smart Rules are "under the hood" also implemented as CEP statements, and you can see them in the Event Processing page. However, you cannot edit Smart Rules from here.

Click Event processing in the Business rules menu to view the current modules or to create new ones.

Event processing

For each module in the list, the status (deployed = indicated by a green checkmark / not deployed = indicated by an exclamation mark), the name and the date when is was last updated is provided.

To edit a module, simply click the module or click Edit in the context menu, accessible through the menu icon.

To remove a module, click Remove in the context menu.

Instead of deleting the module you can also disable it temporarily by setting its status to "Not deployed".

Creating new modules

To create a new module, click New module in the top menu bar.

New module

  1. Enter a name for the module at the very top. You can only use alphanumeric characters without blanks.
  2. By default, the status is set to "Deployed" which means that the statements you enter will be run immediately. Set the slider to "Not deployed" if you want to avoid this.
  3. Enter your CEP statements into the Source code text box. For your convenience, we provide various examples. Click Examples and select an appropriate example from the dropdown list. Click Append example to paste the example into the Source code text box at the position of the cursor.
  4. Click Save to save your settings.

The example module creates an alarm if the temperature goes below 0 degree.

Example module

If the status of a module is set to "Deployed", this is indicated by a green checkmark in the module list. Whenever your statements produce some output you will see it below the checkmark icon. Clicking a line of output unfolds the detailed output of the statement. Clicking Clear all removes the output from the screen.

Alarm mapping

Alarm mapping enables you to change the severity and text of alarms to adapt them to your business priorities. For example, a loss of the connection to a device is by default a "MAJOR" alarm but may be critical to you. To change this, add an alarm mapping to change alarms related to connection losses to CRITICAL.

Click Alarm mapping in the Business Rules menu to see a list of all alarm mappings.

Alarm mapping

For each alarm mapping, the alarm severity and the name of the mapping is shown.

To edit an alarm mapping, simply click it.

To delete an alarm mapping, hover over it and click the Delete button.

Adding an alarm mapping

To add an alarm mapping, click Add alarm mapping in the top menu bar.

Add alarm mapping

  1. Enter the alarm type to be modified.
  2. Optionally, enter a new text for the alarm. If you do not enter any text, the original text in the alarm will be kept.
  3. Select the desired new severity, or select "Drop" to not show the alarm at all.
  4. Click Save to save your settings.

Managing data retention

Retention rules

Retention rules gives you control on how long data is stored in your account. You might for example want to store measurements for 90 days, but delete alarms already after 10 days. By default, all historical data is deleted after 60 days (configurable in the system settings).

Retention rules are usually run during the night. When you edit a retention rule, you will not see an immediate effect in the "Usage" section on the Home screen of the Administration application.

Click Retention rules in the Management menu to view a list of retention rules configured for your account.

Retention rules

For each rule, the rule name, details on the data to be deleted (fragment type, type and source, see below) and the maximum age in days is provided.

The asterisk ("*") indicates that data with any value will be cleaned up.

Creating retention rules

To add additional retention rules, click Add rule in the top menu bar.

Add retention rule

Info: Per default, an asterisk ("*") is set in all fields except the "Maximum age" field, to include all values.

  1. Select the type of data to be cleaned up (alarms, measurements, events, operations, audit logs or all).
  2. Enter a fragment type if you want to be more specific about the data to be cleaned up. To clean up all connection loss alarms with this rule, select "alarms" and enter "c8y_UnavailabilityAlarm" as property into the Type field.
  3. If you want to remove data only from a specific device, enter the device ID into the Source field.
  4. Enter the Maximum age in days (max. allowed value is 10 years in days).
  5. Click Save to create the rule.

Info: Alarms are only removed if they are in CLEARED state.

Delete retention rule

To delete a rule, hover over it and click the Delete button at the right.

Managing files in the file repository

The file repository provides an overview of the files stored in your account.

Click Files repository in the Management menu to see a list of files.

The files listed can come from various sources. They can be software images, configuration snapshots taken from devices, log files from devices or web applications uploaded from the Own applications page.

For each file, the name of the file, its owner, the file type (i.e. image/bmp, text/csv), its size and the date when it was last updated is provided.

Files Repository

To upload a file from your computer, click Upload file in the top menu bar.

To download a file from your account, click the menu icon and from the context menu select Download.

To delete a file from your account, click Delete in the context menu.

Info: If the file corresponds to an active application, it cannot be deleted. You first need to remove or upgrade the application to be able to delete it.

Using two-factor authentication

The Two-factor authentication(TFA) is an extra layer of security that requires not only a username and password, but SMS verification as well. TFA can only be set up by administrators. When TFA is enabled, it is impossible to configure it from the "User settings", it is configurable from the administration UI only.

Info: When adding a user and TFA is enabled, you need to provide a phone number for the user. When users without a phone number try to login using TFA, the users will be redirected to a window, to enter their mobile phone number. Without a phone number a login is impossible.

To see whether TFA is enabled for a certain user, go to the Users page and check the TFA status column right from the password strength column. A key icon indicates that TFA is enabled.

TFA status

To enable two-factor authentication for a user, follow these steps:

  • Click on the desired user in the Users page.
  • Select the checkbox next to Enable two-factor authentication.
  • Click Save.

Enable TFA

Changing settings

From the Settings menu, administrators can modify or manage various settings for the account as

Configuring single sign-on

Cumulocity provides single sign-on functionality, that allows a user to login with a single 3rd-party authorization server using the OAuth2 protocol, for example Azure Active Directory. Currently authorization code grant is supported only with access tokens in form of JWT.

Info: This feature is built on top of cookies technology. To be able to use it, you must have cookies enabled in the settings of your browser.

This feature is enabled since Cumulocity version 9.12. For correct behavior any microservice needs to use the microservice SDK with version 9.12 or later.

Configuration settings

To enable the feature, the administrator has to configure a connection with the authorization server. This is done in the Administration application.

Click Single sign-on in the Settings menu in the navigator.

Request configuration

As the OAuth protocol is based on the execution of HTTP requests and redirects, a generic request configuration is provided.

The first part of the Single sign-on page consists of the request configuration. Here you can configure the HTTP request address, request parameters, headers and body in case of token and refresh requests. The authorize method is executed as a GET, and others as POST requests.

The Configuration section of the Single sign-on page consists of the following configuration settings:

OAuth configuration

Field Description
Group The initial group assigned to the user on first login
Applications The initial applications assigned to the user on first login
Audience Expected aud parameter of JWT
Button name Name displayed on the button on the Login page
Client ID OAuth connection client ID. Can be used in request definitions as a ${clientId} place holder
Redirect to platform Redirect parameter. Can be used in request definitions as a ${clientId} place holder
Issuer OAuth token issuer
Provider name Name of the provider
Visible on login page Indicates whether the login option is enabled or not.

When a user logs in with an access token, the username can be derived from a JWT claim. The claim name can be configured in the User ID configuration window.

OAuth configuration

Each access token is signed by a signing certificate. Currently there are two options to configure the signing certificates.

  1. By specifying the Azure AD certificate discovery address.

    OAuth configuration

  2. By providing the public key of a certificate manually to Cumulocity. A certificate definition requires an algorithm information, public key value and validity period.

    OAuth configuration

Access

When a user logs into Cumulocity for the first time, a user instance is created with default access, i.e. groups and applications specified in the Configuration section. The administrator can further assign specific access to a user manually.

Integration with Azure AD

Azure AD configuration

The integration was successfully verified against Azure AD. The configuration steps are available in https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code.

While configuring your Azure AD, redirect_uri is your full domain address. For the purpose of this document we assume that it is http://aad.cumulocity.com. There are no additional steps on Azure AD required.

Cumulocity configuration

In the Single sign-on page, the Authorization request section should look similar to:

Azure AD authorize request

The URL parameter consists of:

There is no need for headers, and there should be two request parameters:

  • redirect_uri = ${redirectUri} -replaced in runtime by REDIRECT TO PLATFORM
  • client_id = ${clientId} replaced in runtime by CLIENT ID

The Token request section should look similar to:

Azure AD token request

The URL parameter consists of:

the body parameter can be taken from the Azure AD OAuth specification, an example is:

 "grant_type=authorization_code&client_id=${clientId}&code=${code}&redirect_uri=${redirectUri}&client_secret=SECRET=&resource=${clientId}"

and consists of:

  • grant_type=authorization_code
  • client_id=${clientId} - replaced in runtime by CLIENT ID
  • code=${code} - parameter automatically read after successful redirect to the platform
  • redirect_uri=${redirectUri} - replaced in runtime by REDIRECT TO PLATFORM
  • client_secret=SECRET - a password specified in Azure AD -> App registration -> application -> Settings -> Keys -> Passwords
  • resource=${clientId} - replaced in runtime by CLIENT ID

There is no need to set headers or request parameters.

The Refresh token request section should look similar to:

Azure AD refresh request

The URL parameter consists of:

The body parameter can be taken from the Azure AD OAuth specification, an example is:

 "grant_type=refresh_token&refresh_token=${refreshToken}&client_id=${clientId}&resource=${clientId}&client_secret=SECRET"

and consists of:

  • grant_type=refresh_token
  • refresh_token=${refreshToken} - replaced in runtime by known refresh token
  • client_id=${clientId} - replaced in runtime by CLIENT ID
  • client_secret=SECRET - a password specified in Azure AD -> App registration -> Application -> Settings -> Keys -> Passwords
  • resource=${clientId} - replaced in runtime by CLIENT ID

There is no need to set headers or request parameters.

The Configuration section should look similar to:

Azure AD configuration

  • Groups and Applications - should be specified according to the tenant's requirements, but group "business" and Cockpit application are advised as a good start
  • Audience - this is the application ID parameter from Azure AD, it can be found in Azure AD -> App registration -> Application
  • Button name - is the name of the button on the Login page
  • Client ID - For Azure AD is equal to audience, it can be found in Azure AD -> App registration -> Application
  • Redirect to platform - Cumulocity address, in our example http://aad.cumulocity.com,
  • Issuer - the token issuer, value taken from Azure AD -> App registration -> endpoints -> MICROSOFT AZURE AD GRAPH API ENDPOINT
  • Provider name - Azure AD
  • Visible on login page - enabled

User ID Configuration:

Azure AD user id

  • Use constant value - clear this field
  • JWT - upn - which is the user principle name

Signature verification:

Azure AD signature verification

For Azure AD, Cumulocity provides support for automatic certificate rollover.

In the Certificate Type section, choose Azure AD, and set the public key discovery URL to a value consisting of:

Changing application settings

Click Application in the Settings menu to change applications settings.

Under Default application, you can select a default application from the list which will apply to all users within the tenant.

Info: All users must have access to this application.

Under Access control, administrators can enable cross-origin resource sharing or "CORS" on the Cumulocity API.

The Allowed Domain setting will enable your JavaScript web applications to directly communicate with REST APIs.

For further information, see http://enable-cors.org.

Changing the password policy and TFA settings

To change password settings, click Password in the Settings menu.

Under Password expiration, you can limit the validity of user passwords by specifying the number of days after which users have to change their passwords. If you do not want to force your users to change passwords, use "0" for unlimited validity of passwords (default value).

By default, users can use any password with eight characters or more. If you select Enforce that all password are "strong" (green), your users must provide strong passwords as described in Logging into the Cumulocity platform.

Info: The password validity limit and the enforcing of strong passwords may not be editable, if configured by the platform administrator.

Strong (green) passwords must have "M" characters. By default, the system restricts the use of passwords already used in the past. The last "N" passwords provided by a user are remembered by the system and the system does not allow to use them. The default value for "N" is 10.

Info: "M" and "N" can be configured by the platform administrator.

Click Save to apply your password settings.

Password settings

Under TFA settings, you can change the following TFA settings:

  • Limit token validity - here you can set the lifetime of each session in minutes. When the session expires, the user has to enter a new verification code.
  • Limit PIN validity - Here you can set the lifetime of each verification code sent via SMS. When the verification code expires, in order to login the user has to request a new verification code.

To allow two-factor authentication, select the checkbox Allow two-factor authentication".

Click Save TFA settings to apply your changes.

Managing the properties library

In the Properties library, accessible from the Settings menu, custom properties can be added to inventory objects, alarms, events and tenants.

Properties library

With custom properties, you can extend the data model of Cumulocity built-in objects. You may create the following custom values:

  • Custom inventory properties are used to extend the inventory data model. They can be used in the “Asset table” and “Asset properties” widgets.
  • Custom tenant properties are available during tenant creation. The custom properties can be edited under Subtenants in the Custom properties tab of each tenant. Additionally, these properties can be viewed and exported in the Usage statistics.
  • Custom alarm and event properties can be used as custom fields which can be added to your reports and will be available in the Export page in the Cockpit application.

Info: Custom properties are visible to all authenticated users of the tenant, regardless of their inventory role permission.

Adding properties to the properties library

To add a custom property, select the tab for the desired property and click Add property.

Add new property

In the upcoming form, provide a unique name as identifier and a label for the property and select its data type from the drop down list. Additionally, select validation rules for the new property:

Check box Description
Required If selected, the property needs to be provided, i.e. during alarm creation. Not available if the property type is "Boolean".
Default Value Provide a default value to be automatically filled in the custom property field. Only available for properties with type "String".
Minimum Enter a minimum integer value.
Maximum Enter a maximum integer value.
Minimum length Enter the minimum length required for the string.
Maximum length Enter the maximum length required for the string.
Regular expression Add a regular expression which will be required in order to fill the custom property field.

Click Save to create the new property.

Click on the name of a property in the list to open it. To edit the property, enter the desired changes and click Save to save the settings. Click Remove to delete the property.

Entering OpenIT credentials

By providing OPenIT credentials you enable the platform to utilize SMS services provided by Openit.

SMS are used throughout the application for various features like two-factors authentication and user notifications, i.e. on alarms.

Configuration settings

Under Configuration in the Settings menu, you can configure system-wide properties in Cumulocity. The following options can be modified in the Configuration settings.

In the Two-factor authentication field you can change the SMS template which is sent to the users.

In the Support link field you can enter a URL to be used to link to a Support page. If you do not provide a link here, the default link to the Cumulocity Support will be used.

Enter "false" to hide the link.

In the Password reset section you can change all settings related to password reset e-mail templates.

Configuration menu1

At the top you can select if you want to allow sending e-mails to unknown email addresses.

In the Password reset e-mail template fields, provide an e-mail template to be used when the address is known and one to be used when the address is unknown. The link to reset the password might for example be: {host}/apps/devicemanagement/index.html?token={token}.

In the E-mail subject field, provide a subject for all password reset related e-mails.

In the following two fields provide an e-mail template to be used on password change confirmation and a template for the invitation e-mail.

Info: Placeholders to be used are: {host}, {tenant-domain}, {token}.

In the E-mail server section you can provide the protocol, host, port, username, password and sender address for the e-mail server.

Configure e-mail server

In the Data export section you can set the e-mail subject and e-mail template for data export and specify the “User unauthorized error message”.

Configuration menu1

In the Storage limit section you can specify the e-mail subject and e-mail template for emails being send before data is removed on exceeding the storage limit and after data removal is performed.

In the Suspending tenants section you can provide settings for emails being send on tenant suspension.

Suspended tenants

At the top you can select if you want to send the e-mail to the suspended tenant's administrator and specify an additional e-mail receiver. Below you set the subject and template for the tenant suspended e-mail.

Click Save configuration to save your settings.

Info: Additional features are available for "Management" tenants.