Manage Cumulocity Streaming Analytics from the Command Line

Knowledge Base
, ,
1

The Cumulocity CLI is a comprehensive tool to interact with Cumulocity from the command line. Among other things, you can use it to manage devices, deploy applications and microservices or create items in Cumulocity from templates.

The Cumulocity CLI comes with an extension mechanism that allows you to easily add your own commands. This article describes a new Cumulocity CLI extension that adds commands to interact with Cumulocity Streaming Analytics.

The extension supports:

  • Managing Analytics Builder models
  • Managing EPL Apps
  • Managing the Streaming Analytics microservice
  • Managing Analytics Extensions

This extension provides several advantages for managing Streaming Analytics:

  • Automation: Automate repetitive tasks and bulk operations that would be time-consuming in the UI
  • CI/CD Integration: Seamlessly integrate analytics management into your continuous integration and deployment pipelines
  • Version Control: Store and version your analytics artifacts alongside your code in Git or other version control systems
  • Bulk Operations: Perform operations across multiple models or apps simultaneously using command piping
  • Scripting: Create powerful scripts to backup, migrate, or synchronize analytics artifacts across tenants
  • No UI Required: Manage analytics from the command line or automated scripts without manual UI interaction

Prerequisites

Before using this extension, ensure you have:

  • The Cumulocity CLI installed
  • Access to a Cumulocity tenant with Streaming Analytics enabled
  • Appropriate permissions to manage analytics artifacts (Analytics Builder models, EPL Apps, and extensions)

Installation

Once the prerequisites are met, you can install the extension by running:

c8y extension install Cumulocity-IoT/c8y-analytics

You can update the extension at a later point by running:

c8y extension update Cumulocity-IoT/c8y-analytics

You can delete it by running:

c8y extension delete Cumulocity-IoT/c8y-analytics

Usage Examples

A comprehensive list of supported commands can be found in the project’s README or by running with the help option on the command group or individual command level:

% c8y analytics --help                                                                                                                                                                                                     
analytics extension

Usage:
  c8y analytics [command]

Available Commands:
  ab            Analytics Builder
  configuration configuration
  epl           EPL Apps
  extensions    extensions
  instances     Analytics Builder Template instances
  management    management

Some simple commands are:

c8y analytics ab list
c8y analytics ab get --id OEE 
c8y analytics ab update --id OEE --state ACTIVE
c8y analytics ab delete --id OEE

These commands list all available Analytics Builder models, then get a specific model named OEE, then update it to be active, and finally delete it. Note that the extension supports autocomplete for various parameters like id (where you can also use the name) and state. Similar commands are available for EPL Apps, Analytics Builder template models, and Analytics Extensions.

The management and configuration commands provide control over the Streaming Analytics microservice. For example, you can get and set the tenant option to configure the reordering buffer:

c8y analytics configuration get --key analytics.builder/timedelay_secs
c8y analytics configuration update --key analytics.builder/timedelay_secs --value 10

Like the built-in commands of the Cumulocity CLI, the extension supports more complex use cases through pipes. For example, you can deactivate all EPL Apps using:

c8y analytics epl list | c8y analytics epl update --state inactive

To download all Analytics Builder models from a tenant:

c8y analytics ab list --select 'id,name' --output csv | while IFS=, read -r id name; do c8y analytics ab get -n --id $id --outputFileRaw $name.json > /dev/null; done

Summary

The Streaming Analytics extension for the Cumulocity CLI enables straightforward automation and management of various tasks. It can be used for one-off tasks or integrated into CI/CD pipelines for continuous automation.

We are already working on additional capabilities, and if you would like to contribute the project is available here:

The Streaming Analytics extension for the Cumulocity CLI is provided as-is and without warranty or support. It does not constitute part of the Cumulocity product suite. Users are free to use, fork and modify it, subject to the license agreement. While Cumulocity GmbH welcomes contributions, we cannot guarantee to include every contribution in the master project.

3 Likes
Extend Analytics Builder with custom blocks