Applies to: brains.app Platform
Users who can do this: Administrator
Introduction
Metrics are a key component of the brains.app platform as they allow to expose data from various data sources and to use this data in dashboards and reports.
Numerous metrics are set-up during the initial implementation at a new site, with more metrics added overtime to expose more data or to set new features.
There is a new menu item, for admin users on the brains.app context menu.
Inside this new library there are 4 items (as shown in the screen below):
Metric Types
Icons
Units
Quantities
How to use Metric Types Library?
The metric types basically will group certain properties of a metric together in one place and then can be linked to a metric.
A user can create/edit/update and delete metric types on this screen. From the release forward, there will be no metric types to use. The user will need to create new types if they wish to use these in the metrics.
The details that can be entered are:
Metric Type Name
Description of metric type
Icon - select from a library of icons
Unit - select from a library of units
Cumulative
IMPORTANT
Some basic metric types will be necessary to be setup by the user in order to use the metrics screen and batch add metrics feature.
Please note these metric types are company-wide and are meant to be used to standardize metrics for all sites across a company.
How to use Bulk Add Metric Types?
This new feature is part of the metric types summary screen and there is a “Bulk add metric types” option at the top of the summary screen (same picture shown above).
The format of a CSV file or excel should be as follows with the headings at the top first row:
name*
description
unit*
icon*
color*
cumulative* - TRUE/FALSE
Those fields with a * beside cannot be left blank. You can also find this procedure in our article 'How to add bulk/batch metrics to brains.app'.
A validation button is provided to validate the input before the user can submit the batch of metric types.
Validations rules are:
Headers in row 1 match -> Row 1 - List of headers could not be found or doesn’t match expected column names;
Name not null or empty → Row X - Missing metric type name;
Name does not exist in the list of metric types in the database → Row X - A metric type with the same name already exists in the database;
Name not already in prior rows to be inserted → Row X - Duplicated metric type name within the file;
Unit not null and exists in the database → Row X - Unit is missing or does not exist;
Icon not null and exists in the database → Row X - Icon is missing or does not exist;
Color not null → Row X - Colour is missing;
Cumulative not null and valid → Row X - Cumulative property is missing or invalid: valid values are “TRUE“ and “FALSE“.
Once validation passes then the Import button becomes visible.
Icons Library?
The icons library holds the icons which are in use by metrics.
The information that the icons hold are
Icon name
Icon class - set to 'fontawesome icons'
Icon - select from a list of 'fontawesome' set of icons
The icon name and icon class symbol are unique (case insensitive).
The icon cannot be updated if it is used in an existing metric.
The icons that the brains.app had in the previous release in the metrics admin screen will be the default icons.
Units Library
The units library holds the units which are in use by the metrics.
The information that the units hold are:
Unit name
Unit symbol
Unit position
Unit quantity - select from quantities library
The unit name and unit symbol are unique (case insensitive).
The unit cannot be updated if it is used in an existing metric.
The units which brains.app had in the previous release in the admin metrics screen will be the default units available.
Quantities Library
The quantities library holds the quantities which are in use by the units library
The information held is:
Quantity name
Quantity
The quantity name is unique and only one can exist (case insensitive).
The quantity cannot be updated if it is used in an existing unit.
The quantities did not exist before and the default quantity is set to “Other”.
New Metrics screen
The admin metrics screen has now been revamped to include the new libraries for metric type/icons and units.
This metric admin screen is almost the same as the old one but the layout and a few fields have different inputs or are new.
Metric type - this is a new field and is left blank for legacy metrics. This is intended for use with any new metric or batch-add metrics.
Icon - this field is a selector list from the icon library
Unit - this field is a selector list from the unit library
New Bulk Add Metrics
The way that bulk add metrics behaves is very different from the old batch metrics.
The old batch metrics were limited in that:
It had no validation on fields
It took a long time for large batches to insert
A user could only attach a bunch of metrics to one chosen asset
The Bulk add metrics is available from the summary screen in the admin metrics summary screen.
The above issues have now been rectified in a revamped screen and a new batch metric format.
The metrics format should follow the following format with the header exactly matching these names in a csv/excel sheet.
assetName*
metricName*
Description
metricType*
source* - Manual, Interval, Constant, Equation, Mongo
interpolationType - Only valid for Manual source type, none or hold.
databaseField*
Equation
value - Field _multiplier_ in the backend
defaultValue - only for Manual or Interval types
Min
Lowlow
Low
High
Highhigh
max
Those fields with a * next to them are mandatory
A user can now attach a metric to a chosen assetName so that many assets can have a metric attached to them at the same time in the same batch file.
NB A Metric type will have to be set up for this new batch of metrics to work.
A validation button is provided to validate the input before the user can submit the batch of metrics.
There are many validation rules here for batch metrics. Following validation is applied (with a corresponding error message to display for the row otherwise):
Check that list of columns is correct on first row → Row 1 - List of headers could not be found or doesn’t match expected column names
assetName not null and exists → Row X - Missing asset name or the asset does not exist
metricName not null or empty → Row X - Missing metric name
Metric name <metricName> does not already exist (case insensitive) → Row X - A metric with the same name already exists in the database
metricName (case insensitive) does not exist in previous rows → Row X - A metric with the same name already exists in a previous row
metricType not null and exists → Row X - Missing metric type or the metric type does not exist
databaseField not null or empty → Row X - Missing database field
Source not null and valid → Row X - Source is missing or invalid: valid sources are MANUAL, INTERVAL, CONSTANT, EQUATION, MONGO
interpolationType is:
none” or blank (empty string) otherwise → Row X - Interpolation type must be none or blank for a metric types which are not Manual
null otherwise → Row X - Interpolation type must be null for a metric types which are not Manual
10. Equation is:
not null if the metric type is of type EQUATION → Row X - _equation_ is missing for a metric type with source “EQUATION”
null otherwise → Row X - equation must be null for a metric type with source “MONGO“
11. “value” is:
not null if the metric is of type CONSTANT → Row X - _value_ is missing for a metric type with source “CONSTANT”
null otherwise → Row X - value must be null for a metric type with source “MONGO”
12. defaultValue is:
null for metrics other than MANUAL or INTERVAL → Row X - Default value must be null for a metric which are not MANUAL or INTERVAL
null or number otherwise → Row X - Default value must be null or a number for metric types which are Manual or Interval_
13. min <= lowlow <= low <= high <= highhigh <= max (any of those can be null) → Row X - Invalid range, <lowlow> must be lower than <high>
Once validation passes, the Import button will become visible and the user can create the new batch of metrics.