Administration

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.

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.

The capacity sections show:

• API requests: The total number of API requests, counting whenever some function in Cumulocity IoT 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 feature allows you to manage the users within your tenant. With this functionality you may:

• Create users.
• Assign user names and set passwords.
• Store user details.
• Choose basic login options.
• Enable 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.

If your tenant is configured for using single sign-on (SSO) 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 single sign-on feature.

For users created via an external authorization server, updating the following settings in Cumulocity IoT will have no effect (will be reset on the next user re-login):

• user info (login alias, email, first name, last name, telephone)
• global roles → configurable via SSO access mapping
• application access → configurable via SSO access mapping

Moreover, password reset in Cumulocity IoT is disabled for users created through an external authentication server.

Info: Users which are using single sign-on cannot change the password of users which are managed by the platform.

Viewing users

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

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.

To add a user

1. Click Add user at the right of the top menu bar.

   Info: If single sign-on is enabled for your tenant, a message will show up which reminds you that you are about to create a local user which will not be able to login via single sign-on. Create new users in My Cloud instead, accessible through the application switcher in the upper right corner, to enable them using the single sign-on feature.

2. 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. In contrast to username, this alias may be changed if required. User alias is not supported for devices.
   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.

3. Select the login options for the user.

   • Two-factor authentication (SMS): If selected, the user will receive a verification code via SMS which is required to complete the authentication. The SMS will be sent to the phone number configured above. For details refer to Two-factor authentication.
   • User must reset password on next login: If selected, you need to provide a password which the user must reset on the next login. Enter a password and confirm it. While entering the password, the strength of the password will be checked. See To log into the Cumulocity IoT platform for further information on password strength.
   • Send password reset link as email: If selected, 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.

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

5. Click Save to save your settings.

The new user will be added to the user list.

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

To edit a user

1. Click the menu icon at the right of the respective row and then click Edit. All fields except Username and Send password reset link as email can be changed. For details on the fields, see To add a user.
2. Click Change password to change the password.
3. Click Save to apply your settings.

Info: You need a role with user management permission to perform this option.

To copy inventory roles

1. Click the menu icon at the right of the respective row and then click Copy inventory roles from another user.
2. In the resulting dialog box, select if you want to merge the roles to be copied with the existing user roles (the default) or if you want to replace the existing user roles.
3. Select the user from which you want to copy roles from the dropdown list.
4. Click Copy.

The inventory roles will be copied from the selected user.

Info: You need a role with user management permission to perform this option.

To delegate/undelegate user hierarchies

Click the menu icon at the right of the respective row and then click Delegate to delegate your user hierarchies and permissions to a user.

Click Undelegate to remove a delegation.

Refer to Managing User Hierarchies for details on delegation.

Info: You need a role with user management permission to perform this option.

To disable/enable a user

Click the menu icon at the right of the respective row and then click Disable to disable an active user, or click Enable to enable a user that has been disabled.

Info: You need a role with user management permission to perform this option.

To delete a user

Click the menu icon at the right of the respective row and then click Delete.

Info: You need a role with user management permission to perform this option.

Managing permissions

Permissions define what a user is allowed to do in Cumulocity IoT applications. To manage permissions more easily, they are grouped into 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.

Moreover, application access can be granted to enable a user to use an application.

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 global roles pre-defined, but you can define your own according to your needs.

Info: The pre-defined roles are not fully configured. They can be seen as samples which are pre-configured for a particular purpose. You may use them as a starting point and further adapt them to your individual needs.

On creating a new user, make sure that the global roles you assign to the user cover all permissions relevant for this particular user. If, for example, a user only has the role “Cockpit User” (see below), the user will only be able to access the Cockpit application and nothing more.

The roles “admins” and “devices” have a special status:

Furthermore, the following pre-configured roles are initially provided.

You may also see the following legacy roles:

To add a global role

Click Add Role in the Global roles tab.

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

The following screenshot shows the settings for the “admins” role.

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: Change 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 IoT. 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 UPDATE 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:

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

Important: When new features with new permissions are added to Cumulocity IoT, 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

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.

To assign global roles from the user list

1. Click the Global roles column of a particular user to open a list of global roles.
2. Select or clear the respective checkboxes.
3. Click Apply to save your settings.

To assign global roles from the user page

Click on the row of the respective user in the user list. In the user page, select or clear the checkboxes for the relevant global roles at the right. Click Save to save your settings.

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.

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 initially available in new tenants:

To add an 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.

Permissions are grouped into the following categories:

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.

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. Access will be only granted to objects that contain the specified Type.

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. This will allow the user to only see measurements that contain the type “c8y_SignalStrength”. Note that the user will be able to see the entire measurement object including other types that may be part of the same measurement object.

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

Info: For further information on possible types, check your device documentation, the Cumulocity IoT 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

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.

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.

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

Troubleshooting permissions

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

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

Granting application access

The Application Access tab shows a list of all available applications in your tenant in alphabetical order.

To assign applications to the user, simply select the respective applications and click Save.

For more information on application management, see Administration > Managing applications.

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

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:

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

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 the Cumulocity IoT platform we distinguish between two kinds of applications:

• Subscribed applications - all applications subscribed to the tenant (either provided by the platform or a service provider) but not owned. May not be added, modified or removed by the user.
• Own applications - all applications owned by the tenant. Users can add custom applications in various ways as own applications.

Click Own applications or Subscribed applications in the Applications menu in the navigator to display a list of all respective applications in your account.

Application properties

Click on an application card to view the application properties.

Each application will show the following properties, depending on the application type:

In case of applications of the type “microservice”, you will additionally find information on its version, as well as on its isolation level and billing mode, see Enterprise Tenant > Managing tenants > Microservice usage for details on these parameters.

Subscribed applications

Cumulocity IoT provides a variety of applications for different purposes.

Depending on your installation and/or optional services your tenant will show a selection of the potentially available applications listed below.

The columns show the following information:

• Application: Application name as visible in the Administration application.
• Functionality: Brief description.
• Name: Identification of the application in the API. In case you want to subscribe a tenant to the application using an API, use this string in the argument (as name).
• Type: Technical type of the application. “Feature” refers to built-in applications subscriptions, i.e. these applications are not represented by an explicit artefact (microservice or web application).

Standard Tenant default applications

In the Standard Tenant you will find the following default applications:

Enterprise Tenant applications

Optional applications

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

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

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.

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

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

To add an own application

Click Add application in the Own applications page.

In the resulting dialog box, choose one of the following methods:

• Upload web application - by dropping a ZIP file or browsing for it on your computer.
• Upload microservice - by dropping a ZIP file or browsing for it on your computer
• External application - by linking to an application running elsewhere
• Duplicate existing application - by creating a copy of an existing application

To upload a web application

1. Click Add application in the Own applications page.
2. Select Upload web application.
3. In the resulting dialog box, drop a ZIP file or browse for it on your computer.

The application is created once the ZIP file has been successfully uploaded.

Important: The ZIP file must contain the index.html and cumulocity.json in its root directory, otherwise the application will not work.

To upload a microservice

1. Click Add application in the Own applications page.
2. Select Upload microservice.
3. In the resulting dialog box, drop a ZIP file or browse for it in your file system. Note that the size limit of the file to be uploaded is 500 MB.

The microservice application is created once the ZIP file has been successfully uploaded.

Important: The ZIP file must contain the application manifest and the Docker image of the microservice. Refer to Packing in the Microservice SDK guide under General aspects in order to prepare and deploy the microservice package.

To link to an external application

1. Click Add application in the Own applications page.
2. Select External application.
   
   
   
   
3. In the resulting dialog box, 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. Click Save to create the application.

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

To duplicate an application

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.

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

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.

To edit an own application

Simply click the application or click the menu icon at the right of an entry and then click Edit.

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.

To remove an own application

Click the menu icon at the right of an entry and then click 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.

Uploading archives

Multiple archive file versions can be stored in Cumulocity IoT 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

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 IoT account.

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.

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

To restore 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.

To reactivate a single application

If a hosted application is not deployed correctly, users may reactivate it.

1. Open the application by clicking on it.
2. Switch to the Archives tab.
3. Click Reactivate at the top right corner of the Archives tab.

The selected application will be reactivated by removing the respective files from the application directory and unpacking the host application package again.

Monitoring microservices

You can monitor microservices hosted by Cumulocity IoT in two ways.

Status information

The status of the microservice can be checked on the Status tab of the respective application.

The following information is provided on the Status tab:

• Instances: Number of active, unhealthy and desired microservice instances for the current tenant
• Subscribed tenants: Number of active, unhealthy and desired microservice instances for all subtenants subscribed to the microservice
• Alarms: Alarms for given application, provided in realtime
• Events: Events for given application, provided in realtime

The status information is available for subscribed applications as well as for own applications. Information on subscribed subtenants is only visible for the application owner.

To view the status you need the following permissions: ROLE_APPLICATION_MANAGEMENT_READ and ROLE_INVENTORY_READ

Alarms and events

Most of the alarms and events visible in the Status tab are strictly technical descriptions of what’s going on with the microservice.

There are two user-friendly alarm types:

• c8y_Application_Down - critical alarm which is created when no microservice instance is available
• c8y_Application_Unhealthy - minor alarm which is created when there is at least one microservice instance working properly, but not all of them are fully operating

User-friendly alarms are created for the microservice owner tenant only. They are also automatically cleared when the situation gets back to normal, i.e. all the microservice instances are working properly.

User-friendly alarms can be used to create smart rules. For details on creating smart rules of various types, see Smart rules.

For example, to send an email, if a microservice is down, create an “On alarm send email” Smart Rule.

In the On alarm matching section, use c8y_Application_Down as an alarm type. As a target asset select the microservice which you would like to monitor, for example “echo-agent-server”.

Log files

Cumulocity IoT offers viewing logs which provide more details on the status of microservices.

To view logs, open the Logs tab of the respective microservice.

At the top of the page, you can select the instance of the microservice, for which you want to view the logs.

Info: If your microservice was re-scaled into two instances you should be able to switch between them, but it is not possible to see the logs from both instances at once.

Next to the instance dropdown you can select the time range for the log entries to be shown by selecting a date from the calendar and entering a time.

Info: The time entered here may differ from the server time due to different time zones.

At the top right, additional functionality is provided:

• Download - To download the log data for a specified time range.
• Dark theme - To turn dark theme on or off.
• Auto refresh - To activate the auto refresh functionality. If activated, the displayed log data will automatically be refreshed every 10 seconds.
• Unsubscribe - To unsubscribe the microservice.
• Delete - To delete the microservice.

Initially, the Logs tab shows the latest logs of the microservice instance.

At the bottom right you find navigation buttons:

• First - directly navigates to the oldest available log entries for the microservice after its restart (maximum capacity 350MB of logs).
• Previous - increases the time range in 10 minutes steps.
• Next - reduces the time range in 10 minutes steps.
• Last - directly navigates to the latest available log entries.

If no logs are available in the selected time range, a message is shown accordingly:

Info: There is no possibility to see the logs from the previously running instances. However, inside the instance there is a Docker container running, and if only this one was restarted (not the whole instance) you should see the logs from the currently running and also lately terminated Docker container.

Logs are always loaded from the Docker container using both stdout and stderr sources, and there is no possibility to distinguish/filter by the source.

Default applications

To define default applications for subtenants, a tenant policy with the following options can be created and used when creating new tenants:

• category: configuration
• key: default.tenant.applications
• value: comma-separated list of applications names, e.g. administration,devicemanagement,cockpit,feature-microservice-hosting,feature-cep-custom-rules

Managing business rules

Event processing

Info: A user-friendly way to specify real-time 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 all rules.

For each rule 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.

If the status of a rule is set to Deployed, you will see the output produced by the statement 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.

To add a rule

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

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

To edit a rule

Simply click the row of the rule you want to edit or click the menu icon at the right of the respective row and then click Edit.

For details on the fields, see To add a rule.

To delete a rule

Click the menu icon at the right of the respective row and then click Delete.

Instead of deleting the rule you can also disable it temporarily by setting its status to “Not deployed”.

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.

For each alarm mapping, the alarm severity, the alarm type and a description (optional) are shown.

To add alarm mapping

1. Click Add alarm mapping in the top menu bar.
2. Enter the alarm type to be modified.
3. In the New description field, optionally enter a new description for the alarm. If you leave this field empty, the original text from the alarm will be kept.
4. Select the desired new severity, or select “Drop” to not show the alarm at all.
5. Click Save to save your settings.

Info: The alarm type set in an alarm mapping is interpreted as "<type>*". If you create for example an alarm mapping to address alarms of type "crit-alarm", the mapping is effective for any type of alarm that starts with this value e.g. "crit-alarm-1", "crit-alarm-2", or "crit-alarm-xyz".

To edit an alarm mapping

Expand an alarm mapping to edit it. You may modify the description and the alarm severity. The alarm type is not editable.

To delete an alarm mapping

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

Managing data

Retention rules

Retention rules gives you control on how long data is stored in your account. By default, all historical data is deleted after 60 days (configurable in the system settings).

You might however want to store measurements for 90 days for example, but delete alarms already after 10 days.

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.

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.

To add a retention rule

1. Click Add rule in the top menu bar.
2. In the resulting dialog box, select the type of data to be cleaned up (alarms, measurements, events, operations, audit logs or all).
3. 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.
4. If you want to remove data only from a specific device, enter the device ID into the Source field.
5. Enter the Maximum age in days (max. allowed value is 10 years in days).
6. Click Save to save your settings.

The retention rule will be added to the list.

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

Info: Alarms are only removed if they have a status of CLEARED.

To edit a retention rule

Simply click the row of the rule you want to edit or click the menu icon at the right of the respective row and then click Edit.

For details on the fields, see To add a retention rule.

To delete a retention rule

Hover over the rule you want to delete and click the delete icon at the right.

Info: All retention rules are executed sequentially and independent of each other. So if we have two retention rules, a more specific one with a greater maximum age that defines a subset of the documents that are defined by a more common rule with a lower maximum age, then effectively it will work as if we had a single, more common rule.

For example given the two following rules:

All measurements with the type c8y_Temperature which are older than 30 days will be removed, including those where the source equals 12345.

On the other hand when we have the following retention rules defined:

The retention process removes the measurements with the type c8y_Temperature which are older than 30 days, all other measurements will be removed when they are older than 60 days.

Info: The source parameter is the ID of the device. When it is defined, the retention process only removes the documents directly related to the device represented by the source, not its children or groups it belongs to.

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.

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 at the right of the respective row and then click Download.

To delete a file from your account

Click the menu icon at the right of the respective row and then click Delete.

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.

Two-factor authentication

The Two-factor authentication (TFA) is an extra layer of security that only completes authentication with a combination of two different factors: something the users know (username and password) and something they have (for example, smartphone) or something they are (for example, fingerprint). You can read more on how to configure TFA in the authentication settings section.

There are two possible TFA strategies: SMS and TOTP. Only one of them can be active at a time.

To check whether TFA is enabled for a certain user, go to the Users page and see the TFA status column right from the password strength column. A key icon indicates that TFA is enabled and by hovering over it you can see the strategy that is being used.

SMS

When adding a user and TFA is enabled, a mobile phone number must be specified. Without a valid phone number a login is impossible.

How to enable a specific user

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

Info: This process can only be executed in the Administration application and is not available under User settings.

TOTP (Google Authenticator)

Users have to install a TOTP application on their smartphone (Google Authenticator recommended), freely available both on App Store and Play Store.

Setup

Opposed to the SMS strategy TOTP has to be set up by each user. By opening User settings in the top right corner and then clicking Set up two-factor authentication they can start the setup process.

IF TFA is enabled, the user will be presented a QR code at login, that needs to be scanned with the previously installed TOTP mobile application.

Alternatively, the secret can also be inserted manually in case scanning the QR code is not an option.

After this process the mobile application will generate a new code every 30 seconds that can be used to complete the authentication process.

Revoking the secret

Info: Although the setup must be done by each individual user, revoking the secret can only be done by a user with “user management ADMIN” permission via the Administration application. As so, if the user loses the phone or uninstalls the application they must contact a user with this particular permission.

To revoke the key follow these steps:

1. Navigate to the Administration application.
2. Click on the desired user in the Users page.
3. Scroll down to Login Options.
4. Click Revoke TOTP secret.
5. Confirm by clicking Revoke.

Changing settings

From the Settings menu, administrators can manage various settings for the account:

• Configure authentication settings and single sign-on.
• Change the application settings.
• Manage the properties library.
• Provide SMS provider credentials.
• Manage the connectivity settings.

Changing authentication settings

Click Authentication in the Settings menu if you want to view or change the Login or TFA settings.

Info: If the menu is not visible, confirm the user has one of the following roles: ROLE_TENANT_ADMIN or ROLE_TENANT_MANAGEMENT_ADMIN.

Login settings

In the Preferred login mode field, you can select one of the following options:

• OAuth Internal - Recommended, since it provides high security, using authorization tokens to prove your identity (to the server).
• Basic Auth - Should be chosen only for specific compatibility reasons, since it only provides basic security.
• Single sign-on redirect - Can be selected only if SSO is configured. If selected, will remove Basic Auth and OAuth Internal login options.

This login mode will be used by the platform’s applications as the default method to authenticate users. Device authentication stays unchanged.

Info: If OAuth Internal is enforced, Basic Auth cannot be used to login to applications anymore. Older applications might fail to display the login correctly and need to be updated.

In the field Limit password validity for, 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).

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

Info: The password validity limit is not imposed on users with a “devices” role. This prevents devices passwords from expiring.

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 Getting Started > Accessing and logging into the Cumulocity IoT platform.

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 the settings.

Important: Each time you change the login mode you will be forced to log out. Other users will need to log out and log in again so that the change is applied.

TFA settings

Select the checkbox Allow two-factor authentication if you want to allow TFA in your tenant (only possible for administrators).

You may choose one of the following options:

• SMS-based, supporting the following settings:

  • Limit token validity for: Lifetime of each session in minutes. When the session expires or a user logs out, the user has to enter a new verification code.
  • Limit verification code validity for: 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.

  Info: An SMS gateway microservice must be configured for the tenant. Naturally only users with a valid phone number associated can use this functionality.

• Google Authenticator (Time-based One-Time Password = TOTP), supporting the following setting:

  • Enforce TOTP two-factor authentication on all users: When enabled it will force all users to set up their TFA on login. Otherwise each individual user can choose to activate it or not.

  Info: The TOTP method is only available with the login mode “OAuth Internal”.

Click Save TFA settings to apply your settings.

Important: Each time you change the TFA method you will be forced to log out. Users TFA settings are cleared and need to be configured again.

Info: Users with a “devices” role are excluded from TFA and TOTP. This is also true when TOTP is enforced for all users.

Oauth Internal

Cumulocity IoT OAuth Internal is based on JWT stored in a browser cookie. However, it doesn’t support refresh and after the token validity time has ended, the user will have to log in again. The default token validity time is two weeks and this can be changed with tenant options: oauth.internal.basic-token.lifespan.seconds. The minimum allowed value is 5 minutes.

Cookies used to store a token in a browser have their own validity time that can be changed with tenant options: oauth.internal.basic-user.cookie.lifespan.seconds. The default value is two weeks. It can also be set to a negative value so that the cookie will be deleted when the user closes the browser.

Configuring single sign-on

Cumulocity IoT 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 IoT version 10.4.6. For correct behavior any microservice needs to use the microservice SDK with version 10.4.6 or later.

Before switching to the single sign-on option it is mandatory that:

• The authorization server you use supports OAuth2 authorization code grant.
• The access token is issued as JWT and you know what goes into the token content.
• The JWT must consist of a unique user identifier, “iss” (issuer), “aud” (audience) and “exp” (expiration time) fields.
• The Cumulocity IoT platform is in version 10.4.6 but preferably higher.
• All microservices are build with Microservice Java SDK 10.4.6 but preferably higher. For custom-built microservices, refer to General aspects > Security in the Microservice SDK guide.
• For on premises installation the domain-based tenant resolution is configured properly.

Info: In order to use the single sign-on feature for Enterprise Tenants, the enterprise domain must be set up as redirect URI in the basic configurations. If single sign-on providers have a list of allowed domains, the enterprise domain should be added to that list.

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.

At the top left, you can choose a template. The chosen option has an effect on the look of the panel. The default template is “Custom” which allows for a very detailed configuration with virtually any authorization server using OAuth2 authorization code grant. Other templates provide simplified views for well known and supported authorization servers. In the next steps there will first be a definition of how to use the “Custom” template followed by a view dedicated to Azure Active directory.

Custom template

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, token and refresh method by POST requests.

Specifying a logout request is optional. It performs front-channel single logout. If configured, the user is redirected to the defined authorization server logout URL after logging out from Cumulocity IoT.

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

Each time a user logs in, the content of the access token is verified and is a base for user access to the Cumulocity IoT platform. The following section provides the mapping between JWT claims and access to the platform.

In the example above, if a user tries to login a decoded JWT claims look like:

{
...
"user": "john.wick",
...
}

The user will be granted access to the global role “business” and the default application “cockpit”.

If no access mapping matches the user access token, the user will get an “access denied” message when trying to log in. This will also happen if there is no access mapping defined causing all users to be unable to log in using SSO.

New rules can be added by clicking Add access mapping at the bottom. An access mapping statement can consist of multiple checks like in the image below. You can add a rule to an existing statement by clicking and. Click the Minus button to remove a rule.

New roles are added to the user from every matching access mapping. If one access mapping statement assigns the role “admin” and a second one assigns the role “business” and both meet the defined conditions, then the user will be granted access to the global roles “business" and “admin”."

When using “=” as operator you may use wildcards in the Value field. The supported wildcard is asterisk (*) and it matches zero or more characters. For example, if you enter “cur*” this matches “cur”, “curiosity”, “cursor” and anything that starts with “cur”. “f*n” matches “fn”, “fission”, “falcon”, and anything that begins with an “f” and ends with an “n”.

In case the asterisk character should be matched literally it has to be escaped by adding a backslash (\). For example, to match exactly the string “Lorem*ipsum” the value must be “Lorem\*ipsum”.

In this case the following claim will match the condition:

{
...
"user": {
   "type": "human"
},
"role": [
   "ADMIN"
],
...
}

As you can see, there is an option to verify if a value exists in a list via the “in” operator. Values can also be embedded in other objects. In this case a dot in the key implies looking into an embedded object.

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.

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

1. By specifying the Azure AD certificate discovery address.

2. By specifying the ADFS manifest address (for ADFS 3.0).

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

4. By specifying the JWKS (JSON Web Key Set) address.

Info: Cumulocity IoT only supports certificates with RSA key, either as a (“n”, “e”) parameters pair or “x5c” certificate chain. Other key types (e.g. Elliptic-curves) are not supported.

Placeholders

Inside some fields you can use placeholders that are resolved by Cumulocity IoT at runtime. Available placeholders are:

These placeholders can be used in authorization requests, token requests, refresh requests and logout request in the fields: URL, body, headers and request parameters

To use a placeholder in a field, put it inside two curly brackets preceded with a dollar sign:

Placeholders can also be used as a part of text:

Placeholders are not validated for correctness. Any not recognized or misspelled placeholder will be left in text unprocessed.

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.

When configuring your Azure AD, use your full domain address as redirect URI. For the purpose of this document we assume that it is “http://documentation.cumulocity.com/tenant/oauth”. The redirect URI must be set for a web application and not for a single-page application. There are no additional steps on Azure AD required.

Cumulocity IoT configuration

When the “Azure AD” template is selected the configuration panel will look similar to the following:

Optionally single logout can be configured:

The second part of the panel is the same as for the “Custom” template, where access mapping, user ID field selection and signature verification address are provided.

Troubleshooting

It can be particularly helpful to inspect the content of the authorization token sent to the platform as some of its fields contain the information required for the correct configuration described above.

In Administration application, after clicking on Accounts > Audit logs you can filter by the category “Single sign-on” and look for entries “Json web token claims”.

The contexts of the token will be presented in JSON format.

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 IoT API.

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

• Set it to “*” to allow communication from any host.
• Set it to http://my.host.com, http://myother.host.com to allow applications from http://my.host.com and from http://myother.host.com to communicate with the platform.

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

Managing the properties library

Click Properties library in the Settings menu, to add custom properties to inventory objects, alarms, events and tenants.

With custom properties, you can extend the data model of Cumulocity IoT 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.

To add a custom property

1. Select the tab for the desired property and click Add property.

   

2. In the resulting dialog box, provide a unique name as identifier and a label for the property and select its data type from the dropdown list.

3. Additionally, select validation rules for the new property:

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

4. Click Save to create the new property.

To edit a custom property

1. Click on the name of a property in the list to open it.
2. Do your edits. For details on the fields see To add a custom property.
3. Click Save to save your settings.

To remove a custom property

1. Click on the name of a property in the list to open it.
2. Click Remove to delete the property.

Providing SMS provider credentials

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

By providing your credentials you enable platform features that utilize SMS services.

To enter SMS provider credentials

1. Click SMS provider in the Settings menu.

   

2. In the SMS provider page, select either OpenIT or sms77 as SMS provider.

3. Depending on the selected provider, enter the relevant credentials:

   • For OpenIT, your OpenIT username and password.
   • For sms77, your API key to access sms77 (to be found in your sms77 login under Settings > HTTP API).

4. Click Save to save your settings.

Info: OpenIT does not serve new customers anymore and is in the process of shutting down their SMS provider business. We therefore recommend you to select sms77 as SMS provider.

Managing the connectivity settings

In the Connectivity page, you can manage credentials for different providers. In order to add or replace credentials ADMIN permissions are required.

The following provider settings may currently be specified:

• Actility LoRa
• Sigfox
• SIM

To provide or replace credentials

1. Switch to the tab of your desired provider.
2. Enter the URL of the provider.
3. Enter the credentials of your provider platform. Depending on the provider, these credentials will be either the credentials of your account in the provider platform or the credentials with which you can register in the Cumulocity IoT connectivity page, will be displayed in your account in the provider platform.
4. Finally, click Save to save your settings.

Depending on the provider you have selected, there may be additional fields, which will be explained in the respective agent documentation, see Protocol integration guide.

Platform configuration settings

From the Management tenant, you can configure properties which apply globally to the whole Cumulocity IoT deployment.

Click Configuration in the Settings menu, to access the Configuration page.

Most of the settings you can configure here are also available in the Enterprise tenant. For details, refer to Enterprise tenant > Customizing your platform.

In addition, the following settings can be configured in the Management tenant only.

Passwords

In the Passwords section, you can specify password settings like default strength, length or validity for the users in your tenant.

Select the checkbox Enforce “green” passwords for all users to enforce the users in your tenant to use passwords that meet the conditions for “green” passwords, see also Getting started > User options and settings.

• Password validity limit (days) - The number of days a password may be valid before it must be reset; minimum value is “0”, maximum value is “999999”. Leave empty to use the value from the tenant options configured in the Management tenant, see Cumulocity IoT Core - Operations guide.
• Password history size - The number of times before the current password can be reused. Minimum value is “0”, preset value is “10”.
• Minimum length of “green” password - The minimum number of characters which are required for a safe password. Minimum (and preset) value is “8”, maximum value is “32”. Leave empty to skip this constraint.

Support user

In the Support user section you can configure the parameters for the support user access for subtenant users.

This feature enables Cumulocity IoT platform providers (Software AG in case of the public cloud instances or service providers with on-premise installations) to support their customers by accessing their users using a support user. A support user is a user in the Management tenant that has specific permissions, i.e. to access subtenant users in case of any issues. Refer to Support user access for more information.

In the field Activate support user, specify if support user access is activated for subtenant users. Possible values you can enter here are:

• true: Support user access is activated for all subtenants by default. A support user can log into any subtenant as any user. Note that subtenant users cannot disable access themselves.
• false: Support user access is deactivated for all subtenants, but can be explicitly enabled for a subtenant. A support user can log in only to subtenants for which at least one user has explicitly enabled such access.
• An explicit date in date-time format, until when support user access should remain activated. If no date is specified the value is set to “No limit”.

In the Validity limit field, you can optionally specify the support duration, i.e. for how many hours support user access will be prolonged after each support user request from a subtenant user. Enter a number specifying the number of hours. The default value is 24 hours.

The expiry date-time will be updated based on the duration specified in the Validity limit field, e.g. if the current expiry date-time is 01/09/2018 15:00 and duration has been kept at 24 hours, the enabling support user will update the expiry date to 01/10/2018 15:00.

Details on the status of support requests and support user access for a tenant can be found in the Properties tab of the tenant, see Enterprise Tenant > Managing tenants.

Configuring a support user

A support user is a user in the Management tenant with specific permissions. This user can log in to the target tenant and impersonate the target user.

To configure a user in the Management tenant as support user, you need to assign the relevant roles to the user. This can either be done by using a global role or by inventory roles.

Using a global role

1. Create a role “Support” with “Support READ” and “Support ADMIN” permission.
2. Assign the role “Support” to the respective user and remove all other roles for the user.

Using inventory roles

Using inventory roles, you can selectively assign a support user for specific subtenants.

1. Create an inventory role called “Support” with type = “*” and permission = “All”.
2. Create a group of all subtenants which you want to be supported by the user.
3. Assign the “Support” inventory role to above group as described in Administration > Managing permissions > Assigning inventory roles to users.

Info: The support user feature does not work when the support user has two-factor authentication enabled, but no phone number is provided. The phone number has to be provided first, in order to login as a support user.