Managing the ecosystem

Managing applications

There are two types of availability for applications:

• Subscribed - applications subscribed to the tenant, either provided by the platform (as default applications) or by a service provider.
• Custom - applications owned by the tenant. You can add custom applications in various ways as own applications.

Your applications are available through the application switcher in the top bar.

To view applications

Click Applications in the Ecosystem menu in the navigator to display a list or grid of all applications in your account.

In the Applications tab, you can see all applications available in your tenant.

Applications can be filtered by name or by availability.

To edit an application

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

In the Properties tab, several fields can be modified, depending on the application type (see Application properties).

To delete an application

Click the menu icon at the right of an entry and then click Delete. You can also delete an application directly from the Properties tab in the application details.

If you delete an application that overwrites a subscribed application, the currently subscribed application becomes available to all users. Additionally, the users will then also benefit from future upgrades of the subscribed application.

It is not possible to delete subscribed applications. This can only be done by the owner of the subscribed application.

Features

Features are applications which are built-in and not represented by an explicit artifact (like microservices or web applications).

In the Features tab, you will find a list of all features subscribed in your tenant. In an Enterprise tenant, the following features are available by default:

Other features may show up, depending on the individual subscriptions of your tenant.

Subscribed applications

Cumulocity IoT provides a variety of applications for different purposes. Depending on your installation and/or optional services your tenant will show a selection of the potentially available applications.

Below all applications are listed which are by default available in the Standard tenant or Enterprise tenant. In addition, numerous optional applications might be subscribed to your tenant.

Applications subscribed by default

Custom applications

Custom applications may be:

• Web-based UI applications, either deployed as standalone applications or as plugins deployed into a specific application (for example, a widget to the Cockpit dashboard).
• Links to an application running elsewhere.
• Duplicates of subscribed applications (in order to be able to customize them).

Click Add application at the top right of the Applications tab to add a custom application.

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

• Upload web application - drop a ZIP file or browse for it in your file system.
• External application - link to an application running elsewhere.
• Install from available packages - select a package blueprint.
• Duplicate existing application - create a copy of an existing application.

To upload a web application

1. Click Add application at the top right of the Applications tab.
2. Select Upload web application.
3. In the resulting dialog box, drop a ZIP file or browse for it in your file system.

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

To link to an external application

1. Click Add application at the top right of the Applications tab.
2. Select External application.
3. In the resulting dialog box, enter the name of the application. The name will be shown as title of the application.
4. Enter an application key, used to identify this application.
5. Enter the external URL where the application can be reached.
6. Click Save to create the application.

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

To install an application from a blueprint

1. Click Add application at the top right of the Applications tab.
2. Select Install from available packages.
3. Select the desired package.
4. In the resulting dialog box, enter the name of the application. The name will be shown as title of the application.
5. Enter an application key, used to identify this application.
6. Enter the path where the application can be reached.
7. Click Save to create the application.

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

To duplicate an application

Duplicating an application might be useful if you want to customize a subscribed application according to your needs. Duplicating a subscribed application creates a copy of the application as an own application, with a link to the original application.

1. Click Add application at the top right of the Applications tab.
2. In the upcoming dialog, select Duplicate existing application.
3. Select the desired application from the dropdown list, for example “Cockpit”.
4. In the next window, provide a name for the application, an application key to identify the application, and a path as part of the URL to invoke the application. Finally select an icon for the new application from the available icons. Per default, the values of the original application are provided, extended by a number. If you set the path to the path of the original subscribed application, your own application will overrule the subscribed application.
   Info

   The platform restricts the use of the prefix “feature-” in the Name field. You cannot create applications using this prefix in the application name. This also applies to existing applications in cases where the duplicate application feature is used.
5. Finally, click Duplicate to create the application.

Info

In case the application has been subscribed to the tenant, there is an additional toggle Overrule subscribed application. If you turn this toggle on, the values for name, key and path will be inherited from the original application and your duplicated application will overrule the subscribed application. Turn it off, to modify the values.

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

Application properties

To display further details on an application, click it to open its Properties tab.

In the Properties tab, each application will show the following information, depending on the application type (hosted or external):

Extensions

Extensions

Extension packages are combinations of plugins and blueprints which can be packed together into a single file and then be deployed to the platform. Thus, they offer better shareability and reusability of UI features across different applications and allow to add UI features to applications without coding knowledge.

Extension packages can contain two types of content:

• Plugins can be used to extend existing applications without the need of re-building the application.
• Blueprints are combinations of multiple UI functionalities which can be hosted by the platform and can be used to create a new application from scratch.

Blueprint applications must be deployed, while plugins are added to other applications. This allows you to scaffold entire solutions or to extend existing ones. Due to the micro frontend technology, this can happen at runtime without rebuilding.

Packages can be located on the Extensions page.

Packages can be filtered by name, creator type, availability and type of content.

To add a new extension package click Add extension package at the top right.

By clicking on a package, you can see the package details such as Extension package overview which includes a description and images as well as some meta information which is taken from the package.json.

Additionally, it is possible to view all available plugins within the selected package at the right. To install a plugin click Install plugin and select the desired application.

In the Versions tab, you see all previously uploaded binaries related to the current package. The binaries displayed on this tab can be downloaded via the context menu next to each package version entry.

You can select or upload different versions. Versions indicate the state of the package. They can be used to verify whether a certain package is outdated and must be updated. By clicking on a version additional information is provided such as package contents, applications or plugins. Tags can be used to give versions meaningful names. The “latest” tag is used to indicate the default version which will be selected in case no tag is provided. The “latest” tag is set by default to the latest version whenever a version is uploaded without a given tag.

To switch to a different version open the context menu for the desired version and click Set as latest. To delete a version click Delete.

Plugins

Switch to the Plugins tab of an application to view all plugins installed on an application.

In the Plugins tab you can add and remove plugins. Additionally, you can install plugins to an application.

Uploading archives

For custom applications, multiple file versions can be stored in Cumulocity IoT when they were created by uploading either a ZIP file or a MON file. Each version is called an archive. You can upload different versions at the same time and switch between these versions.

To upload an archive

1. Open the application properties for the respective application by clicking on it.
2. Click the plus button at the bottom of the Activity log section and browse for the archive in your file system or simply drop the archive file.
3. Click Upload to upload the archive to your Cumulocity IoT account.

Once uploaded, the recently uploaded version is automatically the active version, that is the version of the application that is currently being served to the users of your account. This version cannot be deleted.

To restore an older application version

Users can restore previous versions of an application from an archive.

1. Open the application properties for the respective application by clicking on it.
2. In the Activity log section, open the context menu for the desired version by clicking the menu icon and select Set as active to make it the active version.

To reactivate a single application

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

1. Open the application properties for the respective application by clicking on it.
2. In the Activity log section, open the context menu for the desired version by clicking the menu icon and select Reactivate archive.

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

Managing microservices

Click Microservices in the Ecosystem menu in the navigator to display a list or grid of all microservices subscribed to your account.

Microservices can be filtered by name and availability.

A microservice is a specific type of application, that is a server-side application used to develop further functionality on top of Cumulocity IoT. As web applications, microservices can either be subscribed to your tenant by the platform or by a service provider, or they can be owned by you as custom applications, see Custom microservices.

Subscribed microservices

Cumulocity IoT provides a variety of microservice applications for different purposes. Depending on your installation and/or optional services your tenant will show a selection of the potentially available applications.

Below you find a list of all microservices which are by default subscribed in a Standard tenant and/or Enterprise tenant. In addition, numerous optional microservices might be subscribed to your tenant.

Microservices subscribed by default

Custom microservices

To add a microservice as custom application

1. Click Add microservice at the top right.
2. In the resulting dialog box, drop a ZIP file or browse for it in your file system. Note that the size limit of the file to be uploaded is 500 MB.
3. The microservice application is created once the ZIP file has been successfully uploaded.

Microservice properties

To display further details on a microservice, click it to open its Properties tab.

In the Properties tab, each microservice will show the following information:

Below, you will additionally find information on the microservice version, as well as on its isolation level and billing mode, see Microservice usage for details on these parameters.

Microservice subscription

At the top right of the Properties tab, you find a toggle to subscribe to or unsubcribe from a microservice.

Changing the subscription is only possible for custom microservices, that is microservices being owned by you.

Microservice permissions

In the Permissions tab you can view the permissions required for the respective microservice, and the roles provided for it.

Monitoring microservices

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

Status information

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

To view the status you need the following permissions: role Application management READ and role Inventory READ.

The following information is provided on the Status tab:

• Instances - number of active, unhealthy and desired microservice instances for the current tenant.
• Subscriptions - number of active, unhealthy and desired microservice instances for all subtenants subscribed to the microservice.
• Alarms - alarms for given application, provided in realtime.
• Events - events for given application, provided in realtime.
• Smart rules - list of applicable smart rules.

Alarms and events

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

There are two user-friendly alarm types:

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

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

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

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

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

Log files

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

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

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

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

At the top right, additional functionality is provided:

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

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

At the bottom right you find navigation buttons:

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

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