Enterprise Tenant

Managing tenants

Using the Enterprise Tenant of Cumulocity IoT, you can make use of the tenants functionality which allows you to create and a manage subtenants.

Important: There is a 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.

To view subtenants

Click Subtenants in the Tenants menu to view all subtenants available in your account, either in a grid or a list.

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.
• Optionally, a 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).

In the management tenant, you will also find information on the parent tenant, i.e. the tenant that created the listed tenant.

To create a subtenant

1. Click Create tenant at the right of the top menu bar.

   

2. Provide the following properties:

   Field	Description
   Domain/ URL	Enter a subdomain of your choice, for example "acme". The tenant's URL will be "acme.cumulocity.com" on 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. The tenant domain may contain lowercase letters, digits or hyphens. It must start with a letter; hyphens are only allowed in the middle; minimum is 2 characters. Note that the usage of underscore characters is deprecated but still possible for backward compatibility reasons.
   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 > Accessing and logging into the Cumulocity IoT platform for more information on password strength).
   Tenant policy	You may select a tenant policy to be applied to the tenant from the dropdown list.

3. Click Save to apply your settings.

When the subtenant is created, it gets an auto-generated ID, which cannot be changed. Also, 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 in the tenant editor.

To view or edit subtenant properties

Click on the desired subtenant or click the menu icon at the right of the subtenant entry and then click Edit.

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.

To change the tenant password, click Change password, enter the new password in the upcoming fields and click Save.

Support user access

In the management tenant, you will moreover find information here on the support user requests/access for the subtenants.

The following information is displayed here:

Suspending subtenants

Suspending a tenant blocks any access to this tenant, regardless whether the access is from devices, users or other applications.

If a tenant is suspended, the tenant’s data remains in the database and can be made available later by clicking Activate.

Important: Suspended tenants for all Cumulocity IoT Public Cloud instances will be automatically deleted after 30 days.

Info: If data broker connectors are configured for a tenant, suspending this tenant results in suspending all its data broker connectors as well.

To suspend a subtenant

1. Click the menu icon at the right of the respective subtenant entry and then click Suspend.

   

2. In the resulting dialog box confirm the suspension by clicking OK and entering your password.

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.

Deleting subtenants

Important: Deleting a subtenant cannot be reverted. For security reasons, it is therefore only available in the management tenant. You cannot delete tenants from any tenant but the management tenant.

Administrators in Enterprise Tenants are only allowed to suspend active subtenants, but not to delete them.

To delete a subtenant

Click the menu icon at the right of the respective subtenant entry and then click Delete to finally delete a tenant and remove all the data of the tenant.

Applications

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

To subscribe an application

Hover over the applications under Available applications on the right and click Subscribe on the desired application.

To unsubscribe an application

Hover over the applications under Subscribed applications on the left and click Unsubscribe.

Monitoring microservices

For all applications hosted as microservices by Cumulocity IoT the status of the microservice is indicated next to its name by symbols:

The microservice may be in one of the following states:

• Microservice is up and running
•   Microservice is unhealthy
• Microservice is down

You may view details on their status by expanding the respective entry.

The following information is provided:

• Active: The number of active microservice instances
• Unhealthy: The number of inactive microservice instances
• Desired: The number of desired microservice instances
• Name: Microservice instance name
• Restarts: The number of microservice instance restarts

Further details are provided on the Status tab of the respective application, see Administration > Managing applications.

Custom properties

The Custom properties tab allows you to view and edit 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 page.

Limiting subtenant device number

Platform administrators can limit the count of concurrently registered root devices or simply all devices (including children devices) via the custom property “Limit number of devices”.

They can view the peak number of concurrently registered devices, root devices and the peak value of used storage in the Usage statistics page.

Limiting subtenant request rate

Platform administrators can limit the request rate of each subtenant via the following custom properties:

• Limit HTTP queue - Limit of HTTP request queue for tenant
• Limit HTTP requests - Limit of HTTP requests for tenant per second
• Limit stream queue - Limit of MQTT request queue for tenant
• Limit stream requests - Limit of MQTT requests for tenant per second

It is also possible to customize the buffer size for the CEP queue and the data broker queue for a particular tenant. This can be done from the management tenant by using the following subtenant custom fragments:

• cep.queue.limit
• data-broker.queue.limit

When there is no limit on tenant and system level, the limit feature is considered as disabled and the tenant gains unlimited access. To switch off request rate limiting after it was enabled, set the value to “-1”.

Usage statistics

The Usage statistics page provides statistical information on each subtenant.

The following information is provided for each subtenant (not completely visible in the screenshot above due to space restrictions):

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.

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. See also Getting Started > UI functionalities and features> Filtering.

To export the usage statistics table

1. Click Export CSV at the right of the top menu bar to export the current view of the statistics table to a CSV file.
2. In the resulting dialog box you can customize the CSV output by specifying a field separator, decimal separator and charset.
   
   
3. Click Download to start the export.

The CSV file will be downloaded to your file system.

Microservice usage

The microservice usage feature gathers information on the resource usage per subtenant for each microservice. This enables Enterprise Tenants and service providers to charge tenants not only based on subscriptions but also based on resources usage.

Billing modes

Cumulocity IoT offers two billing modes:

• Subscription-based billing: Charges a constant price when a tenant is subscribed to a microservice while resource usage is assigned to the owner.

• Resource-based billing: Exposes the number of resources used by a microservice to calculate billing.

The billing modes are specified per microservice in the microservice manifest and are set in the field “billingMode”.

RESOURCES: Sets the billing mode to resources-based. This is the default mode and will be applied to all microservices that are not explicitly switched to subscription-based billing mode.

SUBSCRIPTION: Sets the billing mode to subscription-based.

Isolation level

Two isolation levels are distinguished for microservices: per-tenant isolation and multi-tenant isolation.

In case of subscription-based billing, the entire resources usage is always assigned to the microservice owner, independent of the isolation level, while the subscribed tenant will be billed for the subscription.

In case of resources-based billing, charging depends on the isolation level:

• Per-tenant - the subscriber tenant is charged for used resources
• Multi-tenant - the owner of the microservice is charged for used resources

In case of multi-tenant isolation level, the parent tenant as the owner of a microservice (e.g. the management tenant of an Enterprise Tenant or service provider) is charged for both subscribed applications (subscription-based billing) and used resources (resource-based billing) of the subtenants.

Resources usage assignment for billing mode and isolation level

Collected values

The following values are collected on a daily base for each tenant:

• CPU usage, specified in CPU milliseconds (1000m = 1 CPU)
• Memory usage, specified in MB

Microservice resources are counted based at limits defined in the microservice manifest per day. At the end of each day, the information about resource usage is collected into the tenant statistics. It is also considered that a microservice might not be subscribed for a whole day.

Example: If a tenant was subscribed to a microservice for 12h and the microservice has 2 CPU and 2 GB of memory it should be counted as 1000 CPU milliseconds and 1024 MB of memory.

For billing purposes, in addition to CPU usage and memory usage the cause for the billing is collected (e.g. owner, subscription for tenant):

{
  "name": "cep",
	"cpu": 6000,
	"memory": "20000",
	"cause": "Owner"
},
{
  "name": "cep-small",
  "cpu": 1000,
  "memory": "2000",
  "cause": "Subscription for tenant"
}

The information on the microservice usage is presented in the Usage Statistics page.

For more details, refer to Tenants > Tenant usage statistics in the Reference guide. Note that details are available only for daily usage. For a summary query only the sum of all issued requests is returned.

Scaling

Auto-scaling monitors your microservices and automatically adjusts capacity to maintain steady, predictable performance at the lowest possible cost. It is easy to configure the microservice scaling by setting the property scale in the Microservice manifest.

For instance, when you have a microservice with scale policy set to AUTO and the CPU usage points that it is needed to start a new microservice instance for three hours, the billing logs: (24/24 + 3/24) * consumed resources.

24/24 - one instance active for the whole day
3/24 - second instance active only three hours

Note that an audit record is created for every change of the number of instances.

For more information, refer to Auditing in the Reference guide.

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.

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

To view tenant policies

Click Tenant policies in the Tenants menu to view all 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.

To create a tenant policy

1. Click Add tenant policy in the top menu bar.
   
   
2. In the resulting dialog box, enter a name and an optional description.
3. Add at least one retention rule. For details on creating retention rules, see Administration > Managing data retention > Retention rules.
4. Optionally, add a tenant option.
5. Click Save.

The tenant policy will be added to the tenant policies list.

To edit a tenant policy

Click the respective policy entry or click the menu icon at the right of the policy entry and then click Edit.

In the resulting dialog box, make your edits and click Save to save your settings.

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

To duplicate a tenant policy

Click the menu icon in the tenant policy entry you want to duplicate and then click Duplicate.

To delete a tenant policy

Click the menu icon in the tenant policy entry you want to delete and then click Delete.

Managing user hierarchies

With user hierarchies you can reflect independent organizational entities in Cumulocity IoT 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-hierachy”.

Viewing user hierarchies

In the Users 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 at the right of the top menu bar.

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 “Demo user” has one direct sub-user.

To create a sub-user

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.

1. Select the user in the Users page.
2. In the Owner field, select the user you want to assign as owner from the dropdown list.
3. Click Done to confirm.

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.

Example

A user A has the role “business”. User A becomes the owner of a new user B. User B can then only get a business role assigned (and not for example an admin role) as the user cannot have higher permissions than the owner.

Delegating user hierarchies to other users

In Cumulocity IoT, 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 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.

To undelegate permissions

Remove the delegation in the Delegate by field, or click the menu icon at the right of the user entry in the user list and from the context menu, select Undelegate.

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” permission. As a result, the owner user can not assign built-in applications (and the owned user cannot use them).

Customizing your platform

Using the Enterprise Tenant of Cumulocity IoT, you can customize your platform according to your wishes and requirements.

In the Settings menu, you may specify various customization settings.

Configuration

Info: For information on the general settings in the Customization tab, see Changing Settings > Configuration settings in the Administration section. Here, only the features will be explained which are exclusively available for Enterprise Tenants.

Applications

In the Applications section, you can specify the default applications for new tenants as a comma-separated list.

Passwords

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

Support user

In the Support user section, you configure the parameters for the support user activation for subtenant users.

With the support user feature, support users (i.e. users with specific permissions in the management tenant) can 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 enabled for subtenant users. Possible values you can enter here are:

• true: Support user access is activated. If support user access is activated, support users can log into any subtenant as any user, unless overridden on subtenant level. Subtenant users cannot disable access themselves.
• false: Support user access is deactivated. If support user access is deactivated, support users 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 activation should remain enabled. 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 Managing tenants.

Branding

With the Branding feature, you can fully customize the look of your tenant to your own preferences.

In the Branding tab, you can configure various parameters like logos, colors and font types used throughout the platform.

The parameters are configured on the left side of the tab while on the right you can immediately see your selections applied to a preview extract.

For a more detailed preview of your settings, click Open preview in the top menu bar to check the look and feel of your branding settings in the overall platform. You may interact and even switch applications in the preview. Every change that you make in the Branding tab will immediately be applied to the Preview page.

When you are done or want to store your settings, click Save at the bottom of the Configuration section to save your branding settings to your tenant.

Saving the settings will not yet apply them to the current tenant and respective subtenants. To do so, click Apply in the top menu bar.

Click Reset in the top menu bar to reset the branding of the current tenant and its subtenants to the default settings. The custom settings will still be saved but are no longer applied.

Configuration parameters

In the Configuration section, the following branding parameters can be configured.

General

Under General, 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.

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.

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”.
• Dark brand color.
• Light brand color.
• 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.

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.

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

Cookie banner

In the Cookie banner section you specify the settings for the banner with the cookie usage information. The banner is shown for all users of the current tenant and subtenants until a user clicks Agree and proceed.

The following parameters can be specified:

• Title. Cookie banner title.
• Text. Cookie banner text with a general statement on the cookie usage and the use cases for it.
• Link to privacy policy. A link to the page with the privacy policy.

Domain name

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

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

Info: The custom domain name functionality is only available for cumulocity.com or Private Edition installations which don’t use a custom load balancer.

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

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

Info: If your certificate is not in a valid PKCS#12 format but you have PEM files for certificate, private key and authorization chain then you can generate a valid PKCS#12 file using the following command:

openssl pkcs12 -export -out out_keystore.p12 -inkey privkey.pem -in cert.pem -certfile chain.pe

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:
  Domain name = “*.<your domain name>”, e.g. “*.iot.mycompany.com”
  Type = CNAME
  Target = the domain of the platform you want to point to, e.g. if you use https://demos.cumulocity.com to access your tenant, use “demos.cumulocity.com” as target.
  Make sure to remove all A entries for the wildcard domain. For example, if you already have an A entry for “xxx.iot.mycompany.com”, you cannot create tenants with the URL “xxx”.

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

Info: Keep in mind that after replacing the certificate it may take some minutes until the new certificate has been delivered to the users/browsers.

Deactivating your certificate

If you wish to return to your old domain at Cumulocity IoT, 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 IoT 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: Keep in mind that after changing the DNS entry it might take up to 24 hours until the new entry has been propagated.

Support user access

With the support user access feature, support users, i.e. users of the management tenant with specific permissions, can log into accounts of other subtenant’s users to provide help in case of any issues.

To do so, support user access must be enabled. This can globally be done on platform level or on user level as described below.

Configuring support user access

Support user access may be enabled on different levels.

Platform level

The management tenant can enable support user access for all subtenants on platform level. This is done in the Configuration page, see Customizing the platform.

If support user access is enabled, support users can log into any subtenant as any user, unless overridden on subtenant level. Subtenant users cannot disable access themselves. If support user access is disabled support users can log in only to subtenants for which at least one user has explicitly enabled such access, as described next.

Subtenant/user level

If support user access is disabled on platform level, it may still be enabled by a subtenant user. This is done by clicking Enable support in the User menu, see Getting started > User options and settings.

The support access is then not restricted to the user who activated it but applies to all users of the subtenant. This is necessary for retracing of role/right issues.

After a user has activated support access, the menu item changes to Disable support, so that the user can disable a pending support request which has been resolved actively before it expires.

Info: If a user with tenant management admin permissions disables the support request, all support requests for the tenant will be disabled.

The duration of the active support request is configurable on platform level (default is 24 hours), see Customizing the platform.

Each new support request will prolong the support duration for the specified number of hours. After the last support request in a subtenant has expired or has been actively disabled by the user, the support user access for the subtenant will immediately be disabled (if not enabled globally).

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

Configuring support users

There are two alternative setups for support users in Cumulocity IoT:

• 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 role 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 Administration > Managing permissions > 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 access. For details, refer to Getting started > User options and settings.

To log in as support user

To log in as support user from the management tenant, use a login of the form:

<tenant id>/<support user>$<user>

• tenant id is the tenant ID of the user to be supported. The tenant ID is shown in the user dropdown menu in the UI.
• support user is the username of the management tenant user that executes the support.
• user is the username of the supported user.

Example

Suppose you get a support call from a user “John” in the tenant testtenant.cumulocity.com (which has the ID t07007007). 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 testtenant.cumulocity.com. In this case, you can log in with the following command to reproduce what John is seeing:

<t07007007>/Jill$John

In some environments, especially in test environments, you can simply open the destination tenants URL (e.g. testtenant.cumulocity.com) and log into the tenant using

<support user>$<user>

Alternatively, use

<support user>$

to access the tenant with one of the administrative users.

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 the 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 in the Data Broker menu if you would like to send data to another tenant. Navigate to Data subscriptions, if you would like to receive data from another tenant.

Important: 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.
• The management tenant cannot be used as data broker source 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.
• Data broker does not guarantee the same order of messages on destination tenants as it was on the source tenant.
• While we provide backwards compatibility, we cannot ensure that data broker can send data to Cumulocity IoT tenants which run on earlier Cumulocity IoT 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

Click Data connectors in the navigator to see a list of all currently defined data connectors with their status.

For each data connector, the following information is provided:

• the data connector’s name
• its destination tenant
• the status of the connector
• the number of filters set for the data connector

Use the toggle to enable and disable data forwarding to the destination tenant. If data is being forwarded, the toggle reads “Active”. If data is not being forwarded, the toggle reads “Suspended” or “Pending”. “Suspended” means that you have disabled forwarding. “Pending” means that the destination tenant has disabled forwarding.

Info: If the source tenant has been suspended all its data broker connectors will be suspended as well.

To add a data connector

1. Click Add data connector in the top menu bar.

2. In the Settings tab, provide the following information to create a new data connector:

   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.

3. Click Add filter to configure a new filter.

   

4. Each data filter contains the following information:

   Field	Description
   Group or device	The group or device that is forwarded. If you select a group here all sub-groups and sub-devices of this group will be forwarded. See the warning below on the usage of All objects.
   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.

   5. Click Save to save the configuration.

   Warning on the usage of All objects

   The option All Objects is left in the UI to ensure backward compatibility with older versions. We intend to deprecate it and we strongly recommend to not use this option.

   When selected, Cumulocity IoT will synchronize all types of objects, system as well as user-defined, and might override, or create out of context, objects in the destination tenant. Such objects may contain references to other objects and also configuration information. It is the user’s responsibility to check and ensure consistency of such information in the transferred objects in the target environment.

   This concerns items such as Smartrest templates, device protocols, smart rule configurations and dashboards.

   For example, when you create a smart rule on the source tenant and you synchronize all objects, then the data broker creates a smart rule managed object on the destination tenant. The rule itself is not copied, because a synchronized smart rule would perform the same action on the same device for the same configuration. That would create duplicate emails for the same recipients when an alarm occurs.

   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.

   Updates of the operation status coming from the source tenant 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

   After saving the configuration, 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 click the copy icon next to the security code to copy the code to your clipboard.

   

   To edit a data connector

   Click the menu icon at the right of a data connector entry and then click Edit.

   In the Settings tab, edit the data connector configuration.

   See To add a data connector for details on the settings.

   To duplicate a data connector

   Click the menu icon at the right of a data connector entry and then click Duplicate to create another data connector with the same configuration.

   To delete a data connector

   Click the menu icon at the right of a data connector entry and then click Delete to stop data forwarding and delete the data connector.

   To view alarms for a data connector

   Open a data connector and switch to the Alarms tab to display current alarms for the data connector.

   

   For details on alarms, see Device Management > Monitoring and controlling devices > Working with alarms.

   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.

   

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

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

   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 use the toggle in the card to temporarily stop forwarding data into your tenant.

   You can now navigate to the Device Management application or the Cockpit application. You will find 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.

   

   To delete a data connector

   Click the menu icon and then click Delete to stop data forwarding and delete the data connector.

   Troubleshooting

   On the source tenant, data broker queues data that cannot be forwarded immediately to the destination tenant. The amount of data that can be queued is limited. If Cumulocity IoT cannot queue any further data, the oldest queued data is dropped. In this case, an alarm is raised in the tenant.

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

   To reduce the number of alarms, alarms are not triggered more often than once per minute.

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

Info: The storage quota feature needs to be defined on the tenant and cannot be enabled/disabled by configuration.

Example

Let us assume that a tenant has a storage quota of 10 GB. 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 13 GB. An email is sent to all tenant administrators.

• Day 2: the total storage is still at 13 GB. 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.8 GB.

Managing storage quota warning email

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

The tenant administrators can set a user group (global role) and threshold for an email 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 email to the “admin” role when the storage reaches 80% of maximum storage.

The email warning can also be disabled.

License management

The management tenant may manage the licenses for the domains of the enterprise tenants via the UI.

To add and validate a domain license

1. Log into the management tenant.
2. Navigate to the License management page under the Settings menu. In the License management page all domain licenses are listed, together with their status (green checkmark = valid).
3. Paste the license key into the Add tenant license field and click Add.

The license will be validated and added to the tenants options.

To delete a domain license

1. Log into the management tenant.
2. Navigate to the License management page under the Settings menu.
3. Click the menu icon at the right if the domain for which you want to delete the license and then click Delete.