# Customization and permissions

Source: https://cumulocity.com/docs/streaming-analytics/analytics-customization/
Sector: Analytics
Release: Latest
Description: Configure request concurrency, application access, the home screen, Notifications 2.0, and microservice permissions for Streaming Analytics.

## Optimizing requests with concurrent connections

In order to provide better performance for requests to the Cumulocity 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 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 with concurrent connections](https://cumulocity.com/apama/docs/latest/standard-connectivity-plugins/the-cumulocity-iot-transport-connectivity-plug-in/#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.


> **Info:**
> This does not apply to the Apama-ctrl-smartrules, Apama-ctrl-smartrulesmt, and Apama-ctrl-mt microservices. They have a fix value of 1 (that is, fully serial) for this option, which is not configurable.

## 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](https://cumulocity.com/docs/streaming-analytics/analytics-customization/#customize-home-screen).

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 microservice is running, the **Analytics Builder** page is shown for all subscribed tenants. The **EPL Apps** page is shown 
on the tenant that owns the microservice, but not shown (and cannot be enabled) on the subtenants.
- 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 by an Enterprise tenant or Management tenant (see also [Managing tenants](https://cumulocity.com/docs/enterprise-tenant/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", 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,
see also [Managing permissions and roles](https://cumulocity.com/docs/standard-tenant/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](https://cumulocity.com/api/core/#tag/Tenant-API) in the Cumulocity 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](https://cumulocity.com/docs/streaming-analytics/epl-apps/#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 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](https://cumulocity.com/docs/standard-tenant/ecosystem/#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.

## Configuration requirements for Notifications 2.0

Streaming Analytics can use the Cumulocity Notifications 2.0 reliable data forwarding capability to receive notifications for measurements, events, alarms, managed objects and operations that are processed by the Cumulocity platform. For more information, see [About Notifications 2.0](https://cumulocity.com/api/core/#tag/About-notifications-2.0) in the Cumulocity OpenAPI Specification.

The availability of this feature is governed by two feature flags:

- `notification2.streaming-analytics` <br>
    The Cumulocity Notifications 2.0 feature is currently in Private Preview. If you want to have it enabled for your tenant, you must contact [product support](https://cumulocity.com/docs/additional-resources/contacting-support/) to set this feature flag.

- `streaming-analytics.messaging` <br>
    In addition to this, if you are using one of the variants of the Apama-ctrl microservice, you must also set this feature flag. You then need to resubscribe the Apama-ctrl microservice to pick up changes to the feature flag.
    Use the feature toggles REST API to do so; see [Feature toggles API](https://cumulocity.com/api/core/#tag/Feature-toggles-API) in the Cumulocity OpenAPI Specification.
    <!-- For further information on these feature flags and on feature flags in general, see (TODO: this doc has not yet been written). -->

If you are using a custom microservice, you must also add the `ROLE_NOTIFICATION_2_ADMIN` permission to the microservice manifest once the `notification2.streaming-analytics` feature flag has been activated; see also [Required settings in the microservice manifest](https://cumulocity.com/docs/streaming-analytics/epl-apps/#required-settings-in-the-microservice-manifest).
For the Apama-ctrl microservices, it is not required to add this permission manually as it is set as the default; see also [Modifying microservice permissions and resource usage](https://cumulocity.com/docs/streaming-analytics/analytics-customization/#microservice-permissions).


> **Info:**
> Keep in mind that you must also resubscribe the microservice to pick up changes to the feature flag.

## 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](https://cumulocity.com/docs/microservice-sdk/general-aspects/#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 microservice to Cumulocity 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
- ROLE_NOTIFICATION_2_ADMIN

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