Applications

Overview

The API below is not published in "/platform" but can be reached using "/application".

The application interface consists of the following parts:

  • The application API resource returns URIs and URI templates to collections of applications, so that all applications with a particular name and all applications owned by particular tenant can be queried.
  • The application collection resource retrieves sets of applications and enables creating new applications.
  • The application resource represents applications that can be queried and deleted.
  • The application bootstrap user resource retrieves bootstrap user credentials for microservice.
  • The current application resource provides data of authenticated microservice user's application.
  • The application user collection resource represents a collection of subscription entries.
  • The application user resource represents a single subscription entry.
  • The current application subscription provides an endpoint for accessing current application subscriptions.
  • The application binaries provides an endpoint for uploading a deployable microservice, web application or custom Apama rule to the platform.

Info: For all PUT/POST requests an accept header should be provided, otherwise an empty response body will be returned.

Application names

For each tenant, Cumulocity manages the subscribed applications. Cumulocity provides a number of applications of various types.

These are listed in the following table. The columns show the following information:

  • Application: Application name as visible in the Administration application.
  • Functionality: Brief description.
  • String: Identification of the application in the API. In case you want to subscribe a tenant to the application using an API (as described on this page), use this string in the argument (as name)
  • Application type: Technical type of the application. "Feature" refers to built-in applications subscriptions, i.e. these applications are not represented by an explicit artefact (microservice, web application or custom Apama rule).
  • Availablity: Only applications indicated as "Standard Edition" are available in all installations. Applications of type "microservice", "web application" or "custom Apama rule" indicated as "Optional service" require that the related artefact is installed for the respective Cumulocity instance. The same applies to applications listed as "Enterprise Edition".
Application Functionality String Application type Availability
Administration Lets account administrators manage users, roles, tenants and applications. administration Web application Standard Edition
Apama Define business operations for immediate processing of incoming data by using Apama's Event Processing Language (EPL). This is a per-tenant deployment. apama-small=
1 core; 4 GB RAM
apama-medium=
2 cores; 8 GB RAM
apama-large=
4 cores; 16 GB RAM
Microservice Optional service
Branding Customize the look of your tenants to your own preferences. branding Microservice Enterprise Edition
Cep Define business operations based on realtime data by using the Esper CEP engine. This CEP variant uses a shared instance for multiple tenants. See "Cep-small" for a per-tenant approach. cep Microservice Standard Edition
CEP custom rules Upload your own CEP rules created with Esper in a per-tenant deployment. You need to be subscribed to the application "Cep-small" to be able to use this feature. feature-cep-custom-rules Feature Optional service
Cep-small CEP variant. Lets you work with CEP rules based on Esper in a per-tenant deployment (as opposed to "Cep" which uses a shared instance). You need to be subscribed to "CEP custom rules" to upload your own Esper CEP rules. cep-small Microservice Optional service
Cockpit Manage and monitor IoT assets and data from a business perspective. cockpit Web application Standard Edition
Cloud Fieldbus Collect data from fieldbus devices and remotely manage them in Cumulocity. feature-fieldbus4 Feature Optional service
Cloud Remote Access Implements Virtual Network Computing (VNC) to remotely access operating panels and other devices via a web browser. cloud-remote-access Mircoservice Optional service
Data Broker Lets you share data selectively with other tenants. feature-broker Feature Enterprise Edition
Device Management Manage and monitor devices, and control and troubleshoot devices remotely. devicemanagement Web application Standard Edition
Device simulator Simulate all aspects of IoT devices. device-simulator Microservice Standard Edition
LoRa Actility Interface with LoRa devices through Actility's ThingPark Wireless. actility-device-provider-agent Microservice Optional service
LWM2M agent Interface with LWM2M devices. lwm2m-agent Microservice Optional service
Microservice hosting Host your own microservices on top of Cumulocity. feature-microservice-hosting Feature Optional service
Nokia IMPACT agent With the Nokia IMPACT agent you can interface with heterogeneous devices through the Nokia IMPACT Data Collector. impact Microservice Optional service
Sigfox With the Sigfox agent you can interface with Sigfox devices through the Sigfox cloud. Requires the following application: "feature-fieldbus4" sigfox-agent Microservice Optional service
Smart Rules Use the Smart Rule engine and create smart rules to perform actions based on realtime data. Requires one of the following applications: "Cep", "Apama" smartrule Microservice Standard Edition
SSL management Activate your own custom domain name by using a SSL certificate. sslmanagement Microservice Enterprise Edition
Tenant SLA Monitoring Lets service providers monitor the availability and response time of tenants and sub-tenants. tenant-sla-monitoring Microservice Optional service
User hierarchies Reflect independent organizational entities in Cumulocity that share the same database. feature-user-hierarchy Feature Enterprise Edition

Application API

ApplicationAPI [application/vnd.com.nsn.cumulocity.applicationApi+json]

Name Type Occurs Description
self URL 1 Link to this resource
applicationById Application/URI-Template 1 A reference to a resource of type Application (placeholder {id})
applications ApplicationCollection 1 Collection of all applications
applicationsByName ApplicationCollection URI-Template 1 Read-only collection of all applications with a particular name (placeholder {name})
applicationsByTenant ApplicationCollection URI-Template 1 Read-only collection of all applications subscribed by a particular tenant (placeholder {tenant})
applicationsByOwner ApplicationCollection URI-Template 1 Read-only collection of all applications owned by a particular tenant (placeholder {tenant})

GET the Application API resource

Response body: ApplicationApi

Required role: ROLE_Application_READ

Example request:

GET /application
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.ApplicationApi+json;ver=...
Content-Length: ...
{
    "self" : "<<ApplicationAPI URL>>",
    "applicationsByID" : "<<ApplicationCollection URL>>/{id}",
    "applications" : "<<ApplicationCollection URL>>",
    "applicationsByName" : "<<ApplicationAPI URL>>/applicationByName/{name}",
    "applicationsByOwner" : "<<ApplicationAPI URL>>/applicationsByOwner/{tenantName}",
    "applicationsByTenant" : "<<ApplicationAPI URL>>/applicationsByTenant/{tenantName}"
}

Application collection

ApplicationCollection [application/vnd.com.nsn.cumulocity.applicationCollection+json]

Name Type Occurs Description
self URI 1 Link to this resource
applications Application 0..n List of applications, see below
statistics PagingStatistics 1 Information about paging statistics
prev URI 0..1 Link to a potential previous page of applications
next URI 0..1 Link to a potential next page of applications

GET an application collection

Response body: ApplicationCollection

Required role: ROLE_APPLICATION_MANAGEMENT_READ

Example request:

GET /application/applications
Host: ...
Authorization: Basic ...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationCollection+json;ver=...
Content-Length: ...
{
    "self" : "...",
    "next" : "...",
    "prev" : "...",
    "applications": [
        {
            "availability": "PRIVATE",
            "id": "101",
            "key": "...",
            "name": "myOwnApplcation",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "test"
                }
            },
            "self": "...",
            "type": "HOSTED",
            "contextPath": "/my_own_application",
            "resourcesUrl":"...",
            "resourcesUsername": "...",
            "resourcesPassword": "..."
        },
        {
            "availability": "MARKET",
            "id": "3",
            "key": "...",
            "name": "energyapp",
            "owner": {
                "self": "...",
                "tenant": {
                    "id": "management"
                }
            },
            "self": "...",
            "type": "EXTERNAL",
            "externalUrl": "..."

        }
    ],
    "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
    }
}

POST - create a new application

Request body: Application

Response body: Application

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN.

Example request:

POST /application/applications
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...

{
  "key": "vehicleControlApplicationSecretKey",
  "name": "vehicleControlApplication",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourcesUrl":"http://external.host.com/basedir"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
Location: <<URL of new application>>

{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiCorp"
      }
  },
  "self": "...",
  "type": "HOSTED",
  "contextPath": "/vehicleControlApplication",
  "resourceUrl":"http://external.host.com/basedir",
  "resourcesUsername": "..."
}

Application

Application [application/vnd.com.nsn.cumulocity.application+json;ver=0.9]

Field Name Type Occurs Description PUT/POST
self URL 1 Link to this resource No
id String 1 Unique identifier for the application No
name String 1 Name of application POST: Mandatory PUT: Optional
key String 1 Shared secret of application POST: Mandatory PUT: Optional
type String 1 Type of application. Possible values are : EXTERNAL, HOSTED, MICROSERVICE, APAMA_CEP_RULE POST: Mandatory PUT: No
availability String 0..1 Access level for other tenants. Possible values are : MARKET, PRIVATE (default) Optional
owner TenantReference 1 Reference to the tenant owning this application No
contextPath String 0..1 contextPath of the hosted application POST: Mandatory (when application type is HOSTED) PUT: Optional
resourcesUrl String 0..1 URL to application base directory hosted on an external server POST: Mandatory (when application type is HOSTED) PUT: Optional
resourcesUsername String 0..1 authorization username to access resourcesUrl Optional
resourcesPassword String 0..1 authorization password to access resourcesUrl Optional
externalUrl String 0..1 URL to the external application POST: Mandatory (when application type is EXTERNAL) PUT: Optional

POST - copy an application

A POST request to the "clone" resource creates a new application based on an already existing one.

The properties are copied to the newly created application. For name, key and context path a "clone" prefix is added in order to be unique.

If the target application is hosted and has an active version, the new application will have the active version with the same content.

The response contains a representation of the newly created application.

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN

Example request:

POST /application/applications/<<application_id>>/clone HTTP/1.1
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json

Example response:

HTTP/1.1 201 Created
Location: .../application/applications/{{application_id}}
Content-Type: application/vnd.com.nsn.cumulocity.application+json; charset=UTF-8; ver=0.9

{
    "activeVersionId": "10414",
    "availability": "MARKET",
    "contextPath": "clonetest",
    "id": "1115",
    "key": "clonesecretKeyForTheApplication",
    "manifest": {},
    "name": "clonetestApplicationName",
    "owner": {
        "self": ".../tenant/tenants/management",
        "tenant": {
            "id": "management"
        }
    },
    "resourcesUrl": "/test",
    "self": ".../application/applications/1115",
    "type": "HOSTED"
}

PUT - update an application

Request body: Application

Response body: Application (if "ACCEPT" header is specified).

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN

Example request:

PUT /application/applications/<<applicationId>>
Host: ...
Authorization: Basic ...
Content-Length: ...
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
  "availability" : "MARKET"
}

GET an application

Response body: Application

Required role: ROLE_APPLICATION_MANAGEMENT_READ

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "EXTERNAL",
  "externalUrl":"http://external.host.com/application"
}

DELETE an application

Request Body: n/a

Response Body: n/a

Required role: ROLE_APPLICATION_MANAGMENT_ADMIN and owner

Info: The application can only be removed when its availability is PRIVATE or in other case when it has no subscriptions.

Example Request: Delete an application

DELETE /application/applications/<<applicationId>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

Example Response:

HTTP/1.1  204 NO CONTENT

Bootstrap user

GET bootstrap user

Response body: ApplicationUser

Required role: ROLE_APPLICATION_MANAGEMENT_ADMIN

Example request:

GET /application/applications/{microservice-applicationId}/bootstrapUser
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.user+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.user+json;ver=...
Content-Length: ...
{
    "name": "servicebootstrap_hello-world",
    "password": "9HqBc0miL5",
    "tenant": "dariusz"
}

Current application

GET current application

Response body: Application

Required authentication with bootstrap user

Example request:

GET /application/currentApplication
Host: ...
Authorization: Basic .....
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "vehicleControlApplication",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "taxiDrive"
      }
  },
  "self": "...",
  "type": "MICROSERVICE",
  "externalUrl":"http://external.host.com/application"
}

PUT - update current application

Response body: Application

Required authentication with bootstrap user

Example request:

PUT /application/currentApplication
Host: ...
Authorization: Basic ...
Accept: application/vnd.com.nsn.cumulocity.application+json;ver=...
{
      "availability": "PRIVATE",
      "id": "105",
      "key": "...",
      "name": "vehicleControlApplication",
      "owner": {
          "self": "...",
          "tenant": {
              "id": "taxiDrive"
          }
      },
      "self": "...",
      "type": "MICROSERVICE",
      "externalUrl":"http://external.host.com/application"
    }

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.application+json;ver=...
Content-Length: ...
{
  "availability": "PRIVATE",
  "id": "105",
  "key": "...",
  "name": "...",
  "owner": {
      "self": "...",
      "tenant": {
          "id": "..."
      }
  },
  "self": "...",
  "type": "MICROSERVICE"
}

ApplicationSubscriptionCollection

ApplicationSubscriptionCollection[application/vnd.com.nsn.cumulocity.applicationUserCollection+json]

Name Type Occurs Description
self URI 1 Link to this resource
users ApplicationUser 0..n List of subscribed users, see below
statistics PagingStatistics 1 Information about paging statistics
prev URI 0..1 Link to a potential previous page of applications
next URI 0..1 Link to a potential next page of applications

ApplicationUser

Field Name Type Occurs Description
tenant String 1 Subscription tenant
name String 1 Username
password String 1 Password

GET current application subscriptions

Response body: ApplicationSubscriptionCollection

Required authentication with bootstrap user

Example request:

GET /application/currentApplication/subscriptions
Host: ...
Authorization: Basic ....
Accept: application/vnd.com.nsn.cumulocity.applicationUserCollection+json; ver=...

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.com.nsn.cumulocity.applicationUserCollection+json; ver=...
Content-Length: ...
{
    "users": [
        {
            "name": "service_hello-world",
            "password": "...",
            "tenant": "..."
        }
    ]
}

Application binaries

POST - upload application binary

For the applications of type "microservice", "web application" and "custom Apama rule" to be available for Cumulocity platform users, a binary zip file must be uploaded.

 POST /application/applications/{APPLICATION_ID}/binaries
 Host: ...
 Authorization: Basic …
 Content-Type: multipart/form-data

For the microservice application, the zip file must consist of:

  • cumulocity.json - file describing the deployment
  • image.tar - executable docker image

For the web application, the zip file must include index.html in the root directory.

For the custom Apama rule application, the zip file must consist of a single .mon file.