Plugins reference

Overview

This section provides a reference for Device Integration Platform web applications. It first describes the folder structure of a Device Integration Platform web application. Then it specifies the content of the application manifest and the plugin manifest. Finally, it describes the services and extension points that the Device Integration Platform web application framework provides.

A detailed reference for the various JavaScript classes is on the JSDoc site. Most of the content of the manifest files corresponds to the application API properties, described in the REST reference. Examples of manifest files can be found in the examples.

Device Integration Platform web application folder structure

The default folder structure of a Device Integration Platform web application is as follows:

<<root folder>>
    cumulocity.json
    ...
    plugins
        <<plugin name>>
            cumulocity.json
            index.js
            icon.png
            controllers
            views
            services
            styles
            gallery
            images
            ...

Inside the root folder of your application, the so-called "application manifest" is stored in a file "cumulocity.json". The folder "plugins" contains one folder per plugin contributed by the application. The plugin folder name together with the application name uniquely identifies the plugin. Inside each plugin folder, the so-called "plugin manifest" is stored in another "cumulocity.json" file. The format of the application manifest and the plugin manifest is described below.

We suggest the following convention for the structure of plugins:

  • index.js: Entry point for the plugin, can define config() function for AngularJS module that wraps the plugin.
  • controllers: Contains files with AngularJS controllers used by the plugin.
  • views: Contains AngularJS view templates used by the plugin.
  • services: Contains custom services defined by the plugin,
  • styles: Contains stylesheets (plain CSS and LESS).
  • gallery: Contains plugin screenshots. These are used for the plugin gallery in the Device Integration Platform administration application.
  • images: Contains other images used by the plugin.

Application manifest

The application manifest describes where your application is stored and how it is exposed to Device Integration Platform. The following properties are available:

  • name: A descriptive name for the application.
  • availability: "PRIVATE", if the application is only available in your tenant, "MARKET", if it is a public application.
  • contextPath: The path to be used for hosted applications. The URL of the application will be "<<yourURL>>/apps/<<contextPath>>".
  • key: The application key that is used for associating requests of an application with the application and for subscribing to applications.
  • resourcesUrl: A URL pointing to the built application.
  • type: HOSTED, if the application is hosted through Device Integration Platform, EXTERNAL, if the application is hosted elsewhere.
  • imports: A list of plugins used by the application. List of <<applicationName>>/<<pluginName>>.
  • noAppSwitcher: If set to true, application will not appear in the App Switcher menu. Optional, use, for example, if the application only exposes plugins.

Note that "name", "contextPath" and "key" need to be unique. For "PRIVATE" applications, "name" and "contextPath" need to be only unique within your tenant.

Plugin manifest

The plugin manifest describes how your plugin is shown in the Device Integration Platform administration application (name, description, category, gallery, list) and what files need to be built and loaded in order to run the plugin (ngModules, js, imports, css, less, copy).

  • name: A descriptive name for the plugin, required.
  • description: A description of the plugin, optional.
  • category: A category for the plugin (see the "Category" drop-down in the administration application), optional.
  • gallery: A list of images with screenshots to use in the Device Integration Platform administration application, optional.
  • list: Determines whether the plugin should be listed in the Device Integration Platform administration application, optional.
  • ngModules: A list of AngularJS modules that are provided by plugin, at least one required.
  • js: A list of JavaScript files to be loaded, such as "index.js", controllers, services, asf. The path is relative to the plugin's root folder. Optional.
  • imports: A list of plugins that this plugin depends upon, in the form of <<applicationName>>/<<pluginName>>, optional.
  • css: A list of CSS files to be loaded, paths relative to plugin’s root folder, optional.
  • less: A list of LESS files to be loaded, paths relative to plugin’s root folder, optional.
  • copy: A list of files that should be copied into the built, optional.

Services and extension points

For more information on the JavaScript APIs, consult the JSDoc site. Services to access Device Integration Platform APIs are provided in the "core" package, extension points to, for example, add new menu items or widgets are provided in the "ui" package.