PreEmptive Analytics Workbench User Guide

Portal Customization Concepts

Each component in the data pipeline is configured in a separate JSON file stored in the Portal configuration folder, <Installation Folder>/IIS/portal/config/. The Portal itself is initially configured though a main config file, config.json, at that path.

Config.json

The syntax of config.json is as follows:

{
    "default_report": "preemptive:overview",
    "default_query_timeout": 120,
    "display_date_format": "m/d/yy",
    "input_date_format": "mm/dd/yyyy",
    "reports": {
        "preemptive_1": "preemptive:overview",
        "preemptive_2": "preemptive:exceptions",
        "local_1": "local:report_1",
        "local_2": "local:subfolder/report_2"
    },
    "default_filters":[
        {
            "label": "Date Range",
            "type": "DateRange",
            "domains": ["All"],
            "fields": ["Time"]
        },{
            "label": "Application",
            "type": "Application",
            "domains": ["All"],
            "fields": ["AppId_Version"]
        },{
            "label": "OS",
            "type": "Many",
            "domains": ["All"],
            "fields": ["OS"],
            "hidden": true
        }
    ]
}
  • default_report - the Report shown to a user when they first load the Portal.
  • default_query_timeout - the total time in seconds the portal will allow for a query response. If this value is increased, the web.config of the server-side Interaction service should also be adjusted. See Managing Timeouts.
  • display_date_format - the format used to display dates.
  • input_date_format - the format used to parse dates in the date filter.
  • reports - which reports to make available to users, in the form of "internal-name": "namespace:report_filename".
    • The internal-name will be used in the URL of the Report and must be unique, but each report will specify its own user-friendly name to show in the Portal's UI.
    • Because the internal-name is used in the URL of Reports, do not change it after adding a Report, or links to that Report (including those by the Share feature) will break.
  • default_filters - the set of filters to be used for Reports that do not otherwise specify any.

The configuration above would include these files under the <Installation Folder>/IIS/portal/config/ folder:

  • preemptive/overview.report
  • preemptive/exceptions.report
  • local/report_1.report
  • local/subfolder/report_2.report

Each Report will load any dependent Widgets, Transformations, and Queries as required.

Datasets

The Rendering Pipeline operates on in-memory entities called Datasets. These are JSON entities, in the form of an array of objects, usually with each object corresponding to a row returned from the Query Web Service:

[
    {
        "String-Field" : "Field Value",
        "Numeric-Field" : 10
    },
    {
        "String-Field" : "Another Field Value",
        "Numeric-Field" : -7
    }
]

Datasets come in two varieties: Query and Transformation.

Query Datasets

Query Datasets are generated by Queries, and represent the results of a request to the Query Web Service. When the result is returned, each row becomes an object in the Dataset's array, and each field in that row becomes a key-value pair in the object.

For instance, if a Query makes a request for Custom Data information (i.e., the PreEmptive.CustomData.StringSummary Server Query) and receives the following data from the Query Web Service:

Key Value Count
Character Mage 10
Character Warrior 17
Inventory 1 Pickaxe 8

The Query Dataset would look like this:

[
    {
        "Key" : "Character",
        "Value" : "Mage",
        "Count" : 10
    },
    {
        "Key" : "Character",
        "Value" : "Warrior",
        "Count" : 17
    },
    {
        "Key" : "Inventory",
        "Value" : "1 Pickaxe",
        "Count" : 8
    }
]

Each Query generates only one Query Dataset during pipeline execution, called entities.

Transformation Datasets

Transformation Datasets are generated by Transformations; they are based on the contents of another Dataset, or a hardcoded array. This is done as follows:

  1. The new Dataset is created, creating an empty array whose length matches that of the input Dataset (or hardcoded array).
  2. Each object in the array is populated with a single field: data, containing the corresponding object from the input Dataset.
  3. Each transform action defined by the Transformation is applied, modifying the array. This may include copying data from other Datasets.

For instance, if a Transformation takes in the Query Dataset example above, and formulates a new field ValueLength that is calculated from the length of Value, the resulting Transformation Dataset would look like this:

[
    {
        "data" :
        {
            "Key" : "Character",
            "Value" : "Mage",
            "Count" : 10
        },
        "ValueLength" : 4
    },
    {
        "data" :
        {
            "Key" : "Character",
            "Value" : "Warrior",
            "Count" : 17
        },
        "ValueLength" : 7
    },
    {
        "data" :
        {
            "Key" : "Inventory",
            "Value" : "1 Pickaxe",
            "Count" : 8
        },
        "ValueLength" : 9
    }
]

A Transformation may define multiple Transformation Datasets, each having a unique name within that Transformation.

Note that while most transforms produce an array of objects, the facet transform groups rows into an object containing an array of groupings ("facets") instead. Other transforms and Widgets will interpret this top-level array as the Dataset, with each grouping being treated as a row.

Naming

Each component is identified by its namespace, filename, and extension. For Queries and Transformations, each Dataset within the component also has a unique name (though this is only important for Transformations, as Queries define one and only one Dataset).

Namespace

Namespaces are the folders within the <Installation Folder>/IIS/portal/config folder. All components saved under one of these folders takes that folder's name as its namespace. Further subfolders are not part of the namespace; rather, they are part of the filename.

For instance, a component located at <Installation Folder>/IIS/portal/config/local/subfolder/report_2.report has the namespace local.

There are two default namespaces, though you may add additional folders to define more namespaces:

  • preemptive: contains default components shipped with the Portal.
    • Warning: YOU SHOULD NOT ADD OR CHANGE FILES WITHIN THE PREEMPTIVE FOLDER. Workbench upgrades will overwrite this folder and all the files within it.
    • If you want to use modified versions of these default components, save copies of the files to the local folder and edit them there (remembering to update any references that now cross back over to the preemptive namespace). Remember to update the config.json to use these versions of the reports.
    • If you wish to remove a default Report, remove its entry from config.json.
  • local: a namespace for user-created components.
    • A report and set of widgets for viewing the raw data being returned by preemptive queries is included here, under the query-data subfolder. You can use and modify these components for debugging your own components.

Filename and Extension

Each component file is named with a filename that is used to identify it from other components, and an extension corresponding to the type of component it defines: .query, .transformation, .widget, or .report.

For instance, a component located at <Installation Folder>/IIS/portal/config/preemptive/exceptions.query has the filename exceptions and the extension query, and defines a Query.

Dataset

Queries and Transformations define Datasets. Each Query defines one and only one Dataset, named entities. Transformations may contain multiple Datasets, with names defined within the Transformation configuration file.

Referencing Components

When a component needs to reference another component, it does so in the form:

[namespace]:[filename].[extension]
  • [namespace], [filename], and [extension] are the parts of the component's naming.
  • [namespace]: can be omitted if the referred component is in the same namespace as the referencing component.
  • .[extension] must be omitted if only one type of component can be used in this context.
Example

The Overview Report (<Installation Folder>/IIS/portal/config/overview.report) defines one of the Widgets it displays like so:

{
    "widget_id": "users-by-day",
    "span": 6
}

This refers to <Installation Folder>/IIS/portal/config/preemptive/users-by-day.widget. No namespace is needed, because both the Overview Report and the Widget are in the preemptive namespace, and no extension is allowed, because only a Widget could be used in this context (a Report cannot "display" another Report, for instance).

Referencing Datasets

When a component needs to reference a Dataset in another component, it does so by referencing the component and the name of the Dataset (if it is a Transformation Dataset):

[component reference]>[dataset]

Because each Query only defines one Dataset, named entities, the syntax for referencing a Query Dataset can just be:

[component reference]
Example 1

The default sessions-by-runtime Transformation (<Installation Folder>/IIS/portal/config/preemptive/sessions-by-runtime.transformation) contains one Dataset, aggregation, which uses the sessions-by-runtime Query Dataset as an input:

{
  "name": "aggregation",
  "input": "sessions-by-runtime.query",
  "transform": [ ... ]
}

Because our input is a Query Dataset, we do not need to specify the Dataset's name, just the component. And because the Query is in the same namespace (preemptive) as the referencing Transformation, the namespace can be omitted. Note, however, that an extension (.query) is needed, because a Transformation Dataset's input can come from multiple kinds of components: either Queries or other Transformations.

Example 2

Let's say we want to modify the default sessions-by-os Widget and use it in our own Report. We save the <Installation Folder>/IIS/portal/config/preemptive/sessions-by-os.widget file as <Installation Folder>/IIS/portal/config/local/my-sessions-by-os.widget. We reference it in our Report, but when we test our Report, an error is displayed:

AJAX Error local/sessions-by-os.transformation Could not find component(s).

This is because our newly-copied Widget references its dependent Dataset with the line:

"input": "sessions-by-os.transformation>aggregation",

That is, it refers to a Transformation Dataset named aggregation, located in the file sessions-by-os.transformation. However, since there is no namespace listed, it assumes the same namespace as the Widget - which used to be preemptive, but now it's local. To fix this, we can either copy the Transformation file as well (and its dependencies), or modify the line to reference the preemptive version:

"input": "preemptive:sessions-by-os.transformation>aggregation",


Workbench Version 1.2.0. Copyright © 2016 PreEmptive Solutions, LLC