Business Calendar Requirements

Learn more about the data requirements for your custom business calendar.

Areas impacted by the business calendar

The business calendar affects the overall user experience, visual elements, and how data is processed:

Calculations: Visier Formula Language (VFL) functions like yearsBetween or workingDaysBetween are based on your calendar boundaries.
Extraction formulas: The business calendar can influence Visier Extraction Language (VEL) functions in the data load such as lastDateInMonthWithCustomCalendar.
The Time picker: The displayed date ranges are based on your uploaded CSV file.

Required columns

The business calendar CSV file must contain the specific columns described below to validate against the expected schema. It's defined at a daily granularity. This means every day must be explicitly accounted for as a row in the file, including a year before your tracked data, your entire historical period, and all future dates.

Note: The CSV file must contain a header line with the column names, and all rows must be sorted in ascending date order.

The business calendar must contain the following columns:

Column	Description	Required
DateID	The unique identifier of the date in yyyyMMdd, such as `20200701`.	Required
Date	The Unix timestamp including milliseconds for the date, such as `1593561600000` for July 1, 2020. Set to midnight UTC.	Required
Year	An integer representing the year in YYYY format, such as `2020`.	Required
YearLabelM	The long label that displays in the Time picker and chart axis for time in visualizations, such as `FY 2020`.	Required
YearLabelS	The short label that displays in the Time picker and chart axis for time in visualizations, such as `FY 2020`.	Required
Quarter	An integer representing the quarter that the date belongs to, such as `1` for July 1, 2020 to represent that date as part of the first quarter of the business calendar.	Required
QuarterLabelM	The long label that displays in the Time picker and chart axis for time in visualizations, such as `1st Quarter`.	Required
QuarterLabelS	The short label that displays in the Time picker and chart axis for time in visualizations, such as `Q1`.	Required
Month	An integer representing the month number, such as `1` for July to represent July as the first month of the business calendar.	Required
MonthLabelM	The long label that displays in the Time picker and chart axis for time in visualizations, such as `July` for July.	Required
MonthLabelS	The short label that displays in the Time picker and chart axis for time in visualizations, such as `Jul` for July. Note: Use short abbreviations. If you populate this column with full month names, the user interface may become crowded.	Required
Week	An integer representing the week of the date, such as `1` for July 1, 2020 to represent that date as part of the first week of the business calendar. Note: Do not include text prefixes. The word "Week" is automatically added to the values in this column. For example, if you input `1`, it renders as `Week 1` . Inputting `Week 1` results in a duplicate `Week Week 1` label.	Required
WeekLabelM	The long label that displays in the Time picker and chart axis for time in visualizations, such as `Week 1`.	Required
WeekLabelS	The short label that displays in the Time picker and chart axis for time in visualizations, such as `Wk 1`.	Required
FullTimeHours	The number of full-time hours for this date, such as `7.5` for a work day or `0` for a weekend day.	Required
CustomerID	The unique identifier of the customer, such as `00123`. This is for WFA legacy support. Note: The column and a value must be present, however, the value can be `0`.	Required
DataVersion	The data version of the business calendar. This is for WFA legacy support. Note: The column and a value must be present, however, the value can be `0`.	Required

Note:

LabelM is used across most standard system views while LabelS is used in the Time picker to select display day and year.
We recommend keeping all calendar labels under 20 characters. Shorter labels allow the user interface to render more items clearly in elements like the Time picker.

Let’s say your organization’s financial calendar begins in February. The example business calendar below demonstrates correct formatting:

DateID	Date	Year	YearLabelM	YearLabelS	Quarter	QuarterLabelM	QuarterLabelS	Month	MonthLabelM	MonthLabelS	Week	WeekLabelM	WeekLabelS	FullTimeHours	CustomerID
20160131	1454198400000	2016	FY 2016	FY 16	1	Quarter 1	Q1	1	February	FEB	1	FEB-W01	W01	0	54
20160201	1454284800000	2016	FY 2016	FY 16	1	Quarter 1	Q1	1	February	FEB	1	FEB-W01	W01	7.5	54
20160202	1454371200000	2016	FY 2016	FY 16	1	Quarter 1	Q1	1	February	FEB	1	FEB-W01	W01	7.5	54

Best practices

Follow these best practices when uploading a business calendar to avoid unexpected issues.

Include every day in the business calendar file

Business calendars are defined at a daily granularity, meaning you must explicitly account for every day in the file. Your calendar dates must span the following ranges:

Start at least one year before your analytic tenant's start date.
Cover your entire historical data period.
Extend at least one year into the future.
Ensure your periods align with your year. Quarters, months, and weeks cannot cross over into a new business year—they must all restart fresh on the exact day the new year begins.

Include an extra decade of future dates so you don't have to constantly update the file. If the calendar approaches the end of its uploaded data, replace it with new future dates.

Update metric formulas for metrics that handle time

Metrics that handle time, such as time between calculations, use the uploaded business calendar unless gregorian is specified in the formula. Many of Visier's out-of-the-box metrics use gregorian in the formula. To use your business calendar instead, remove gregorian from the metric formula.

Populate FullTimeHours column correctly

Metrics such as Absence Ratio or Full-time Equivalents (FTE) rely directly on the FullTimeHours column to determine expected work days. It’s important to ensure this column is populated accurately for valid metric calculations when using your custom business calendar.

Do not change the required column names in the business calendar file

Do not change the column headers in your business calendar file because they are used to validate against the expected schema. To change the labels displayed in the Time picker, you must modify the row values in your file.

Review Visier Formula Language dependencies

Business calendars change how custom expressions calculate time gaps. Review the following dependencies to understand what VFL functions may be impacted:

VFL functions without Gregorian fallbacks: VFL calendar functions like yearsBetween, monthsBetween, daysBetween, millisBetween, or workingDaysBetween are based on your uploaded business calendar data. If you do not define a Gregorian calendar fallback parameter. The formula may return an error if a date falls outside calendar boundaries.
Past-date validation errors: Formulas that calculate expressions like Age may fail and return an error if an employee's birth date falls outside your business calendar's range.

To prevent historic data validation failures, we recommend that you include the Gregorian fallback parameter within your VFL time-calculation formulas. For more information, see Visier Formula Language (VFL).