PreEmptive Analytics Workbench User Guide

Widget Configuration

Widgets are a visualization of data from a Query or Transformation. Tables, charts, and graphs are all types of Widgets.

Widget configuration files have the extension .widget.

Common Syntax

Widget Definition

All widgets share some common settings:

{
    "title": "Widget Title",
    "type": "type_of_widget",
    "input": "namespace:filename.extension>dataset",
    "options": { ... }
}
  • title (string): title for the widget on the report
  • type (string): the type of widget (one of the Available Widgets, e.g., "Table")
  • input (string): specifies which Dataset to use as the input to this Widget, using the Dataset referencing syntax
  • options (object): settings specific to each widget (see below)

Field Syntax and Metadata

Each input Dataset is an array of JSON objects. A field describes how to access a particular piece of data from that object, and how the widget should format it. Fields are used to choose columns and data series in most Widgets.

The complete field syntax is:

{
    "key": "path.to.data",
    "as": "Display Name",
    "type": "type of data"
}

Where:

  • key (string): The path to the data within the JSON object that represents a row of data. This is specified the same way you would access the data if it was a JavaScript object.
  • as (optional, string): A display name for the widget to use when showing this data, usually used as a series name or column header.
  • type (optional, string): A data type for the field (see below).

Note: Keep in mind the structure of the Dataset that you are accessing. In particular, when working with Query Datasets, fields need only be specified by the names declared in the query configuration, but to access the same data after it has passed through a Transformation Dataset, the reference would need to be prepended with data. first.

Shorthand

If you want to use the default as and type for a field, you can specify the key as a string instead of an object:

"path.to.data"

The Widget will attempt to determine the values of as and type based on existing metadata associated with the Dataset (such as from the Query Metadata).

Regular Expression

A regular expression (regex) can be used to specify multiple fields at the same time. This is useful after a transpose transform, as the field names might not be knowable when designing the Widget. The syntax is:

{
    "regex": "([^.]+Users)\\.sum",
    "format": true,
    "type": "number"
}
  • regex (string): specifies the regex to match against the path. The first capture (based on the first section in parentheses) made by the regex will be used for the display name (the as).
  • format (boolean): Whether to split the captured display name on capitals/underscores and use sentence capitalization. For instance, field 'NewUsers' becomes 'New users'.
  • type (string): The data type to use for all fields found by the regex.

For help in devising a JavaScript regular expression, refer to a reference site and test page, but note that in this context, all backslashes (\) must be escaped.

Data Types

The data type, used to format how the field will be displayed, is one of the following numeric types:

  • number: Interpret as a number, with no additional formatting (fieldValue.toString()).
  • fixed: Interpret as a number, format with 2 digits following the decimal point (fieldValue.toFixed(2)).
  • percentage: Interpret as a fraction of 1, format as percent with 2 digits following the decimal point ((fieldValue * 100).toFixed(2) + '%').
  • timelength: Interpret as .NET ticks (10 million ticks = 1 second), format like: 12h 24m, 10.4s, or 104ms.

Or one of the following non-numeric types:

  • characters: Interpret as a string, with no additional formatting (fieldValue.toString()).
  • date: Interpret as milliseconds since Unix epoch, format using the display_date_format set in config.json.
  • hour_of_day: Interpret as hours since midnight (e.g., 13 is 1 PM), format as a range like: 1pm-2pm.
  • formatted: The data is stored as a JSON object and contains metadata and a format property containing what to display in the widget. The AppId_Version field is a good example of a formatted object and is structured as below.
{
    "format": "Dummy Application",
    "value": "c870c254-0a1e-46af-8c9b-2a9e16264ab1",
    "value_type": "characters",
    "metadata":
    {
        "AppName": "Dummy Application",
        "AppId": "7b8dfa0d-eee6-4656-92e2-0669b49b0953",
        "AppGroupId": "1ff550e3-4446-4423-83b6-0d807d2af0e9",
        "CompanyId": "ef328ac2-876b-4b71-906f-5635581698a3",
        "CompanyName": "Dummy Company",
        "Version": "1.0.0.0"
    }
}

If no type is specified, the field's type is inferred from its original definition. This is declared on the server-side for most fields, but fields that are the result of a formula transform will use that transform's definition.

Available Widgets

This section lists each Widget type available for the Portal, including how it displays the data, how users of the Portal may configure their view of the Widget (aside from the standard Refresh icon), what options the Widget supports, and an example of the Widget's use within the default preemptive namespace.

Table

Displays each element in the Dataset as a row, with specified fields as columns.

Portal users can sort the rows based a column's values by clicking that column's header. Additionally, if a click action (the onclick option) is specified, users may trigger it.

Options
  • columns (array<field reference>): fields to show as columns in the table. The order specified here will be the order displayed, left-to-right.
  • sort (optional, array<string>): fields used to determine the initial ordering of the rows, using the same syntax as the sort transform. Defaults to the ordering of the input dataset.
  • onclick (optional, object): describes a click action that Portal users may trigger using this Widget.
    • action (string): can be one of:
      • modal: causes a modal popup to appear when the field specified in onclick.target is clicked, showing the value of the field specified in onclick.value.
      • filter: provides a checkbox associated with the report filters whose fields array contains the value specified in onclick.target. When checked, the report will be filtered by the value of the field specified in onclick.value.
    • target: see above
    • value: see above
    • title (string): the tooltip to show when the user hovers over the cell
Example 1

Exception Table with Modal Click Action

preemptive:exceptions-summary-table.widget displays information about exceptions that have occurred in client applications, with each row representing a unique stack trace, and displaying the exception message, the type of exception report each row represents, and the number of times it has been reported.

{
      "title": "Exception Summary",
      "type": "Table",
      "input": "exceptions-summary.transformation",
       "options": {
        "columns": [
            {
                "key": "data.ExceptionMessage",
                "as": "Exception"
            },
            "exceptionType",
            {
                "key": "data.Count",
                "as": "Count",
                "type": "number"
            }
        ],
        "onclick": {
            "action": "Modal",
            "target": "data.ExceptionMessage",
            "value": "data.ExceptionTrace",
            "title": "Click for details"
        },
        "sort": ["-data.Count"]
      }
}

Because displaying the full stack trace (data.ExceptionTrace) in a table would be poor aesthetics, this table only displays this field when the exception message (data.ExceptionMessage) is clicked, by using the Modal click action. This is why the example image has two entries for "The request timed out." - each row represents a different stack trace, that can be viewed by clicking on that text.

Example 2

Country Table with Filter Click Action

config.json defines a number of filters that can be used to limit the data queried (and thus displayed) in the Portal. Among them is one that allows filtering by Country:

{
    "label": "Location",
    "type": "Many",
    "domains": ["All"],
    "fields": ["Country"],
    "hidden": true
}

Because hidden is set to true, this filter does not normally appear in the Portal (like the application and date range ones do), but it is possible for Widgets to set this filter. This is exactly what preemptive:sessions-by-country.widget is intended for:

{
    "title" : "Sessions by Country",
    "type" : "Table",
    "input" : "sessions-by-country.transformation>aggregation",
    "options" :
    {
        "columns" : [
            "data.Country",
            "data.Count",
            {
                "key" : "AvgLength",
                "as" : "Avg. Length"
            }
        ],
        "onclick" :
        {
            "action" : "filter",
            "target" : "Country",
            "value" : "data.Country",
            "title" : "Click to filter"
        },
        "sort" : ["-data.Count"]
    }
}

This Widget lists all countries where sessions have run, and provides a filter click action, meaning each row will have a checkbox associated with it. When one or more checkboxes are clicked, a "filter" icon will appear at the top of the table; clicking that icon will cause the Portal to filter the queried data by the checked values. This is done because Country is present both in the filter's fields array and the Widget's target option.

Metrics Table

Displays fields from the first element in the Dataset, with each field receiving its own row. This is good for summary data, such as the result of a stats transform on non-faceted input.

Portal users have no special controls for this Widget.

Options
  • fields (array<field reference>): fields to show as rows. The field's friendly name will be shown on the left of the table, and the value will be shown on the right. The order specified here will be the order displayed, top-to-bottom.
Example

Metrics Table

preemptive:key-statistics-table.widget displays a summary of important scalar values within the currently-displayed data. These were calculated by multiple transforms, such as aggregate, which produced a Dataset with only one element containing many sub-elements for various metrics. The Widget displays each piece of information on a row, labeled with the name specified.

{
    "title" : "Key Statistics",
    "type" : "Metrics Table",
    "input" : "key-stats.transformation>day_metrics",
    "options" :
    {
        "fields" : [
            {
                "key" : "Count.sum",
                "as" : "Total Sessions"
            },
            {
                "key" : "CompleteCount.sum",
                "as" : "Complete Sessions"
            },
            {
                "key" : "Count.mean",
                "as" : "Avg. Total Sessions",
                "type" : "fixed"
            },
            {
                "key" : "CompleteCount.mean",
                "as" : "Avg. Complete Sessions",
                "type" : "fixed"
            },
            {
                "key" : "MinLength.min",
                "as" : "Min. Session Length",
                "type" : "timelength"
            },
            ...
        ]
    }
}

Line Graph

Displays multiple series of numerical values (y-values) graphed as ordered functions of another numerical field (x-values). Despite the Widget's name, the y-values may be expressed either as lines or in a stacked-area format.

Portal users can disable and re-enable the drawing of individual series, and in the stacked-area format, they may also choose to view the graph as a traditional stacked-area graph (Stacked), a streamgraph (Stream), or relative graph based on the percent of each x-value's total as a percent (Expanded).

Options
  • type (string): the type of line graph to show:
    • line: each y-value is graphed in terms of distance from the x-axis; the series is connected by line segments.
    • stacked: each y-value is graphed in terms of distance from the previous series' corresponding value; the space is filled with the color of the upper series.
  • xaxis (field reference): the field that defines the x-values.
  • xaxis_label (optional, string): label for the x-axis. Defaults to the friendly name of the field specified for xaxis.
  • xaxis_type (optional, data type): data type for the x-axis. Defaults to the data type of the field specified for xaxis. Must be numeric.
  • yaxis (array<field reference>): fields that define each series.
  • yaxis_label (optional, string): label for the y-axis. Defaults to the friendly name of the first yaxis field.
  • yaxis_type (optional, data type): data type for the y-axis, defaults to the data type of the first field in yaxis. Each must be numeric.
  • series_count (optional, number or "All"): limit the number of series to display on the graph (e.g., 10 to display "first 10 in series_sort order"). Defaults to "All".
  • series_sort (optional, string): determine how to rank the series when using series_count. Can be any of the following options, and can be preceded by - to rank in descending order (i.e., highest are shown, not lowest):
    • sum: rank by total of series values.
    • min: rank by minimum value within each series.
    • max: rank by maximum value within each series.
    • name: rank by the friendly name (the as of the field) of the series.
Example

Line Graph

preemptive:version-adoption.widget displays the 10 most used application-versions. (Note that the Workbench considers each version of an application a separate entry, so if the Portal user filters by a particular application but not by version, this graph will indicate version adoption for that application).

The input Dataset originated as a query for session information by application and day (preemptive:version.query), which was then faceted (grouped) by day and transposed so each day had a field for every application that occurred on that day. The resulting Dataset looks something like this:

[
    {
        "key" : "1412553600000",
        "Time" : 1412553600000,
        "transposed":
        {
            "Application v1.0": 2
        },
        "values" : [ ... ]
    },
    {
        "key" : "1412640000000",
        "Time" : 1412640000000,
        "transposed":
        {
            "Application v1.0": 3,
            "Application v2.0": 1
        },
        "values" : [ ... ]
    }
]

The Widget uses the Time field as the x-axis, and each result of the transpose operation (that is, every application) as a series. This can be done without knowing the specific application names by using a regular expression:

{
    "title" : "Version Adoption (top 10)",
    "type" : "Line Graph",
    "input" : "version-adoption.transformation>entities",
    "options" :
    {
        "type" : "stacked",
        "series_count" : 10,
        "series_sort" : "-sum",
        "xaxis" :
        {
            "key" : "Time",
            "type" : "date"
        },
        "yaxis" : [
            {
                "regex" : "transposed\\..+",
                "type" : "number"
            }
        ],
        "xaxis_label" : " ",
        "yaxis_label" : " "
    }
}

The Widget limits its display to 10 series, in decreasing sum order; that is, the top 10 applications, in terms of total sessions in the displayed time frame, will be displayed. All other applications are not listed.

Bar Graph

Displays multiple series of numerical values (y-values) graphed in groups based on another field (x-values). Unlike the Line Graph, the x-values do not need to be numeric.

Portal users can disable and re-enable the drawing of individual series, and choose to view the different series adjacent to each other (Grouped) or stacked on top of each other (Stacked).

Options
  • xaxis (field reference): the field that defines the x-values.
  • xaxis_label (optional, string): label for the x-axis. Defaults to the friendly name of field specified for xaxis.
  • xaxis_type (optional, data type): data type for the x-axis. Defaults to the data type of the field specified for xaxis. Can be non-numeric.
  • yaxis (array<field reference>): an array of fields that define each series.
  • yaxis_label (optional, string): label for the y-axis. Defaults to the friendly name of the first yaxis field.
  • yaxis_type (optional, data type): data type for the y-axis, defaults to the data type of the first field in yaxis. Each must be numeric.
Example

Bar Graph

preemptive:service-level.widget displays three different metrics, grouped by day.

{
    "title" : "Service Level",
    "type" : "Bar Graph",
    "input" : "preemptive:service-level.transformation>aggregation",
    "options" :
    {
        "xaxis" :
        {
            "key" : "Time",
            "as" : "Date",
            "type" : "date"
        },
        "yaxis" : [
            "ExceptionsPerSession",
            "Count",
            {
                "key" : "ExceptionCount",
                "as" : "Exceptions"
            }
        ],
        "xaxis_label" : " ",
        "yaxis_label" : " "
    }
}

Choropleth (map)

Displays a geographic map with regions colored according to a data field and a region-identifying field.

Portal users have no special controls for this Widget.

Options
  • map (string): The map to display. Currently there is only one supported map:
    • world-countries: a map of the world with countries as the regional unit, projected using the Kavrayskiy VII projection. The location field must specify a valid ISO 3166-1 country code.
  • value (field reference): The data field. Only numeric types are supported.
  • location (field reference): The region-identifying field. The field should have a formatted data type, containing a sub-field, value, which is the ID for the region. Depending on the map and area unit, the required value may vary.
  • default_color (optional, string): Color for geographical regions that do not have data associated. Default is #D3D3D3
  • scale (object)
    • type (string): The type of scale used for shading regions of the map. Currently there is only one supported type:
      • gradient: data values are mapped linearly to a customizable color gradient.
    • options (optional, object): Settings for the gradient scale type.
      • min (number): Data value to start the scale from. Values smaller than the specified minimum will be colored with the color of the minimum. Default is 0.
      • max (number): Data value to end the scale on. Values larger than the specified maximum will be colored with the color of the maximum. Default is the biggest data value in the Dataset.
      • colors (array<string>): An array of colors to graduate through. At least two colors are needed. Default is #A9F5A9 to #173B0B.

Each color property is specified with string containing a CSS-style color identity (hexadecimal, RGB triplet, or color name).

Example

Choropleth

preemptive:sessions-by-country-choropleth.widget indicates the number of sessions that occurred per country. Countries that have more sessions are shown in darker shades of green, those that have fewer sessions are shown in lighter shades of green, and those that have no sessions are shown in gray.

{
    "title" : "Session Locations",
    "type" : "Choropleth",
    "input" : "preemptive:sessions-by-country.transformation>aggregation",
    "options" :
    {
        "map" : "world-countries",
        "value" : "data.Count",
        "location" : "data.Country",
        "default_color" : "#ddd",
        "scale" :
        {
            "type" : "gradient"
        }
    }
}

Prominently displays a single value, along with a label, in colors that can be customized.

Portal users have no special controls for this Widget.

Options
  • field (field reference): the metric for the Widget to display. The friendly name (as) will be used for the label for the Widget.
  • text-color (optional, color): text color for the value and the label. Default is "white".
  • background-color (optional, color): background color for the Widget. Default is series color 0 (blue).

There are three different ways to specify color for the two color options:

  • a number between 0 and 9, inclusive. This refers to a color in the default 10-color palette used by the other Widgets (e.g., 0 is blue, 1 is orange).
  • a string containing a CSS color specification. This can be expressed in hexadecimal format ("#FF0000"), as an RGB triplet ("rgb(255, 0, 0)"), or a recognized name ("red").
  • a JSON object containing a single property, expr, which specifies an expression that evaluates to a CSS color specification string. Similarly to the formula transform, the first element of the input dataset can be referenced in this expression by the variable d.
Example

This Widget displays the total number of Sessions that fall under the current filters, labeling the metric Total Sessions, coloring the text white, and coloring the background red if the number is above 1000, or blue otherwise.

{
    "title" : "Total Sessions",
    "type" : "Featured Metric",
    "input" : "preemptive:key-stats.transformation>day_metrics",
    "options" :
    {
        "field" :
        {
            "key" : "Count.sum",
            "as" : "Total Sessions"
        },
        "text-color" : "white",
        "background-color" :
        {
            "expr" : "d.Count.sum > 1000 ? 'blue' : 'red'"
        }
    }
}


Workbench Version 1.2.0. Copyright © 2016 PreEmptive Solutions, LLC