Configuring the Analytics app

The magnolia-analytics-ui submodule provides the Analytics app configuration, the demo dashboard you see in the app, and several preconfigured charts.

Demo dashboard

Analytics app light module

You can edit the configuration of the app and dashboards as part of a light module (YAML).

magnolia.resources.dir/
└── analytics-ui/
    ├── apps/
        └── analytics.yaml
    ├── dashboards
        └── demo.yaml
    └── i18n/
        └── magnolia-analytics-ui-messages_en.properties

You can configure what data is available and how it appears for the end users creating and using dashboards and widgets in the Analytics app.

Dashboard filters

Developers can define filters to drill down into the data displayed in the charts that are configured. When set, each filter is applied to all the charts in the dashboard simultaneously. For example, if you set a filter to display a given time range, all the charts display data for that time range.

You can use basic Magnolia field types to define filters, such as date, rich text, and so on.

Complex fields such as multiValue, composite, switchable, and collapsibleComposite aren’t supported.

The filter parameters depend on the type of data supplier used (see properties below).

Example

/analytics-ui/dashboards/demo.yaml
filterFields:
  - name: limitTopSearch
    $type: textField
    placeholder: number
    label: Limit of frequent search
  - name: numberOfTags
    $type: textField
    placeholder: number
    label: Number of content tags
  - name: startDate
    $type: dateField
    label: Start date
  - name: endDate
    $type: dateField
    label: End date

Properties

Property Description

filterFields

required

         name

required

The filter names are used to append the REST call against the supplier. Therefore, the value here must have a counterpart in the given data suppliers. You can also use filters to override parameters.

Filter parameters for each supplier:

         $type

required

Valid field alias name. See field types.

For example: $type: dateField

         label

required

A text label displayed as the title of the filter in the dashboard. For example Start date.

         placeholder

optional

Text to be displayed in the filter field when you don’t want the filter to appear empty.

         options

optional

Options to be applied to the filter contents. The sub-properties depend on the field type being used.

Using date filters

If you don’t set a value for the date parameter in the data supplier .yaml file (such as /matomo/dataSuppliers/demoMatomoSupplier.yaml), the dashboard display uses the default value (for Matomo: last7).

In the dashboard, if the filter startDate and endDate are left empty by the user, the date parameter value from the data supplier .yaml file is used in widgets for that data supplier.

If the user enters a startDate and endDate in the filter, the date value range selected is used in widgets for that data supplier.

If the user only enters a startDate, data for that date only is displayed in widgets for that data supplier.

If the user only enters an endDate, data for that date only is displayed in widgets for that data supplier.

Enabling and disabling dashboard definitions

By default, all the dashboards you or your end users create are available in the Analytics app.

Dashboards dropdown in the Analytics app

If you don’t want a dashboard to be available in the app, you must set the enabled property in the dashboard definition to false.

In this example, the demo dashboard is enabled:

analytics-ui/dashboards/demo.yaml
enabled: true
chartDefinitions:
  chart1:
    dataSupplier: recentPageActivitiesDataSupplier
    class: info.magnolia.analytics.amcharts.data.AmChartDefinition
    chartType:
      class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
      series:
        - name: Recently activated pages
          type: LineSeries
          yAxis: yaxe

When there are no user-defined dashboards available in the app, the fallback display by default is the demo dashboard provided by Magnolia.

If you disable the default demo dashboard, nothing is displayed in the app when no user-defined dashboards are available.

Default dashboard display

By default, the demo dashboard is the dashboard selected in the dropdown and displayed when you open the Analytics app.

If you want to change the default dashboard displayed, add the dashboardName property to /analytics-ui/apps/analytics.yaml and set its value to the name of the dashboard you want.

subApps:
  dashboard:
    class: info.magnolia.analytics.ui.app.DashboardSubAppDescriptor
    dashboardName: timeline # this is the real name of dashboard and its `enabled` property must be `true`
The dashboard definition name you set must exist under /analytics-ui/dashboards and be enabled.

Data suppliers available

You can configure which data suppliers are available to your end users in the Analytics app Add widget and Edit widget dialogs.

Data supplier dropdown

To do so, edit the configuration for the ignoredDataSupplierNamesStartingWith property under analytics-ui/config.yaml.

For example, by default, Magnolia removes the A/B/n Testing data supplier from the dropdown:

          ignoredDataSupplierNamesStartingWith:
            - testResultsDataSupplier #ignore supplier in ab testing

If you want to remove all data suppliers starting with the word "dummy", the configuration is:

          ignoredDataSupplierNamesStartingWith:
            - testResultsDataSupplier #ignore supplier in ab testing
            - dummy # ignore all supplier name starting with "dummy"

Chart types available

The analytics-amcharts-samples submodule provides several predefined chart definitions under /analytics-amcharts-samples/charts.

You can configure which chart types are available to your end users in the Analytics app Add widget and Edit widget dialogs when adding advanced widgets.

Chart type dropdown

To do so, edit the configuration for the chartTypeConfigurationName property in the:

  • Add widget dialog: analytics-ui/dialogs/widgetStep.yaml

  • Edit widget dialog: analytics-ui/dialogs/widgetStepForEdit.yaml

By default, Magnolia lists the Timeline (simple-line), Metric number (metric-number), Bar (simple-column) and Pie (pie) chart types in the dropdown:

        chartTypeConfigurationName:
          $type: comboBoxField
          required: true
          placeholder: analytics-ui.widgetStep.chartTypeConfigurationName.placeholder
          factoryClass: info.magnolia.analytics.ui.app.fields.ChartTypeConfigurationNameComboBoxFieldFactory
          datasource:
            $type: optionListDatasource
            options:
              - name: simple-column
                value: simple-column
              - name: pie
                value: pie
              - name: metric-number
                value: metric-number
              - name: simple-line
                value: simple-line

Adding a chart type to the dropdown

You can reuse one of the predefined chart definitions in the chart type dropdown, except those which have more than two data fields (such as the candlestick or ohlc chart types).

For example, to make the predefined word-cloud chart type available to your users when they add or edit all widgets, add it to the options as shown below.

chartTypeConfigurationName:
  $type: comboBoxField
  required: true
  placeholder: analytics-ui.widgetStep.chartTypeConfigurationName.placeholder
  factoryClass: info.magnolia.analytics.ui.app.fields.ChartTypeConfigurationNameComboBoxFieldFactory
  datasource:
    $type: optionListDatasource
    options:
      - name: simple-column
        value: simple-column
      - name: metric-number
        value: metric-number
      - name: pie
        value: pie
      - name: simple-line
        value: simple-line
      - name: word-cloud
        value: word-cloud

We recommend you provide an i18n key for the chart types you add to analytics-ui/i18n/magnolia-analytics-ui-messages_en.properties. You can find the key by opening the dialog and looking in the dropdown:

Dialog dropdown i18 key

If you want to update an existing chart created in v1.1 with a new chart type, use a YAML include to add it to the chart definition.

For example:

Before:
chart4:
  dataSupplier: contentTagsDataSupplier
  class: info.magnolia.analytics.amcharts.data.AmChartDefinition
  chartType:
    class: info.magnolia.analytics.amcharts.data.configuration.AmChartType
    series:
      - name: series
        type: WordCloudSeries
        labels:
          fill: "#599900"
        dataFields:
          - name: word
            value: tag
            jsonPath: $.[*].tag
          - name: value
            value: weight
            jsonPath: $.[*].weight
    type: WordCloud
After:
chart4: !include:/analytics-ui/charts/word-cloud.yaml
  dataSupplier: contentTagsDataSupplier
  chartType:
    # Decorate series for mapping json data
    series:
      - name: series
        dataFields:
          - name: word
            value: tag
            jsonPath: $.[*].tag
          - name: value
            value: weight
            jsonPath: $.[*].weight

Theme and CSS

You can change the CSS and theme of the dashboard charts to suit your visual requirements.

To do so, update the amcharts.css and amcharts_theme.js files in /info/magnolia/analytics/amcharts/vaadin.

Enabling responsiveness

Magnolia supports the amCharts responsiveness feature.

+ To make your charts responsive, enable the feature by adding the responsive property to the chart definition and setting it to enabled: true as shown in this example:

analytics-amcharts-samples/dashboards/ga-and-matomo-samples.yaml
chartDefinitions:
  column2Matomo: !include:/analytics-ui/charts/pie-and-donut-group/pie.yaml
    label: User country from Matomo
    chartType:
      responsive:
        enabled: true
    dataSupplier: demoMatomoSupplier

If you enable responsiveness, when a chart’s pixelWidth is ⇐ 500px, Magnolia automatically hides the chart legend.

You can change the responsive rules in /info/magnolia/analytics/amcharts/vaadin/amcharts_connector.js.

Default metrics and dimensions

The following default metrics and dimensions are used for each third-party data supplier. You can change the defaults through decoration in the data supplier .yaml file.

Adobe Analytics

Metric ID

Visits

metrics/visits

Unique Visitors

metrics/visitors

Page Views

metrics/pageviews

Time Spent per Visit

metrics/timespentvisit

Bounce Rate

metrics/bouncerate
Dimension ID

Date

variables/daterangeday

Google Analytics 4

Label ID

Users

activeUsers

Sessions

sessions

Items viewed

itemsViewed

Avg. Session Duration

averageSessionDuration

Bounce Rate

bounceRate
Dimension ID

Date

date

Matomo

Label ID

Unique Visitors

nb_uniq_visitors

Visits

nb_visits

Actions

nb_actions

Total time spent

sum_visit_length

Bounce Rate

bounce_rate
Dimension ID

Date

API.get

Example: Decorating default metrics and dimensions

In this example, the Adobe Analytics data supplier is decorated to change the default dimension and metrics.

The default time granularity dimension has been changed from days (daterangeday) to weeks (daterangeweek). The default metrics are now revenue and time spent per visit.

With this decoration, all commonly used metrics charts created by end users in the app are based on these new defaults.

/adobe-analytics/dataSuppliers/adobeDataSupplier.yaml

defaultCommonDimension: variables/daterangeweek

defaultCommonMetrics:
'metrics/revenue': "Revenue"
'metrics/timespentvisit': "Time spent per visit"
The metric ID is the value on the left. The value on the right is the i18n key displayed to users in the app. If no i18n key is set, the metric ID is displayed.

Metric data start dates

You can configure the start date for the metric data for each data supplier in /<module name>/dataSuppliers/<dataSupplierRegistryFile.yaml>.

This controls what data end users see in the widgets they add in Analytics app.

Defaults:

  • Adobe:

    • endDate: '2020-01-15'

    • startDate: '2020-01-01'

  • Matomo: last7

  • Google Analytics: 7DaysAgo

Date formatting in widgets

You can configure how dates are displayed in widgets either for each data supplier or for all the widgets, regardless of where the data comes from.

To configure date formatting for a specific data supplier, add the properties below to: /<module name>/dataSuppliers/<dataSupplierRegistryFile>.yaml For example, for Adobe, /adobe-analytics/dataSuppliers/adobeDataSupplier.yaml:

fromdateFormat: MMM d, yyyy
toDateFormat: dd.MM.yy
decimalNumberFormat: "#0.00"

To configure date formatting for all widgets, add the properties below to: /analytics/config.yaml. For example:

dateFormat: dd.MM.yy
decimalNumberFormat: "#0.00"
Property Description

fromDateFormat

Date format in the JSON results retrieved.

Default values:

  • AdobeDataSupplier: MMM d, yyyy

  • GoogleDataSupplier: yyyyMMdd

  • MatomoDataSupplierWithTransformer: yyyy-MM-dd

  • FileBasedDataSupplier: yyyy-MM-dd

toDateFormat

Date format you want to use in the charts defined for each data supplier.

If defined for a given data supplier, this property overrides the dateFormat property.

dateFormat

Defines the date format for all suppliers.

Default value: dd.MM.yy.

If the dateFormat property is configured in the /analytics/config.yaml file, and toDateFormat property isn’t, the value of the dateFormat property is used for date formatting.

If both the properties are configured, the value of toDateFormat is used.

Decimal formatting in widgets

Like date formatting, you can configure how decimals are displayed in widgets either for each data supplier or for all the widgets, regardless of where the data comes from.

To configure decimal number formatting for a specific data supplier, add the decimalNumberFormat property to: /<module name>/dataSuppliers/<dataSupplierRegistryFile>.yaml For example, for Adobe, `/adobe-analytics/dataSuppliers/adobeDataSupplier.yaml:

fromdateFormat: MMM d, yyyy
toDateFormat: dd.MM.yy
decimalNumberFormat: "#0.0000"

To configure decimal number formatting for all widgets, add the decimalNumberFormat property to: /analytics/config.yaml. For example:

dateFormat: dd.MM.yy
decimalNumberFormat: "#0.00"
Property Description

decimalNumberFormat

Decimal number formatting displayed in widgets.

The default value "#0.00" is set for all data suppliers in /analytics/config.yaml.

"#0.00" corresponds to two figures after the decimal point, for example, 1.23.

"#0.0000" corresponds to four figures after the decimal point, for example, 1.2345.

If the decimalNumberFormat property is configured in both the /analytics/config.yaml file, and the <dataSupplierRegistryFile.yaml>, the value in the <dataSupplierRegistryFile.yaml> is used.

Converting time metrics to seconds for Matomo widgets

This configuration only applies to data suppliers configured with the info.magnolia.analytics.matomo.datasource.MatomoDataSupplierWithTransformer class.

In some cases, Matomo returns time metrics as, for example, 2 days 12:34:56.789. This means 2 days, 12 hours, 34 minutes, and 56.789 seconds. To be correctly displayed and compared on a chart, a value such as 00:01:30.00 should be converted to seconds only: 90.

You can configure time metrics so they display as seconds using the property metricsForTimeToSecondsConversion property in matomo/config.yaml.

The default configuration is:

matomo/config.yaml
metricsForTimeToSecondsConversion:
- avg_time_on_site_new
- avg_time_on_site_returning
- sum_total_time_watche
- avg_time_on_site
- avg_page_load_time
- avg_form_time_hesitation
- avg_form_time_spent
- avg_form_time_to_first_submission
- avg_form_time_to_conversion
- avg_time_network
- avg_time_server
- avg_time_transfer
- avg_time_dom_processing
- avg_time_dom_completion
- avg_time_on_load
- avg_time_watched
- avg_time_to_play

Add metrics to this list as required for your data.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules