History Modifier With Examples

A guide on how to include history modifiers in your formulas in Plecto.

Last updated: Feb. 15, 2022

A history modifier is a setting in the data function component. It manipulates the formula so that it includes data from a previous time period outside of what you can select on widgets, reports, notifications, or other places where formulas are used.

The history modifier makes the formula look at data relative to a time period in the past, for example, the previous 5 days, 2 weeks before the beginning of the current month, the past 2 years, and more.

how-to-add-history-modifier.png

You can find the history modifier in the "more menu" when adding a data function component in the formula editor. The history modifier allows you to customize formulas to draw historical data as well as display your current and past KPIs on the same widget on a dashboard.

History Modifier Number Box.png

An example of a number box displaying data for the current week compared to last week.

It is common to use formulas with history modifiers on widgets that can display a minimum of two KPIs, such as the number box, speedometer, line and area charts, and the table widget.

The available time periods are Day(s), Week(s), Month(s), Year(s). The historical data the formula calculates from your data source is relative to the time period selected on the widget.

For example, you want to count the number of sales deals for the previous 5 days from a data source called "Deals." You can create a data function component and add a history modifier like the following:

history-modifier-formula-3.png

This history modifier will look at historical data from five days ago.

Let's break down how a dashboard widget would display data from the formula above if different time periods are selected.

  • Current day: The widget will display data from five days back, starting from yesterday. For example, if the current day is June 10th, it will show data from the 5th until the 9th of June (both days included).
  • Current week: The widget will display data from five days back, starting from the last day of the previous week. For example, if the current day is June 10th and the week starts on June 7th, the widget will show data from the 2nd until the 6th of June (both days included).
  • Current month: The widget will display data from five days back, starting from the last day of the previous month. For example, if the current day is June 10th, it will show data from the 27th until the 31st of May (both days included).
  • Current year: The widget will display data from five days back, starting from the last day of the previous year. For example, if the current year is 2021, the widget will show data from the 27th until the 31st of December 2020 (both days included).

You are tracking your KPIs and would like to see the performance today compared to yesterday on the same widget on a dashboard. The easiest way to do so is by copying an existing formula, adding a history modifier to the duplicate, and adding both formulas to a widget, such as a number box.

For example, to display the number of leads on the current day compared to the previous day, you could create two formulas as here below.

  • A formula that counts the number of leads in a data source:
history-modifier-example-a.png
  • A formula that counts the number of registrations in a data source one day before the chosen time period on the widget:
history-modifier-example-a1.png

The video below illustrates how to add both formulas to a number box widget on a dashboard to see the number of leads on the current day compared to the previous day.

Say you want to see the performance this month compared to the same month last year on a single widget, such as a number box. The easiest way to do so is by copying an existing formula, customizing the duplicate with two history modifiers, and adding both formulas to a widget on your dashboard.

Time period

Make sure to set the time period on the widget to "Current month."

For example, to display the number of deals this month compared to the same month last year, you could create two formulas like here below.

  • A formula that counts the number of deals in a data source:
history-modifier-example-b.png
  • A formula that counts the number of deals for the same month last year. For this formula, we need to create two components with history modifiers like the following:
history-modifier-example-b2.png

The modifier in the first component takes data from the previous year (you can also use 12 months) and the second takes data from the previous 11 months. All we need is to subtract the 11 months of data from the 12 months to get the metrics for the same month last year.

Assume you have a manual data source containing all your employee targets, but there is only one registration per employee that gets updated if the target changes. Knowing that each registration has a date field linked to it, if a registration does not get updated for a while, it might not fit within the time period selected on a widget and therefore not display the target.

To work around this limitation, you can add a history modifier to the formula to display the employee target even if it is outside the selected time period on the widget. To do so, you should create a formula using the Last data function.

Be aware of the scope

The history modifier will exclude the targets from the currently selected time period on the widget. For example, if you create a target on a Tuesday and the time period on the widget is "Current day," the widget will display 0 as the history modifier takes the data from Monday and back.

In this formula, you can freely decide how much of the historical data you want to draw. If you know that the employee targets get updated rarely, you can add more time to the modifier, for example, 3 years. See the formula below:

history-modifier-example-c.png

The available history modifiers in the Advanced formula editor are Day, Week, Month, Year. Please note that the history modifiers are written as singular nouns: "day" instead of "days," "month" instead of "months," and so on. Here are some examples:

.History(2,day)
.History(3,week)
.History(10,month)
.History(3,year)

The video below shows how to create formulas in the advanced editor and see the number of leads on the current day compared to the previous day.

Build more formulas

Learn how to create a year-to-date index by applying a history modifier to your formula. Read more in Year-to-Date Index.

Was this article helpful?