Dates and time

Learn how to create dates and times, measure durations, extract date parts, and build reporting periods in Ninox scripts.

Dates and time values drive schedules, deadlines, logs, and reports in Ninox. This chapter shows you how to create date values, measure spans, extract date parts, and build reporting keys for dashboards and automation.

In this chapter, you will learn how to:

• Create current and fixed date or time values.

• Format date and time output.

• Measure elapsed time and add time offsets.

• Extract parts like year, month, weekday, or quarter.

• Build reporting keys and business calculations from dates.

Function (A-Z)	Task
age()	Return the age in years from a date
date()	Create a specific date
datetime()	Create a specific date and time
day()	Return the day of the month
days()	Return the number of days between two dates
duration()	Return the span between two date or time values
endof()	Return the end of a period such as a month
format()	Display a date or time value as text
month()	Return the month number
now()	Return the current date and time
quarter()	Return the quarter number
time()	Create a specific time value
timeinterval()	Create a duration offset such as 2 hours
timestamp()	Convert a value to a UTC-based timestamp
today()	Return the current date
week()	Return the week number
weekday()	Return the weekday number
workdays()	Return business days between two dates
year()	Return the year number
yearmonth()	Build a year-month reporting key
yearquarter()	Build a year-quarter reporting key
yearweek()	Build a year-week reporting key

Create date and time values

Use these functions when you need a real date or time value. They are useful for stamps, due dates, schedules, and logs.

Get today’s date with today()

Use today() when only the date matters.

Use it when you want to:

• Compare against a deadline.

• Use the date of today directly or as a basis for further calculations.

today() returns the current date without a time part.

Let’s take a look at some examples:

if today() > due_date then "Overdue" else "On time" end

Checks whether a record is past its due date.

today() + 7

Builds the date seven days from today.

year(today())

Returns the current year from today’s date.

Get the current date and time with now()

Use now() when the exact moment matters.

Use it when you want to:

• Stamp record creation.

• Measure elapsed hours or minutes.

• Build date calculations from the current timestamp.

now() returns the exact current timestamp at the moment the function runs.

Let’s take a look at some examples:

created_at := now()

Stores the current timestamp in a field.

date(now()) + 7

Builds a date value for seven days from today.

Create fixed values with date(), time(), and datetime()

Use date() to create a date or convert a time-based value to a date. Use time() to create a fixed time value. Use datetime() to create a local timestamp from numeric values, a date and time, or Unix time in milliseconds.

Use them when you want to:

• Build a due date from year, month, and day.

• Convert a time-related value to a time.

• Set a meeting time.

date(any) date(year, month, day) time() time(any) time(hour, minute) time(hour, minute, second) time(hour, minute, second, millisecond) datetime(milliseconds) datetime(year, month, day) datetime(year, month, day, hour) datetime(year, month, day, hour, minute) datetime(year, month, day, hour, minute, second) datetime(year, month, day, hour, minute, second, millisecond) datetime(date, time)

• any (for date(any)): a date, datetime, or numeric timestamp in milliseconds

• year: the year value

• month: the month number

• day: the day of the month

• hour: the hour value in 24-hour format

• minute: the minute value

• second: the second value

• millisecond: the millisecond value

• any (for time(any)): a date, datetime, appointment boundary, time, or numeric timestamp in milliseconds

• date: the date part

• time: the time part

If you pass a number to date(any), Ninox treats it as Unix time in milliseconds. If you omit the time part in datetime(), Ninox uses 00:00. If you pass a number to time(any), Ninox treats it as Unix time in milliseconds.

Let’s take a look at some examples:

date(2026, 12, 31)

Creates the date 31 December 2026.

date(appointment)

Returns the date part from the appointment date/time field.

date(2026, 8, 0)

Returns 31 July 2026. Use 0 as the day to get the last day of the previous month.

date(1617873118285)

Converts the Unix timestamp in milliseconds into a date value.

time()

Returns the current local time.

time(endof(appointment))

Returns the time part from the end of the appointment field.

time(14, 30)

Creates the time value 14:30.

time(14, 30, 45)

Creates a time value with seconds.

time(14, 30, 45, 125)

Creates a time value with milliseconds.

datetime(2026, 4, 22)

Creates a local timestamp for 22 April 2026 at 00:00.

datetime(2026, 4, 22, 9)

Creates a local timestamp for 22 April 2026 at 9:00.

datetime(2026, 4, 22, 9, 30)

Creates a local timestamp for 22 April 2026 at 9:30.

datetime(2026, 4, 22, 9, 30, 45)

Creates the same timestamp like above with 45 seconds.

datetime(date, time)

Combines the date from the field Date and the time from the field Time into one timestamp.

datetime(1617873118285)

Converts a Unix timestamp in milliseconds into a local timestamp.

Tips:

• Use date(year, month, 0) to get the last day of the previous month.

• Use datetime(date, time) when date and time are stored in separate fields.

Convert values to UTC-based timestamps with timestamp()

Use timestamp(any) to convert a time-related value to a UTC-based timestamp.

Use it when you want to:

• Convert a date or datetime to a UTC-based timestamp.

timestamp(any)

• any: a time-related value, or a number that represents Unix time in milliseconds

If the input has no time part, Ninox uses 00:00 related to your local time zone.

Let’s take a look at some examples:

timestamp(1640991540010)

Converts Unix milliseconds into a UTC-based timestamp.

number(timestamp('Date + Time'))

Returns the numeric Unix time in milliseconds for the 'Date + Time' value.

timestamp(format(now(), "x"))

Converts a millisecond value into a timestamp.

Tips:

• Use number(timestamp(...)) when you need the Unix value in milliseconds.

• Use now() when you need the current local timestamp.

Format date and time output

Use format() when you want to display a date, time, timestamp, or appointment as readable text.

This is useful for:

• print layouts

• exported values

format(value, string)

• value: the value you want to format

• string: the pattern of the format as text

Examples:

format(today(), "YYYY-MM-DD")

Returns a value such as 2026-04-22.

format(now(), "dddd, DD MMMM YYYY")

Returns a value such as Wednesday, 23 April 2026.

format(now(), "HH:mm")

Returns a value such as 14:30.

format(now(), "hh:mm a")

Returns a value such as 02:30 pm.

You can also pass a language code as the third argument:

format(today(), "DD MMMM YYYY", "fr")

This returns the formatted date in French.

Common format codes

Use these format codes inside the format pattern:

Format code	Description	Example
YY	Year with 2 digits	21
YYYY	Year with 4 digits	2021
M	Month with 1 or 2 digits	1 ... 12
Mo	Month as an ordinal number	1st ... 12th
MM	Month with 2 digits	01 ... 12
MMM	Month name with 3 letters	Feb
MMMM	Full month name	February
D	Day of month with 1 or 2 digits	1 ... 31
Do	Day of month as an ordinal number	1st ... 31st
DD	Day of month with 2 digits	01 ... 31
d	Weekday number	0 ... 6
do	Weekday number as an ordinal	0th ... 6th
dd	Weekday name with 2 letters	Mo ... Su
ddd	Weekday name with 3 letters	Mon ... Sun
dddd	Full weekday name	Friday
w or W	Calendar week	1 ... 53
Q	Quarter	1 ... 4
l	Short numeric date	6/15/2021
L	Numeric date with leading zeros	06/15/2021
h	Hour in 12-hour format with 1 or 2 digits	1 ... 12
hh	Hour in 12-hour format with 2 digits	01 ... 12
H	Hour in 24-hour format with 1 or 2 digits	0 ... 23
HH	Hour in 24-hour format with 2 digits	00 ... 23
a	am or pm	11:30 pm
m	Minute with 1 or 2 digits	0 ... 59
mm	Minute with 2 digits	00 ... 59
s	Second with 1 or 2 digits	0 ... 59
ss	Second with 2 digits	00 ... 59
x	Unix time in milliseconds	1617873118285
X	Unix time in seconds	1617873118
Z	Time zone offset from UTC	-04:00:00

Tips:

• Combine format codes to build your own output pattern.

• Use HH:mm for 24-hour time.

• Use hh:mm a for 12-hour time.

• Use YYYY-MM-DD when you need a stable, sortable date format.

• Test formatted output with real values before you use it in exports or integrations.

Measure time spans and offsets

Use duration() to measure time spans. Use timeinterval() to create an offset you can add to a date or time.

Measure elapsed time with duration()

Use duration() to calculate a time span from an appointment or between two date and time values.

Use it when you want to:

• Track task runtime.

• Get the length of an appointment from its start and end.

duration(appointment) duration(end, start)

• appointment: the appointment for which Ninox returns the duration

• end: the later value

• start: the earlier value

If the result is longer than 24 hours, Ninox also shows days.

Let’s take a look at some examples:

duration(end, start)

Returns the time span between two datetime fields "End" and "Start".

duration(holiday)

Returns the duration of the appointment field "Holiday".

duration(now(), created_at)

Returns the elapsed time since the record was created.

duration(appointment(date(2026, 3, 27), date(2026, 3, 29)))

Returns a duration of two days.

Count days between two dates with days()

Use days() to return the number of calendar days between two date values.

Use it when you want to:

• Check how many days remain until a deadline.

• Measure a date range in full calendar days.

days(date, date)

• first date: the start date

• second date: the end date

You can use all value types that contain a date.

Let’s take a look at some examples:

days(start, end)

Returns the number of days between the two given dates.

days(date1, date2)

If date1 is 07/02/2026 and date2 is 12/31/2026, the result is 183.

Tips:

• Use days() when you need plain calendar days.

• Use workdays() when weekends should not count.

• Use duration() when you need a time span, not only a day count.

Count business days with workdays()

Use workdays() to count working days between two dates.

Use it when you want to:

• Plan schedules.

• Track delivery windows.

workdays(date, date)

• first date: the start date

• second date: the end date

workdays() counts Monday to Friday as working days.

Public holidays are not considered.

If you start from an appointment, pass start(appointment) and endof(appointment).

Let’s take a look at some examples:

workdays(today() - 13, today() + 6)

Returns 14.

workdays(start(appointment), endof(appointment))

Counts business days across the appointment range.

Create time intervals with timeinterval()

Use timeinterval() to build a reusable duration or convert a time-related value to a duration.

Use it when you want to:

• Convert milliseconds to a duration.

• Turn a time value into a duration.

timeinterval(number)

• number: a time value or a number

If the input is a number, Ninox treats it as a duration in milliseconds.

Unlike duration(), timeinterval() describes a duration by itself. It does not measure the span between two date values.

Let’s take a look at some examples:

timeinterval(60000)

Converts 60000 milliseconds to a duration of one minute.

timeinterval(time(1, 30))

Converts the time value 01:30 into a duration of 1 hour and 30 minutes.

now() + timeinterval(7200000)

Builds a datetime two hours from now.

Tips:

• Use duration() for measured spans.

• Use timeinterval() for planned durations.

Extract date parts

Use these functions to break a date into smaller parts. They are useful for grouping, filtering, and reporting.

Get year, month, and day with year(), month(), and day()

Use these functions when you need one part of a date or timestamp.

year(date) year(appointment) year(timestamp) month(date) month(appointment) month(timestamp) day(appointment) day(date) day(timestamp)

• date: the date from which Ninox returns the requested part

• appointment: an appointment value from which Ninox returns the year, month, or day from the start date

• timestamp: a timestamp from which Ninox returns the requested date part

Let’s take a look at some examples:

year(today())

Returns the current year.

year(endof(appointment))

Returns the year from the end of the appointment field.

month(today())

Returns the current month number.

month(today()) + 3

Adds three to the current month number.

month(appointment)

Returns the month number from the start date of the appointment field.

month(now())

Returns the month number from the current timestamp.

day(date)

Returns the day of the month from the field "Date".

day(1624226400000)

Returns the day from a Unix timestamp.

Tip:

• If you use an appointment and need the end date, wrap it with endof().

Get weekday, week, and quarter with weekday(), week(), and quarter()

Use these functions when calendar periods matter.

weekday(date) weekday(timestamp) weekday(appointment) week(date) week(timestamp) week(appointment) quarter(date)

• date: the date from which Ninox returns the requested calendar value

• timestamp: a timestamp from which Ninox returns the weekday or calendar week

• appointment: an appointment from which Ninox returns the weekday or calendar week of the start date

weekday() returns a number from 0 to 6, where Monday = 0 and Sunday = 6.

weekday() does not consider public holidays.

quarter() returns a number from 1 to 4. If you use an appointment, first choose whether you need the start or end date.

Let’s take a look at some examples:

weekday(today())

Returns the weekday number for today.

weekday(date(2026, 4, 22))

Returns 2 because 22 April 2026 is a Wednesday.

if weekday(date) > 4 then "Weekend" else "Business day" end

Checks whether a date falls on a weekend or a workday.

week(today())

Returns the current week number.

week(now())

Returns the calendar week from the current timestamp.

week(appointment)

Returns the calendar week from the start date of the appointment field.

quarter(today())

Returns the current quarter number.

quarter(date)

Returns the quarter number from the date field.

quarter(start(appointment))

Returns the quarter number from the start of the appointment field.

quarter(endof(appointment))

Returns the quarter number from the end of the appointment field.

Jump to a period end with endof()

Use endof() to return the end of an appointment or the end of a calendar period.

Use it when you want to:

• Get the end timestamp of an appointment.

• Trigger reminders near a deadline.

endof(appointment)

• appointment: the appointment field or result from which Ninox returns the end timestamp

Let’s take a look at some examples:

endof(appointment)

Returns the end timestamp of the appointment field.

format(endof(holiday), "dddd, HH:mm")

Formats the end of the "Holiday" appointment field as readable text.

Build reporting keys and business calculations

Use these functions when you want compact grouping keys or business-friendly date calculations.

Build reporting keys with yearmonth(), yearweek(), and yearquarter()

Use these functions to group records by a period in one value.

Use them when you want to:

• Group invoices by month.

• Build weekly charts.

• Summarize results by quarter.

yearmonth(appointment) yearmonth(date) yearmonth(timestamp) yearweek(appointment) yearweek(date) yearweek(timestamp) yearquarter(appointment) yearquarter(date) yearquarter(datetime) yearquarter(timestamp)

• appointment: an appointment from which Ninox builds the reporting key from the start date

• date: the date from which Ninox builds the reporting key

• timestamp: a timestamp from which Ninox builds the reporting key

yearmonth() returns a string in the format YYYY/MM.

yearweek() returns a string in the format YYYY WW.

yearquarter() returns a string in the format YYYY Qn.

If you use an appointment and need the end date, wrap it with endof().

Let’s take a look at some examples:

yearmonth(today())

Returns a combined year-month key for the current date.

yearmonth(appointment)

Returns a value such as 2021/06 from the start date of the "Appointment" field.

yearmonth(endof(appointment))

Returns the year and month from the end of the "Appointment" field.

yearweek(today())

Returns a combined year-week key for the current date.

yearweek(appointment)

Returns a value such as 2021 23 from the start date of the appointment field.

yearweek(endof(appointment))

Returns the year and week from the end of the appointment field.

yearquarter(today())

Returns a combined year-quarter key for the current date.

yearquarter(appointment)

Returns a value such as 2021 Q2 from the start date of the appointment field.

yearquarter(endof(appointment))

Returns the year and quarter from the end of the appointment field.

Calculate age with age()

Use age(date) to return the number of full years between a date and the current date.

Use it when you want to:

• Show a person’s age.

The current date is always used for this calculation.

age(date)

• date: the reference date from which Ninox calculates the number of full years

Let’s take a look at some examples:

age(date_of_birth)

Returns the age in full years from the date in date_of_birth.

age(date(1976, 4, 12))

Returns the number of full years since 12 April 1976, based on today’s date.

Common date recipes

These short patterns cover common date and time tasks in Ninox.

Flag overdue records

if today() > due_date then "Overdue" else "On time" end

Compares the current date with a due date.

Measure SLA time since creation

duration(now(), created_at)

Measures the elapsed time since the record was created.