system.date

system.date holds time helpers. They run inside the script's own engine, cost no gateway call, and are available in every kind of script, including expression tags. See The system API for the rest of system.

Times

Every function that takes a time accepts a ScadexTime:

type ScadexTime = Date | number | string;   // a Date, epoch milliseconds, or ISO 8601 text

A string or number is turned into a Date with JavaScript's new Date(...); text that is not a time throws Not a time: <text>. Functions that return a time return a new Date, so the one passed in is never changed. Tag values of type DateTime reach a script as ISO 8601 strings, which these functions accept as they are.

Local time means the time zone of the gateway process, which is the zone system.gateway.info().timeZone names.

now

now(): Date

The current time.

format

format(date: ScadexTime, pattern?: string, utc?: boolean): string

Parameter	Type	Meaning
date	time	What to format. Required
pattern	string	The pattern; yyyy-MM-dd HH:mm:ss when left out
utc	boolean	Format in UTC rather than the gateway's time zone

The pattern's tokens are yyyy (year, 4 digits), MM (month), dd (day), HH (hour, 24-hour), mm (minute), ss (second) and SSS (millisecond). Every token is zero-padded. Other characters pass through unchanged, so dd/MM/yyyy and HH:mm work; there is no token for the 12-hour clock, the weekday or the month name.

system.date.format(system.date.now());                       // "2026-11-08 13:05:09"
system.date.format(tag('Line1.LastStart'), 'HH:mm');           // "06:30"
system.date.format(1762606800000, 'yyyy-MM-dd HH:mm:ss', true); // in UTC

parse

parse(text: string): Date

A Date from text, with new Date(text) rules: ISO 8601 such as 2026-11-07T08:00:00Z is safe; other formats depend on the JavaScript engine. Throws Not a time: <text> when it cannot be read.

Arithmetic

addSeconds, addMinutes, addHours

addSeconds(date: ScadexTime, seconds: number): Date
addMinutes(date: ScadexTime, minutes: number): Date
addHours(date: ScadexTime, hours: number): Date

The time moved by that many seconds, minutes or hours (negative moves back). These add exact milliseconds.

addDays

addDays(date: ScadexTime, days: number): Date

The time moved by that many calendar days in local time, so across a daylight-saving change the clock time is kept and the day is 23 or 25 hours long.

secondsBetween

secondsBetween(from: ScadexTime, to: ScadexTime): number

Seconds from from to to, negative when to is earlier. Fractions are kept.

var since = system.date.secondsBetween(tag('Line1.StartedAt'), system.date.now());
return system.util.round(since / 60, 0) + ' min';

startOfDay

startOfDay(date: ScadexTime): Date

Midnight at the start of that day, in local time.

toMillis

toMillis(date: ScadexTime): number

Epoch milliseconds, the form system.tag.history and system.alarm.history return times in and accept in their filters.

Example

Yesterday as a period for a history query, in the gateway's zone:

var today = system.date.startOfDay(system.date.now());
var from = system.date.addDays(today, -1);
var points = system.tag.history('Plant.Tank1.Level', { from: from, to: today, maxPoints: 2000 });
return {
  day: system.date.format(from, 'yyyy-MM-dd'),
  first: points.length ? system.date.format(points[0].t, 'HH:mm:ss') : null,
  count: points.length,
};