Work With Metrics

Learn about metrics and metric formulas in Visier.

Overview

A metric is a business concern that can be quantified as a number. For example, Headcount, or the number of active employees in your organization, is a business concern (how many people do we have?) that is quantified as a number (we have 5000 active employees). Metrics are based on one or more analytic objects (subjects, events, or overlays) and perform an aggregation to return a result.

Metrics calculate a value using a formula and settings. Metric formulas are written using Visier's Formula Language. Metric settings are defined in the Settings tab of a metric. To view the metrics in your Visier solution, open a project and navigate to Model > Metrics. To create a metric, see Create a Metric.

Note: To use Visier APIs to retrieve a list of all metrics in your solution, see Data Model API.

Metric formulas

Metric formulas define how values are calculated. Metrics are based on analytic objects (subjects, events, or overlays), and the functions you can use in a metric formula are related to the type of analytic object. To author a new metric, you need to consider the analytic object you want to aggregate, how time should be handled in the query, what records you want to filter out, and how to aggregate the values.

Tip: To find the formula functions that are available, like on, filterBy, and aggregate, use the Formula dictionary in the Formula tab of a metric or see Visier Formula Language (VFL). For metric formula examples, see Metric Formula Examples.

The standard metric formula syntax is on <subject//event> <time handling> filterBy(<filter condition>) aggregate <function>(<aggregation property>)

Syntax

Description

Example

on

Keyword to start a query on a data source. The data source is the subject, event, or overlay that the metric uses in its calculation, such as Employee or Applicant. All metric formulas start with on.

 

<subject//event>

The source of records to aggregate across. The analytic object also determines the information displayed the Detailed View visual for a metric. Use the object name. For more information about object names, see Basic information (optional).

Applicant

<time handling>

The method to filter records by time. Time handling options are determined by the analytic object of the metric.

  • Subjects: Default behavior is validUntil instant, which queries the state at the selected time.
  • Events: Default behavior is occurredIn interval, which queries over the entire selected interval.

Tip: When using the default behavior, we recommend that you omit time handling expressions in metric formulas. If omitted, the metric uses the default time handling option. For example, instead of on Employee_Exits occurredIn interval aggregate count (EmployeeID), you can simply write on Employee_Exits aggregate count (EmployeeID) to count exits.

lastKnownStateIn

filterBy

Keyword to add an optional filter clause to a query. Use filterBy to specify the records that you want to include in the aggregation. You may use multiple filter clauses in a query. You may use existing properties, concepts, or dimensions in a filterBy clause. Additionally, you may filter using other functions like include, exclude, hasValue, and operators like and, or, not, =, !=, <, <=, >, >=. For more information, see filterBy.

filterBy(!isClosedApplicant)

<filter condition>

The properties, concepts, or dimensions to filter the metric calculation by and any filter functions.

Note: You can also write a nested query to create variables within a formula to filter by, if needed. For more information about assigning variables, see :=.

isClosedApplicant

aggregate

Keyword to add an aggregation clause to a query. Data aggregation queries must have exactly one aggregation clause. For more information, see aggregate.

 

<function>

The method to aggregate records after they are filtered by time and record values.

count

<aggregate property>

The property to use to aggregate the metric.

Note: If the formula uses multiple analytic objects, you must use a property's qualified name to specify which object it belongs to. A qualified name includes the parent analytic object's name and the property name; for example, Current Employee is an attribute of Employee, so its qualified name is Employee.Current_Employee.

ApplicantID

Analytic objects in metric formulas

The following table provides an example and general formula structure for each analytic object type that a metric can be based on.

Note: These formula structures are commonly used, but you can write metric formulas that don't look like the below structures and still achieve the results you want.

Analytic object Example Formula structure
Subject Headcount is based on the Employee subject. on <subject> <time handling> filterBy<filter condition> aggregate <function>(<aggregation property>)
Event Resignation Count is based on the Employee Exit event. on <event> <time handling> filterBy<filter condition> aggregate <function>(<aggregation property>)
Overlay (lookup) Engagement Overall Score is based on the Engagement lookup overlay. on <overlay> filterBy(<filter condition>) lookup <property>
Overlay (rollup) Revenue is based on the Revenue rollup overlay. on <overlay> filterBy(<filter condition>) aggregate sum(<property>)

Example: Writing a metric formula

Let's say you want to create a metric to calculate the active headcount in your organization. You can breakdown the metric formula by thinking about the four key considerations, as shown in the following table:

Consideration Value Description
Analytic object Employee Headcount data comes from the Employee subject.
Time handling validUntil instant This time filter selects records with a validity interval that contains the given instant. The endpoint is inclusive. In this example, we're using the default time handling for a subject, so we'll omit it from the final formula.
Filter isActiveEmployee A selection concept that selects employee records that are active during the time period.
Aggregation count (EmployeeID) This aggregation function tells the metric to count members of the Employee subject by the EmployeeID property.

All together, this formula would look like:

on Employee filterBy(isActiveEmployee) aggregate count(EmployeeID)

Let's say you run your new Headcount metric to find active employees during March 2021, with the following employee records loaded in your Visier solution:

Validity_Start Validity_End EmployeeID Job_Name
January 1, 2021 March 31, 2021 10023 BI Consultant I
February 1, 2021 March 31, 2021 12789 BI Consultant I
February 1, 2021 February 28, 2021 19754 BI Consultant II
February 1, 2021 March 31, 2021 19721 BI Consultant II

The new Headcount metric will count the number of employee IDs that were valid during March 2021, which is 3.

Questions to consider

Writing a metric formula requires a lot of decision-making and forethought. To write a metric formula, ask yourself the following questions:

What business question do you want to answer?

Frame this as a sentence that can be answered with a numerical value; for example, how many employees are in my organization? Who wants the answer to this question? Frame this as the core audience that will benefit from the metric, such as HR leaders, line managers, or Finance teams.

What is the metric calculating?

In Visier, a metric calculates at least one analytic object, such as Employee. For more information, see Analytic Objects. In the standard metric syntax, put the analytic object's object name in the on <subject//event> part of the formula.

How does the metric handle time? 

In Visier, a metric must know what records to retrieve in a time period, such as all valid records in the selected time period or records that are valid at the end of the period. For more information, see "<time handling>" in Metric formulas. In the standard metric syntax, put the time handling function in the <time handling> part of the formula.

Which records does it select? 

Usually, a metric calculates a specific attribute on the analytic object, such as gender or performance rating. For more information, see Attributes. In the standard metric syntax, put the property, dimension, or concept's object name in the filterBy(<filter condition>) part of the formula.

What type of calculation is it?

In Visier, you have many aggregation options, such as count, average, and median. For more information, see Visier Formula Language (VFL). In the standard metric syntax, put the aggregation type in the aggregate(<function>) part of the formula.

Which records does it select? 

Usually, a metric calculates a specific attribute on the analytic object, such as gender or performance rating. For more information, see Attributes. In the standard metric syntax, put the property, dimension, or concept's object name in the (<aggregation property>) part of the formula.

What data type is the metric value? 

Metrics can return a value as an integer, a percent, in years, in months, as a number, and more. Configure the data type in the metric's Settings tab. For more information, see Settings (required).

Is the metric additive? 

Some metric values can be additive over any dimension or concept, like Headcount, or additive over time, like Employee Exit Count, or non-additive and cannot be summed over time, such as Average Headcount. Configure the additivity type in the metric's Settings tab. For more information, see Settings (required).

After answering the following questions, you can plug your answers into the standard formula syntax: on <subject//event> <time handling> filterBy(<filter condition>) aggregate <function>(<aggregation property>) Then, you're ready to create a metric in Visier! For more information, see Create a Metric.

Best practices

If using the object's default time handling, you can omit it from the formula. The platform will apply the default time handling at run time.

In metric formulas, Visier objects are referenced using their object name and path, if applicable. In the standard formula syntax, there are multiple Visier objects: the subject, the filters, and the property or dimension. To find an object's object name, open the object in a project and navigate to the Basic Information tab, then find the Object name field. Some objects have the same object name and display name, like Employee and Gender.

In the formula, you might specify an attribute's qualified name. The qualified name defines the attribute name and its parent analytic object; for example, Current Employee is an attribute of Employee, so its qualified name is Employee.Current_Employee. Use the following guidelines to decide if you should specify an object's qualified name:

  • If the metric formula only uses one analytic object, you can optionally omit the attribute's qualified name because the formula already specifies the analytic object. For example:
    Copy
    on Employee filterBy(isActiveEmployee) aggregate count(EmployeeID)

    Alternatively, you can write the same formula with qualified names: 

    Copy
    on Employee filterBy(Employee.isActiveEmployee) aggregate count(Employee.EmployeeID)
  • If the metric formula uses multiple analytic objects, you must specify qualified names for attributes that aren't associated with the primary analytic object so that the platform knows how to execute the formula. For example:

    Copy
    on Hire occurredIn interval aggregate average(daysBetween(Applicant.Requisition.Approved_Date, effectiveDate, gregorian))

    In this formula, Hire is the primary analytic object, however, Approved_Date is associated with a different analytic object (Requisition through Applicant), so we must specify the qualified name for Approved_Date.

After creating a new metric in Visier, always preview the metric to validate it works as expected. For more information, see Preview a metric.

In this section