Customization and permissions

Optimizing requests with concurrent connections

In order to provide better performance for requests to the Cumulocity IoT platform, Streaming Analytics uses multiple client connections to perform requests concurrently. This can provide improved performance, but may also change the ordering in which requests are executed and responses are returned. By default, the Cumulocity IoT transport tries to use multiple connections and restricts ordering to avoid races that may affect your EPL application.

An attempt is made to ensure order is maintained when required. For example, all updates to a single managed object are performed serially in the order they were sent to the transport. For more details see Optimizing requests to Cumulocity IoT with concurrent connections in the Apama documentation.

You can adjust the default number of client connections with the client.numClients tenant option in the streaminganalytics category. For example:

{
   "category": "streaminganalytics",
   "key": "client.numClients",
   "value": "5"
}

If you require a fully serial transport, set the value of client.numClients to 1.

Controlling access to the Streaming Analytics application

By default, the Streaming Analytics application gives you access to the Analytics Builder and EPL Apps pages. Administrators may wish to control which of these are shown on different tenants or for different users, or modify the wording of the cards on the home screen, see also Customizing the home screen of the Streaming Analytics application.

Which pages are available also depends on the variant of the Apama-ctrl microservice that is running.

• If the microservice is not running, an error message is shown indicating that the microservice cannot be accessed, and only a card with information about smart rules is shown on the home screen.
• If the Apama-ctrl-starter microservice is running, the EPL Apps page is not shown (and cannot be enabled) as the EPL apps functionality is not available in Apama-ctrl-starter.
• If the Apama-ctrl-mt-4c-16g microservice is running, the Analytics Builder page is not shown (and cannot be enabled). In this case, only the EPL Apps page is shown.
• If the Apama-ctrl-smartrules or Apama-ctrl-smartrulesmt microservice is running, neither the Analytics Builder nor the EPL Apps page is shown (and cannot be enabled). In this case, only the card with information about smart rules is shown on the home screen.
• For other variants of the Apama-ctrl microservice, both the Analytics Builder and EPL Apps pages are shown by default.

For an entire tenant, if a “feature application” named feature-disable-analyticsbuilder and/or feature-disable-eplapps is available within the tenant, then the relevant part is disabled. This can be done either within a tenant or by an Enterprise tenant or Management tenant (see also Managing tenants) and then subscribing to subtenants (the subtenant administrators are then not able to unsubscribe this application if the parent tenant wishes to restrict access to the functionality). To create such a “feature application” within a tenant, send a POST request to /application/applications (as an administrator with the permission to create applications). For example, to disable Analytics Builder:

{
   "name":"feature-disable-analyticsbuilder",
   "contextPath": "feature-disable-analyticsbuilder",
   "type":"HOSTED",
   "resourcesUrl":"/",
   "manifest": {
       "noAppSwitcher": true
   },
   "key":"feature-disable-analyticsbuilder-key"
}

Or to disable EPL Apps:

{
   "name":"feature-disable-eplapps",
   "contextPath": "feature-disable-eplapps",
   "type":"HOSTED",
   "resourcesUrl":"/",
   "manifest": {
       "noAppSwitcher": true
   },
   "key":"feature-disable-eplapps-key"
}

You can also send the POST request using a curl command, for example, to disable Analytics Builder:

curl --user username -X POST -H 'Content-Type: application/json' -d '{"name":"feature-disable-analyticsbuilder", "contextPath": "feature-disable-analyticsbuilder", "type":"HOSTED", "resourcesUrl":"/","manifest": {"noAppSwitcher": true},"key":"feature-disable-analyticsbuilder-key"}' -k https://{{hostname}}/application/applications/

Or to disable EPL Apps:

curl --user username -X POST -H 'Content-Type: application/json' -d '{"name":"feature-disable-eplapps", "contextPath": "feature-disable-eplapps", "type":"HOSTED", "resourcesUrl":"/", "manifest": {"noAppSwitcher": true},"key":"feature-disable-eplapps-key"}' -k https://{{hostname}}/application/applications/

By default, all users can see the same set of pages (according to the limitations above). You can also restrict the visibility of the pages to only users who have the permission ROLE_ANALYTICSBUILDER_READ or ROLE_EPLAPPS_READ, which can be assigned directly to users or via groups, see also Managing permissions. To enable this, set the category of the tenant option to streaminganalytics and the applicationAccess key to the value “role”, see the Tenant API in the Cumulocity IoT OpenAPI Specification, or use a curl command as given in the example below:

curl --user username -X POST -H 'Content-Type: application/json' -d '{"category": "streaminganalytics", "key": "applicationAccess", "value": "role"}' -k https://mytenant/tenant/options

You must replace the username with the name of a user who has ADMIN permission for “Option management”.

Note that this only affects the visibility of the cards and pages in the Streaming Analytics application. The supported REST services only require READ and ADMIN permissions for “CEP management”.

Customizing the home screen of the Streaming Analytics application

The cards that are shown on the home screen of the Streaming Analytics application contain text and links which you can customize on a per-tenant and per-language basis. To do this, download the documentation.json file for the language you wish to customize from the URL /service/cep/apamacorrelator/EN/documentation.json (this must be authenticated for a user in the Cumulocity IoT tenant). Replace the “EN” within the URL with the language code for the file you want to download.

The documentation.json file includes the URLs for the documentation links across the Streaming Analytics application and the text that is shown on the home screen. You can modify this to your requirements.

After you have made all required changes, package the modified copies into a ZIP file containing the following files:

• files/support/cumulocity/EN/documentation.json
• cumulocity.json

The cumulocity.json file contains the following:

{
   "contextPath": "streaminganalytics-customization",
   "availability": "MARKET",
   "type": "HOSTED",
   "name": "streaminganalytics-customization",
   "key": "streaminganalytics-customization-key",
   "noAppSwitcher": true
}

Then upload the ZIP file using the Administration application: go to Ecosystem > Applications, click Add application, and select the method Upload web application. See Managing applications for detailed information.

You may need to clear your browser cache for the changes to take effect.

You can include multiple languages in a single ZIP file as needed. You can subscribe this to subtenants as needed from an Enterprise tenant.

On new releases of the platform, it is recommended that you review the source documentation.json file for any changes. New entries in this file will be picked up with their default values.

Modifying microservice permissions and resource usage

The resource usage and permissions that the Apama-ctrl microservice operates with are defined in the manifest file of the Apama-ctrl microservice. See Microservice manifest for more information.

If you have access to the microservice image (typically available only to operations), then you are able to extract the microservice image, modify the manifest, rebuild the microservice, and reupload the microservive to Cumulocity IoT as an application in the Administration application.

The manifest specifies CPU and memory resource usage. In some circumstances, these must be changed (different sizes of the microservice image are provided with different configurations).

The manifest also specifies the permissions with which the microservice runs. This is the set of permissions that every request from EPL (or any other code running in the Apama-ctrl microservice) runs with. The Apama-ctrl microservice itself requires the following permissions:

• ROLE_APPLICATION_MANAGEMENT_READ
• ROLE_INVENTORY_READ
• ROLE_INVENTORY_ADMIN
• ROLE_INVENTORY_CREATE
• ROLE_MEASUREMENT_READ
• ROLE_MEASUREMENT_ADMIN
• ROLE_EVENT_READ
• ROLE_EVENT_ADMIN
• ROLE_ALARM_READ
• ROLE_ALARM_ADMIN
• ROLE_DEVICE_CONTROL_READ
• ROLE_DEVICE_CONTROL_ADMIN
• ROLE_IDENTITY_READ
• ROLE_IDENTITY_ADMIN
• ROLE_CEP_MANAGEMENT_READ
• ROLE_CEP_MANAGEMENT_ADMIN
• ROLE_OPTION_MANAGEMENT_READ
• ROLE_SMS_ADMIN
• ROLE_AUDIT_ADMIN
• ROLE_AUDIT_READ
• ROLE_USER_MANAGEMENT_READ
• ROLE_USER_MANAGEMENT_OWN_READ
• ROLE_TENANT_MANAGEMENT_READ
• ROLE_BULK_OPERATION_ADMIN
• ROLE_BULK_OPERATION_READ

You can add other roles to this list (or remove them from it) to grant (or remove) permissions to EPL code.