PreEmptive Analytics Workbench User Guide

Report Configuration

Reports define a page in the Portal, including the Widgets, their layout, and how data on that page can be filtered.

Report configuration files have the extension .report.

Page Contents

General Syntax

The syntax for specifying a Report:

{
    "title" : "Report Name",
    "icon" : "icon-id",
    "widgets" : [
        {
            "widget_id" : "namespace:widget-name",
            "span" : 12,
            "break" : true,
            "max_height" : "500px"
        },
        ...
    ],
    "filters" : [
        {
            "label" : "Date Range",
            "type" : "DateRange",
            "domains" : ["All"],
            "fields" : ["Time"]
        },
        ...
    ]
}
  • title (string): name of the report, which will be displayed in the page title and the navigation bar.
  • icon (string): the name of a Font Awesome icon to use for the Report in the navigation bar.
  • widgets (array<object>): array of widgets to show on the report. Each widget has:
    • namespace:widget-name (string): specifies which Widget to display, using the component referencing syntax.
    • span (number): width of the widget. The report is laid out in a 12 column grid, so this value must range between 1 and 12, inclusive.
    • break (optional, boolean): whether to force following Widgets to start on a new row, even if there is still remaining space on the current row. Defaults to false.
    • max_height (optional, string): Limit the height of the widget to the specified value.
  • filters (optional, array<object>): defines filters to use for this report. Defaults to the set of filters specified in config.json.
Example

preemptive:overview.report is default report that is first shown to users of the Portal (per the config.json setting). It contains four rows of widgets:

  • The first row has 3 widgets: the first two each take up a fourth of the row (a span of 3), and the third takes the remaining half (a span of 6).
  • The second row has 2 widgets, each taking half of the row.
  • The third row also has 2 Widgets, but the first only takes a fourth of the row, and the second takes the remaining three-fourths (a span of 9).
  • The fourth row has 3 widgets, each taking a third of the row (a span of 4).

Additionally, all table and metrics table widgets are limited in height to 318 pixels. This ensures the tables maintain a consistent height relative to each other (the user can scroll the tables to see more data).

It is defined as follows:

{
    "title": "Overview",
    "icon": "icon-dashboard",
    "widgets": [
        {
            "widget_id": "unique-users",
            "span": 3
        },
        {
            "widget_id": "sessions",
            "span": 3
        },
        {
            "widget_id": "top-app-version",
            "span": 6,
            "break": true
        },
        {
            "widget_id": "users-by-day",
            "span": 6
        },        
        {
            "widget_id": "sessions-by-day",
            "span": 6,
            "break": true
        },
        {
            "widget_id": "key-statistics-table",
            "span": 3,
            "max_height":"318px"
        },
        {
            "widget_id": "feature-summary-table",
            "span": 9,
            "break": true,
            "max_height":"318px"
        },
        {
            "widget_id": "sessions-by-os",
            "span": 4,
            "max_height":"318px"
        },
        {
            "widget_id": "sessions-by-runtime",
            "span": 4,
            "max_height":"318px"
        },
        {
            "widget_id": "sessions-by-country",
            "span": 4,
            "break": true,
            "max_height":"318px"
        }
    ]
}

Because this Report does not define any filters, all filters defined by config.json will be used.

Filters

The Query API supports filtering the queries, e.g. to limit the Portal to only show a certain date range for a particular application.

The Portal allows each Report to specify a set of filters that will apply to the Queries used by its Widgets. These filter options are displayed at the top of each report, though it is possible to make a filter invisible until it is triggered by a Table Widget's click action.

Each filter defined by the Report is configured in an object with the following properties:

  • label (string): the label on to display on the filter.
  • type (string): the filter type defined by the server. Can be:
    • Application: use only with the AppId_Version field.
    • DateRange: use for timestamp fields.
    • Many: use for string fields.
  • domains (array<string>): which Server Query domains to apply the filter to; queries from other domains will not be filtered. Specify "All" to indicate all domains should be filtered.
  • fields (array<string>): an array of server fields to apply this filter to. Only server fields that have been marked as filterable can appear here.
  • hidden (optional, boolean): whether to hide the filter when it is not in use. If true, the filter will appear when it is used in a Table Widget. Defaults to false.

If a Report doesn't specify any filters, the set defined by config.json will be used. Generally, it is best to define filters primarily in that file, and only specify filters on a per-Report basis for special cases, like the example below.

Example

preemptive:tamper.report defines its own set of filters to apply. This is because the default set in config.json includes filters for OS, Runtime, and Location, but tamper data may not have values for these fields (as tamper messages do not strictly need to occur during a session). Therefore, the Report manually declares two filters: one for application, and one for date range.

{
    "title" : "Tamper Notifications",
    "icon" : "icon-unlink",
    "widgets" : [
        {
            "widget_id" : "tamper-choropleth",
            "span" : 12,
            "max_height" : "500px",
            "break" : true
        },
        {
            "widget_id" : "tamper",
            "span" : 12,
            "max_height" : "318px",
            "break" : true
        }
    ],
    "filters" : [
        {
            "label" : "Date Range",
            "type" : "DateRange",
            "domains" : ["All"],
            "fields" : ["Time"]
        },
        {
            "label" : "Application",
            "type" : "Application",
            "domains" : ["All"],
            "fields" : ["AppId_Version"]
        }
    ]
}


Workbench Version 1.2.0. Copyright © 2016 PreEmptive Solutions, LLC