Enterprise Edition

The Enterprise Edition of Cumulocity provides several enhancements to the features provided by the Standard Edition. The following sections describe additional functionalities available in the Enterprise Edition.

Managing tenants

If you are a service provider or subscribed to the Enterprise Edition of Cumulocity, you may want to manage your own subtenants.

The tenants functionality allows you to create subtenants, subscribe them to the applications that you have available and potentially deactivate tenants if they are not in use anymore.

Important: There is an major difference between providing several tenants and providing several users with different permissions within a single tenant. Tenants are physically separated data spaces with a separate URL, with own users, a separate application management and no sharing of data by default. Users in a single tenant by default share the same URL and the same data space. So if your users, for example, are separate customers of yours and you need to strictly separate them because they may be competitors, we strongly recommend you to do so by working with tenants.

Info: If you would like to use this feature, please contact sales@cumulocity.com.

To be able to use the tenant functionality, your user needs to have the appropriate permissions. See Creating and editing global roles for information on editing permissions. Since editing tenants is a sensitive operation, permissions for editing tenants are more granular:

  • Read: Browse and view tenants.
  • Create: Create new tenants.
  • Update: Edit tenants (incl. subscriptions) and suspend or activate them.
  • Change: Create, edit and delete tenants.

Viewing subtenants

Click Subtenants in the Tenants menu to view a list of all subtenants available in your account.

The Tenants page provides the following information on each subtenant:

  • The name of the subtenant, e.g. company name of your customer.
  • The ID and domain. Note: The domain can be changed later on. The ID cannot be changed anymore once the tenant was created.
  • An optional contact name and phone number.
  • The date when the tenant was created.
  • The status of the tenant, either active (indicated by a green checkmark icon) or suspended (indicated by a red cross icon).

If you are using the management tenant, you will see an additional column "Parent tenant". This column shows the tenant that created the listed tenant.

Sub-tenants

Creating sub-tenants

To add a new tenant, click Create tenant at the right of the top menu bar. To create a tenant, provide the following properties:

Field Description
Domain/ URL Enter a unique ID as the first part of the URL. For example, if you enter "acme" as ID on cumulocity.com, the tenant's URL will be "acme.cumulocity.com". You can only use one subdomain level. For example, you can only use "acme.cumulocity.com" on cumulocity.com. You cannot use "mycustomer.acme.cumulocity.com". This is not permitted by the TLS standard.
Name The name of the tenant, e.g. the company's name.
Administrator's email You must provide a valid email address to enable users to reset their password.
Administrator's username Username for the administrator of this tenant.
Contact name Optional name of the contact.
Contact phone Optional phone number of the contact.
Send password reset link as email Selected by default. If you deselect this option, you need to provide a password and confirm the password (see Getting Started > Logging in for more information on password strength).
Tenant policy You may select a tenant policy to be applied to the tenant from the dropdown list.

Note, that fields with an asterisk * are mandatory.

Click Save to apply your settings.

When the tenant is created, it is automatically provisioned with a first, administrative user ("Administrator's username"). This administrator can create other users and set their permissions. The first user cannot be deleted to prevent you from locking yourself out.

From the management tenant, you can enable other tenants to create subtenants. To do so, check Allow creation of subtenants.

Tenant-creation

Editing subtenant properties

To edit subtenants, click on the desired subtenant or click Edit in the context menu, accessible through the menu icon.

In the Properties tab, all fields are editable except of the ID and the administrator's username. For details on the fields, refer to Creating sub-tenants.

Subscribing to applications

In the Applications tab you can subscribe tenants to applications or remove the applications from the tenant. By default, tenants will be subscribed to the standard Cumulocity applications.

Subscribe tenant

To subscribe an application to a tenant, hover over the applications under Available applications on the right and click Subscribe on the desired application.

To remove an application, hover over the applications under Subscribed applications on the left and click Unsubscribe.

Suspending subtenants

You can temporarily suspend tenants. Suspending tenants blocks any access to this tenant, regardless whether the access is from devices, users or other applications.

To suspend a tenant, click the menu icon and from the context menu select Suspend.

In the upcoming dialog confirm the suspension by clicking OK and entering your password. The tenant will be shown with a red cross icon. As part of suspending the tenant, an email is sent to the tenant administrator if an email address is configured for that administrator.

Info: If you are a service provider, you can suppress this email.

Suspend tenant

If a tenant is suspended, the tenant's data remains in the database and can be made available any time later. To do so, click Activate.

Deleting subtenants

To finally delete a tenant and remove all the data of the tenant, click the menu icon and from the context menu select Remove.

Info: This action cannot be reverted. For security reasons, it is only available in the management tenant.

Editing custom properties

The Custom properties tab allows you to view and modify values of custom properties, either predefined ones (like "External reference") or those defined in the Properties library. Such properties are also displayed as columns in the usage statistics table.

Custom Properties

Limiting subtenant device number

The platform administrator can limit the count of concurrently registered root devices or simply all devices (including children devices). The platform administrator can also see the peak number of concurrently registered devices, root devices and the peak value of used storage in the Usage statistics page.

Retrieving usage statistics

The Usage statistics page provides statistical information on each subtenant.

The following information is provided for each tenant:

  • ID: ID of the subtenant
  • API requests: Total number of API requests, including requests from devices and applications
  • Device API requests: Number of API requests from devices
  • Storage (MB): Amount of data stored in your account
  • Peak storage (MB): Peak value of storage
  • Root Devices: Number of root devices, excluding child devices
  • Peak root devices: Peak number of root devices, excluding child devices
  • Devices: Total number of devices connected to the subtenant, including child devices
  • Peak devices: Peak number of devices, including child devices
  • Endpoint devices: Leaf machines, without gateways and edges
  • Subscribed applications: Number of applications that the subtenant is subscribed to
  • Creation time: Date and time of the creation of the subtenant
  • Alarms created: Number of alarms created
  • Alarms updated: Number of updates on alarms
  • Inventories created: Number of managed objects created
  • Inventories updated: Number of updates on managed objects
  • Events created: Number of events created
  • Events updated: Number of updates on events
  • Measurements created: Number of measurements created
  • Total inbound transfer: Sum of all inbound transfers (alarms created, alarms updated, events created, events updated, inventories created, inventories updated, measurements created)
  • Parent tenant: Name of the parent tenant (available only for management tenant)
  • External reference: This field is for individual usage, for example, you can add a link to the CRM system here or an internal customer number.

Moreover custom properties are displayed, if configured.

Custom properties may be defined in the Properties Library and then set their values in the Custom properties tab of the tenant.

Usage statistics

You can filter the usage statistics list for a time period by adding the start and end date in the top menu bar and click Filter. You can also filter and sort the list on any column by clicking the filter icon next to the column name and providing the filtering criteria. For details on filtering, refer to Getting Started > Features and Functionalities > Filtering.

Click Export CSV at the right of the top menu bar to export the current view of the statistics table to a CSV file. A dialog will come up in which you can customize the CSV output.

Tenant policies

A tenant policy is a set of tenant options and retention rules. Tenant options and retention rules may be specified during tenant creation.

Creating a tenant policy with a specific set of options and rules saves time when creating multiple tenants with the same settings.

Tenant policy

Info: The options and rules are copied into the tenant. Editing the policy has no effect on tenants that have already been created.

Click Tenant policies in the Tenants menu to view all tenant policies available.

Tenant policies

For each tenant policy, the name, an optional description and the number of options and retention rules is provided, either in a list or a grid.

Adding a tenant policy

Click Add tenant policy in the top menu bar to create a new tenant policy.

Add new policy

  1. Enter a name and an optional description.
  2. Add at least one retention rule. For details on creating retention rules, refer to Administration > Retention rules.
  3. Optionally, add a tenant option.
  4. Click Save to save your settings.

Editing, duplicating and deleting policies

To edit a policy, click on the desired policy or click Edit in the context menu, accessible through the menu icon.

To change the name of a policy, click the name in the top bar, modify it and click the green checkmark icon to save your changes.

To delete a retention rule or a tenant option from a policy, hover over it and click the delete icon.

To duplicate a policy, click the menu icon and from the context menu select Duplicate.

To delete a policy, click the menu icon and from the context menu select Delete.

Edit policy menu

Managing user hierarchies

With user hierarchies you can reflect independent organizational entities in Cumulocity that still share the same database. These entities can have limited permissions to subsets of the shared data and can manage their own sub-users.

Info: To be able to use this feature, your tenant must be subscribed to the application "FEATURE.USER.HIERARCHY".

Viewing user hierarchies

In the User page, user hierarchies are indicated by an arrow left from the user icon. Clicking on the arrow unfolds the user hierarchy. You can also fold and unfold the entire user hierarchy using the Expand all and Collapse all links on the top right.

A small number next to the user name shows how many direct sub-users a user has. Sub-users are users that can be managed by their respective parent user and that have at most the permissions of that parent user. In the example below, the user "TestUser" has two direct sub-users.

User hierarchies

Creating sub-users

User hierarchies are created by assigning an "owner" to a user. The "owner" can manage the user. The user can have at most the same permissions as the owner.

To assign an owner to a user, select the user in the Users page. In the Owner field, select a user from the dropdown list and click Done to confirm.

Select owner

Info: When creating a new user, the owner is automatically set to the user who is logged in. The owner can be changed later. Only users with USER ADMIN permission can assign an owner to a user.

If you want an owner to manage only their sub-users, make sure that the owner does not have a global role with user management permissions for all users.

As an example, the sample below shows a user with a business role. The user becomes the owner of a new user. Therefore the new user can only get a business role assigned as the user cannot have higher permissions than the owner.

Owner Sample

Delegating user hierarchies to other users

In Cumulocity, users can delegate their user hierarchies and permissions to another user. The delegated user then has the same user management permissions as the user who activated the delegation.

You may of course also delegate on a temporary basis, for example if you are temporarily unavailable.

To delegate your permissions to a user, either open the user and click the delegate icon in the Delegated by field, or click the menu icon at the right of the user entry in the user list and from the context menu, select Delegate.

User delegation

To undelegate, remove the delegation in the Delegate by field, or click Undelegate in the context menu.

If the delegated user also needs to manage specific devices, the admin user must assign this device permissions (inventory roles) directly to the intended user. This can be done by using Copy inventory roles from another user. For details refer to Administration > Managing permissions > Assigning inventory roles to users.

Info: Delegation works only inside user management and does not have any implication to other places.

Troubleshooting sub-users

In the example below the user cannot change the access to the Administration application, because the owner of the user has no USER MANAGEMENT permissions. As a result, the owner user can not assign built-in applications (and the owned user cannot use them).

Warning message

Supporting users in other tenants

Support users are users in the management tenant with a special permission to log in as other tenant's users. As an example, suppose you get a support call from a user "john" in the tenant "acme.cumulocity.com". The user cannot run certain functionality, and you suspect that it is a permission issue. Your username in the management tenant is "jill" and you are permitted to carry out support for "acme.cumulocity.com". In this case, you can log in to "acme.cumulocity.com" using the username "jill$john" and your password for "jill". Now you can reproduce what "john" is seeing.

Configuring support users

There are two alternative setups for support users in Cumulocity:

  • A service provider configures specific permissions for management tenant users which enable them to provide support.
  • Tenant users request support and by this provide the permission to management tenant users to login.

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.

Management tenant permission

To enable a management tenant user to support users in other tenants, you need to provide the user with either the "Support" global permission or the "Support" inventory role (both "Read" and "Change").

Using the "Support" inventory role, you can selectively assign support to particular users. Create a group of the tenants that you want the user to support, then assign the inventory role to the user and the group as described in Assigning inventory roles to users.

User-provided permission

Users can allow support, i.e. a management tenant user logging in as them. To do so, click the User button at the right of the top bar and from the context menu select Enable support. Click Ok to confirm. Support will be active for 24 hours.

Enable support

Logging in as support user

To log in as support user, use the following username:

<support user>$<user>

"support user" is the user in the management tenant that executes the support. "user" is the supported user.

Alternatively, use

<support user>$

In this case, the support user will access the tenant with one of the administrative users.

Important: In many environments, access to the management tenant is specifically restricted to certain networks or hosts, or can only be used through a tunnel. When logging in using the support user functionality, you need to make sure to have access to the management tenant. If you use a tunnel to access the management tenant, you may need to use a login of the form <tenant>/<support user>$<user>.

Audit logs are created for each support user access and for the actions that support users perform. In the column "Who?" the author's name will be shown in form of:

"support_user$user"

Using the data broker

Data broker lets you share data selectively with other tenants. You can share:

  • devices (and more generically, managed objects),
  • events,
  • alarms,
  • measurements,
  • operations.

Navigate to Data connectors if you would like to send data to another tenant. Navigate to Data subscriptions, if you would like to receive data from another tenant.

Data broker menus

Info: Devices that are forwarded using the data broker are charged like normal devices in the destination tenant.

Be aware of the following limitations of the data broker:
Cloud Remote Access cannot be used on the destination tenant.
Currently, the Fieldbus widget does not work on tenants that receive the fieldbus devices through data broker, as the corresponding data models are not synchronized.
While we provide backwards compatibility, we can not ensure that data broker can send data to Cumulocity tenants which run on later Cumulocity versions than the source.

Data connectors

A data connector describes the subset of the data that you would like to send to a destination tenant as well as the URL of that destination tenant.

Viewing data connectors

In the Data connectors page, you can manage existing data connectors or create new ones. Click Data connectors to see a list of all currently defined data connectors with their status.

Data broker connectors list

For each data connector, the following information is provided:

  • the data connector's name
  • its destination tenant
  • a description
  • the status
  • the number of filters set for the data connector

Use the slider to enable and disable data forwarding to the destination tenant. If data is being forwarded, the slider reads "active". If data is not being forwarded, the slider reads "suspended" or "pending". "Suspended" means that you have disabled forwarding. "Pending" means that the destination tenant has disabled forwarding.

  • To modify the data connector's configuration, click the menu icon and from the context menu select Edit. The configuration is described in more detail below.
  • Click "Duplicate in the context menu to create another data connector with the same configuration.
  • Click Delete in the context menu to stop data forwarding and remove the data connector.

Creating or editing data connectors

Click Add data connector in the top menu bar to create a new data connector.

Data broker edit connector

To create a new data connector provide the following information:

Field Description
Title The name of the data connector.
Target URL for data connector The URL of the tenant to which data will be forwarded. Once saved, you cannot edit this value anymore.
Description A textual description of the configuration. Both the name and the description will be visible on the destination side after accepting the subscription.
Data filters A set of filters that define what is copied to the destination. You need to configure at least one filter.

Each data filter contains the following information:

Field Description
Group or device The group or device that is forwarded. Selecting a group here results in all sub-groups and sub-devices being forwarded. By default, all data is forwarded.
API The type of data being forwarded (alarms, events, measurements, manages objects) or being received (operations).
Fragments to filter The fragments that need to be present in a device to be forwarded.
Fragments to copy The fragments that are copied to the destination. If nothing is specified here, only standard properties of managed objects, alarms, events and measurements are forwarded (see below). Select Copy all fragments to forward the entire object.
Type filter Forwarded data needs to have this value in its "type" property.

Info: If the Group or device field is filled in the entire descendant structure of the inventory is forwarded to the destination as soon as the connector stays active. if the Group or device field is empty or set to "all" the descendant structure of the inventory is not forwarded; in this case the filter works in "lazy" mode, i.e. forwards the device or asset along with its first event/measurement/alarm.

If operation API is checked in filters, operations created in the target tenant will be forwarded to the source tenant. This applies only to operations that meet the following conditions:

  • operation's device itself is a result of forwarding data;
  • operation matches other filter criteria.

Update of operation status coming from source will be forwarded to the destination tenant.

The heading of a data filter summarizes the configuration in one line. The standard properties that are copied by default are:

  • For created alarms: type, text, time, severity, status.
  • For updated alarms: status, text, severity.
  • For created events: type, text, time.
  • For created measurements: type, text, time
  • For created and updated devices: type, name, c8y_IsBinary, c8y_IsDeviceGroup, c8y_IsDevice, c8y_DeviceGroup, c8y_DeviceSubgroup, c8y_SmartRule, c8y_DynamicGroup, c8y_DeviceQueryString.
  • For updated operations: status

Once you have configured your data connector, click Save to save the configuration.

After saving, you will see a security code displayed below your configuration. The security code prevents unintended forwarding of data. You need to communicate this security key separately to an administrative user of the destination tenant. You can use the icon next to the security code to copy the code to your clipboard.

Security code

Data subscriptions

In the Data subscriptions page, you can manage existing data subscriptions or create new ones.

Click Data subscriptions to see a list of all currently defined data forwarded to your tenant.

Data subscriptions

For each subscription, the name, the target tenant and the status (enabled or disabled) is provided on a card.

Use the slider to temporarily stop forwarding data into your tenant.

To stop data forwarding and remove the data connector, click the menu icon and from the context menu select Delete.

How to set up data forwarding on the receiving end

  1. Click Add data subscription in the top menu bar to receive data.
  2. In the new card, enter the security code that you received from the sending end of the data.
  3. When the connection is established, click Accept to start forwarding data into your tenant. The subscription is active now.
  4. You can move the slider in the card to temporarily stop forwarding data into your tenant.

You can now navigate to the Device Management application or the Cockpit application. There will be a new "virtual group" with a specific icon (see the screenshot below) showing the forwarded devices. The group will have the same name as your subscription. Devices are "lazily" created on the destination side whenever they send data for the first time after setting up an active subscription.

Data broker group in cockpit app

Troubleshooting

Error message

Data broker processing is currently overloaded and may stop processing your events. Please contact support.

Description

The data broker queue for the respective tenant is full. This might for example happen when more events are created then currently can be handled.

In this case, an alarm will be raised. To avoid losing incoming new events, the oldest events will be deleted, i.e. an incoming new event triggers the deletion of the queue head event. To reduce spam, the alarms and logs are triggered once per minute.

Customizing your platform

In an Enterprise Edition installation under the Settings menu you can specify settings for the customization of your platform.

Info: For information on the settings in the Customization tab refer to Changing Settings > Configuration settings in the Administration section.

Branding

In the Branding tab you can fully customize the look of your tenants to your own preferences.

The branding feature allows you to edit the logos and colors used throughout the platform. Once your branding settings are saved, all subtenants are automatically updated.

Branding tab

General

In the General section you can edit the title which will be used in the browser tab.

Main logo

Under Main logo, specify the following items:

  • The favicon, which will be displayed in the browser’s address bar. Click Choose file to select a file from your computer. The supported favicon format is “ico”.
  • Your branding logo, which will be shown during application loading. Click Choose file to select a file from your computer. The supported formats are “png” and “svg”.
  • The brand logo height.

Navigator logo

Under Navigator logo you can provide the navigator logo and set the navigator logo height located on top of the navigator panel.

Type

In the Type section you specify the font settings for your branded version.

Branding type

You can choose your base and headings font, and select an option for the navigator font (either same as base or same as headings font). You may also add a link to existing remote fonts to be used.

Colors

In the Colors section you specify the colors to be used in your branding version.

Branding color

The following parameters can be specified by providing a hex, rgb or rgba value:

  • Main brand color.
  • Secondary brand color. The default value is “#07b91A”.
  • Text color. The default value is “#444”.
  • Link color. The default value is the same as the main brand color.
  • Main background color. The default value for this item is “#FAFAFA”.

Top bar

In the Top bar section you specify the parameters for the top bar.

Branding topbar

The following parameters can be specified by providing a hex, rgb or rgba value:

  • Background color. The default value is “#FFFFF”.
  • Text color. The default value is “49595B”.
  • Button hover text color. The default value is the main brand color.

Navigator

In the Navigator section you specify the parameters for the navigator.

Branding top bar

The following parameters can be specified by providing a hex, rgb or rgba value:

  • Background color. The default value is “2c3637”.
  • Logo wrapper background color. The default value is “Transparent”.
  • Title color. The default value is “FFFFF”.
  • Text and buttons color. The default value is “#FAFAFA”.
  • Separator line color. The default value is “#FAFAFA”.
  • Text color of the current item in the navigator. The default value is “#FAFAFA”.
  • Background color of the current item in the navigator with the main brand color as default.

Misc

In the Misc section you may specify the “Button Border-Radius” by providing a value in pixel (px).

Click Save to save your settings.

Click Preview in the top menu bar to preview the new branding.

Click Generate in the top menu bar to apply your new branding.

The following image shows an example where

  • the main brand color is purple,
  • the secondary brand color is white,
  • the main background color is blue,
  • the top bar background color is green,
  • the navigator background color is pink.

Branding example

Domain name

In the Domain name tab you can activate your own custom domain name.

Info: To activate you domain, you need a valid license. Please contact our Sales team at sales@cumulocity.com to install a license for your domain.

Domain name

First you have to upload the appropriate certificate by clicking Upload Certificate. Make sure that

  • the certificate is in a valid PKCS#12 format,
  • the certificate is not password protected,
  • you are using a wildcard certificate to enable creation of subtenants.

Before activating the custom domain name, make sure that

  • you have uploaded a valid SSL certificate for your custom domain,
  • the common name (domain name) is not used by any other tenant,
  • the certificate is currently valid (validFrom in the past and validTo in the future),
  • you have added a wildcard CNAME record (starting with ".") to your DNS server of the following format:
    Hostname = `
    ., e.g.*.iot.mycompany.com<br> Type = CNAME <br> Target = the target URL of the platform you want to point to, e.g.manage.cumulocity.com`
    Make sure to remove all A entries for the wildcard domain. If your DNS service does not provide CNAME entries for wildcard certificates, please contact our support.

After successful activation you will be redirected to your enterprise tenant at the new domain. You will also receive an email with information about the activation.

Info: After the activation is completed you will no longer be able to access your tenant with the cumulocity domain name. Instead, use your custom domain name.

Updating your certificate

When your certificate expires, you must update your certificate with a new one with an extended validation period. When updating a certificate, you need to make sure that

  • the certificate is in a valid PKCS#12 format,
  • the certificate is not password protected,
  • the certificate is currently valid (validFrom in the past and validTo in the future),
  • the certificate has exactly the same common name (domain name) as the currently active certificate,
  • you have added a CNAME record to your DNS server. For details on the CNAME record see above.

Deactivating your certificate

If you wish to return to your old domain at Cumulocity, you can simply deactivate you certificate.

Important: Use with care. Your customers will not be able to access their subtenants anymore.

Troubleshooting

In case you cannot reach Cumulocity using your custom domain, we recommend to perform the following checks to verify your DNS setup.

Check if the DNS entry is correct

Execute the following command:

host management.<your domain name>

The following result should be returned:

management.<your domain name> is an alias for <instance domain name>
<instance domain name> has address <ip address>

Check if the API is responding

Execute the following command:

curl -v -u '<tenant ID>/<your user>:<your password>' --head http://management.<your domain name>/inventory/managedObjects

The following result should be returned:

...
HTTP/1.1 200 OK
...    

Info: Take into consideration that after changing the DNS entry it might take up to 24 hours until the new entry has been propagated.

Storage quota

The storage quota is in place for a tenant when a storage quota per device is set by the platform administrator. The total storage available to the user is calculated using the formula storage quota per device x number of devices. A check is performed every night to ensure the quota is not exceeded.

In case the quota is exceeded, an e-mail is sent to all tenant administrators to warn them that data will be deleted the following night. After 24h, if the quota is still exceeded, all data retention limits are reduced by a fixed percentage. The storage quota per device will be reduced as a result of this rule.

Example:

Let us assume that a tenant has a storage quota of 10GB. Retention rules are 80 days for measurements, 90 days for all other data.

  • Day 1: In the nightly check, the total storage is calculated at 13GB. An e-mail is sent to all tenant administrators.

  • Day 2: the total storage is still at 13GB. The system determines that a 15% reduction of the retention rules is sufficient to be under the storage quota. So any measurement older than 68 days (80 days - 15%) and any other data older that 77 days (90 days - 15% results in 76.5 days, rounded to 77 days) is deleted.

The total storage is now at 9.8GB.

Managing storage quota warning e-mail

This feature is only visible if a storage quota was set for the tenant.

The tenant administrators can set a user group and threshold for an e-mail to be sent once a day if the storage used is higher than a particular percentage of the storage quota. The default setup is sending an e-mail to the "admin" group when the storage reaches 80% of maximum storage.

The e-mail warning can also be disabled.