map.apps integration

Upload Analytics bundles with map.apps

In order to use the bundles of service.monitor Analytics they need to be installed in map.apps. To install the bundles follow these steps:

  1. Login to the map.apps Manager as Admin user

  2. Go to the Bundles tab

  3. Above the list of already installed bundles click +

  4. Upload the bundles of service.monitor Analytics by selecting [CD-CONTENTS]/software/service.monitor Analytics web/ct-analytics-js-[VERSION].jar

After uploading, the service.monitor Analytics bundles are displayed in the list of installed bundles.

Configuration of map.apps

In order to use service.monitor Analytics to collect and display usage data of a map.apps installation, it is necessary to configure map.apps to integrate with the service.monitor Analytics webapp and the logging infrastructure. To achieve this, some properties need to be changed in the map.apps application.properties file, located at (map.apps) [data.directory.location]/application.properties

Note, that the map.apps data.directory.location is different from the service.monitor Analytics data.directory.location and is usually located at $\{user.home\}/.mapapps

After properties have been changed, the Servlet Container has to be restarted or the context has to be reloaded.

application.properties (map.apps)
#### service.monitor Integration
analytics.service.url=/monitor-analytics/resources/usage/log
analytics.message.src=map.apps
analytics.elasticsearch.url=/monitor-analytics/resources/elastic/forward
analytics.management.role=maAdmin
appservice.default.bundles=system,templatelayout,usagelog_restservice

##### Properties for map.apps 4
manager.3x.config.enabled=true
manager.3x.config.viewbundles=usagelog_monitorIntegration,usagelog_management,usagelog_questionsDashboardConfig
manager.3x.config.activetool=usagelog_management

servicemonitor.base.url=/monitor

Description of the configuration properties

analytics.service.url

http endpoint for collecting usage data by means of service.monitor Analytics webapp

Property status: new

Default: <host>/monitor-analytics/resources/usage/log

analytics.message.src

Name of the message’s source (for analyses purposes)

Property status: new

Default: map.apps

analytics.elasticsearch.url

http endpoint for querying log events. In order to gain access the logged data via Elasticsearch, it’s URL has to be set. It is possible to query Elasticsearch directly, but this ist not recommend. To secure the logged data, the service.monitor Analytics webapp should be used as a security layer.

Property status: new

Default: <host>/monitor-analytics/resources/elastic/forward

analytics.management.role

Dashboards are secured by the map.apps role system, so it has to be defined which role is allowed to see the dashboard tab. The following property has to be set.

Property status: new

Default: maAdmin

appservice.default.bundles

It is possible to enable the logging of usage data by default for all map.apps app. In oder to achieve this a list of bundles has to be defined in the application.properties of map.apps, which are loaded automatically with each app, even if they are not specified under the "allowedBundles" section in the app.json file. Adding the usagelog_restservice bundle to the application.properties will simplify the activation of service.monitor Analytics for several apps at once by adding a log service bundle to the appservice.default.bundles property.

If the property appservice.default.bundles was extended by the usagelog_restservice, all existing and newly created apps will send log statements to the defined service URL.

Property status: warning may already pre-exist

Default: system,templatelayout,usagelog_restservice

manager.3x.config.enabled

If you are using map.apps 4, dashboards will be displayed inside of the 3.x map.apps Manager configuration.

Property status: warning may already pre-exist

Default: true

manager.3x.config.viewbundles

If you are using map.apps 4, dashboards will be displayed inside of the 3.x map.apps Manager configuration.

Property status: warning may already pre-exist

Default:

"usagelog_management",
"usagelog_questionsDashboardConfig",
"usagelog_monitorIntegration"
manager.3x.config.activetool

If you are using map.apps 4, dashboards will be displayed inside of the 3.x map.apps Manager configuration.

Property status: warning may already pre-exist

Default: usagelog_management

servicemonitor.base.url

http endpoint for embedding /monitor webapp as part of map.apps Management view.

Property status: new

Default: <host>/monitor

If the map.apps is not running on the same host as the service.monitor Analytics Webapp please make sure that the host is added to the allowedProxyUrls in the map.apps application.properties file

When editing and saving an app via Live-Configuration in map.apps the bundles mentioned above will be added to the app.json file. Therefore removing the property from application.properties will not remove the bundles from those apps automatically.

Also note, that this property only applies to apps provided via the map.apps app service and will not apply to apps stored in the file system.

Enable usage logging app by app

When usage logging is not enabled globally on map.apps level, make sure that required bundles are added to the app’s app.json where logging should be enabled. At least one bundle is needed that provides a writer component (e.g the usagelog_restservice bundle).

app.json
{
  "load": {
    "allowedBundles": [
      ...
      "usagelog_restservice"
    ]
  }
  ...
}