To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Central date and time service for templates and GraalJS scripts, registered as the "dateManagerV1" application service and reachable in scripts via services.dateManagerV1. Converts between the date representations used around the platform (String, Date, Long epoch millis, Instant, ZonedDateTime, Milton Resource) and formats or parses them using the current user's or organisation's timezone and locale, falling back to a domain-based default when neither is set. Also provides simple date arithmetic, duration calculation and human-readable relative time text. The class name is versioned so a future breaking change can be introduced as a new class without disturbing existing templates.
Group: Managers
Properties
| Property | Returns | Description |
|---|---|---|
| defaultDateOnlyFormatter | TemporalParser | The registered parser that is the locale default for formatting date-only values, resolved for the current user's or organisation's locale. |
| defaultDateTimeFormatter | TemporalParser | The registered parser that is the locale default for formatting date-time values, resolved for the current user's or organisation's locale. |
| defaultLocale | Locale | |
| defaultTimeZone | ZoneId | |
| locale | Locale | The locale currently in effect, taken preferentially from the current user's profile, then the organisation, then the server's domain-based default. |
| parsers | List<TemporalParser> | The full, immutable list of date and date-time parsers this service tries in turn when parsing free-text input, in priority order. |
| timezoneId | String | The id of the timezone currently in effect, taken preferentially from the current user's profile, then the organisation, then the server's domain-based default. |
| uSDefaultLocale | boolean | Whether the domain-based default locale for the current request resolves to US English. |
Methods
formatAge(Object o) · formatPeriod(Object multiples, Object timeUnits) · getParsers() · addHours(Object dateTime, int hours) · addMonths(Object dateTime, int months) · toDate(Object dateTime) · getDayOfWeek(Object o) · getDateTime(Object o) · getDateTime(Object o, ZoneId zone, Locale l) · findTimeZone(String id) · parseDate(String s) · parseDate(String s, String timezone, String localeId) · formatDateTime(Object o) · formatWithPattern(Object date, String pattern) · formatDateISO8601(Object o) · formatDateISO8601(Object o, String timezone, String localeId) · formatDateTime(Object o, String timezone, String localeId) · formatDateTime(Object o, ZoneId zone, Locale l) · formatDate(Object o) · formatDate(Object o, String timezone, String localeId) · formatDate(Object o, ZoneId zone, Locale l) · dateTimePattern(String context) · datePattern(String context) · getDefaultDateTimeFormatter() · getDefaultDateOnlyFormatter() · isUSDefaultLocale() · getTimezoneId() · getLocale() · startOfDay(ZonedDateTime zdt) · endOfDay(ZonedDateTime zdt) · calculateDuration(ZonedDateTime startDate, ZonedDateTime endDate, String type)
formatAge(Object o)
Returns: String
Renders a human-friendly relative time description for the given date, such as "Just now", "5 minutes ago", "in 3 days" or "2 months ago". Accepts anything convertible via getDateTime, and returns an empty string when the input is null.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource), or null |
formatPeriod(Object multiples, Object timeUnits)
Returns: String
Formats a count and a period unit code as a short display phrase, using singular wording for a count of one, for example "day" or "3 days". Recognised unit codes are d (day), w (week), m (month) and y (year); any other code is returned unchanged. Returns an empty string if either argument is missing or blank.
| Parameter | Description |
|---|---|
multiples | the number of periods, coerced to an integer |
timeUnits | the period unit code (d, w, m or y) |
getParsers()
Returns: List<TemporalParser>
The full, immutable list of date and date-time parsers this service tries in turn when parsing free-text input, in priority order.
addHours(Object dateTime, int hours)
Returns: ZonedDateTime
Adds the given number of hours to a date-like value, converting it to a ZonedDateTime first via getDateTime.
| Parameter | Description |
|---|---|
dateTime | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
hours | the number of hours to add, may be negative to subtract |
addMonths(Object dateTime, int months)
Returns: ZonedDateTime
Adds the given number of months to a date-like value, converting it to a ZonedDateTime first via getDateTime.
| Parameter | Description |
|---|---|
dateTime | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
months | the number of months to add, may be negative to subtract |
toDate(Object dateTime)
Returns: Date
Converts a date-like value to a Date. Date, ZonedDateTime and Long (epoch millis) inputs are converted directly; anything else is first resolved via getDateTime. Returns null if the input is null, empty, or cannot be resolved to a date.
| Parameter | Description |
|---|---|
dateTime | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
getDayOfWeek(Object o)
Returns: int
Returns the day of the week for the given date-like value, converting it first via getDateTime, where 1 is Sunday and 7 is Saturday.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
getDateTime(Object o)
Returns: ZonedDateTime
Converts a date-like value to a ZonedDateTime using the current user's or organisation's timezone and locale, falling back to the server's domain-based default when neither is set. This is the general-purpose conversion method most other formatting and arithmetic methods on this service build on.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource), or null |
getDateTime(Object o, ZoneId zone, Locale l)
Returns: ZonedDateTime
Converts a date-like value to a ZonedDateTime in the given zone, parsing a String with the given zone and locale, or resolving the current user's or organisation's zone when zone is null. Supports ZonedDateTime, Instant, Date, Milton Resource (uses its modified date), String, and any value convertible to a long epoch millis value.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource), or null |
zone | the timezone to apply, or null to use the current user's or organisation's timezone |
l | the locale to use when parsing a String value, or null to use the current user's or organisation's locale |
findTimeZone(String id)
Returns: ZoneId
Resolves a timezone id to a ZoneId, correcting the legacy Europe/Kyiv id to the java.time-recognised Europe/Kiev before lookup.
| Parameter | Description |
|---|---|
id | a timezone id, for example Australia/Sydney |
parseDate(String s)
Returns: ZonedDateTime
Parses a date or date-time String using the current organisation's timezone and locale.
| Parameter | Description |
|---|---|
s | the text to parse |
parseDate(String s, String timezone, String localeId)
Returns: ZonedDateTime
Parses a date or date-time String, trying each registered parser in turn, first checking if the whole String is a plain epoch millis value. Falls back to the current user's or organisation's timezone and locale when timezone or localeId is blank.
| Parameter | Description |
|---|---|
s | the text to parse |
timezone | a timezone id to parse relative to, or blank to use the current default |
localeId | a locale tag to parse with, or blank to use the current default |
formatDateTime(Object o)
Returns: String
Formats a date-like value as date and time text using the current user's or organisation's timezone and locale.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
formatWithPattern(Object date, String pattern)
Returns: String
Format the given date-like object with the given pattern
| Parameter | Description |
|---|---|
date | - an object which either is or can be converted to a ZonedDateTime (using getDateTime) |
pattern | - a String which describes a pattern for displaying the date and/or time, eg dd_MM_yyyy |
formatDateISO8601(Object o)
Returns: String
Formats a date-like value as an ISO 8601 date-time string with millisecond precision and timezone offset, using the current organisation's timezone and locale where available, or the current user's or organisation's default otherwise.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
formatDateISO8601(Object o, String timezone, String localeId)
Returns: String
Formats a date-like value as an ISO 8601 date-time string with millisecond precision and timezone offset, in the given timezone and locale.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
timezone | a timezone id to format in, or blank to use the current default |
localeId | a locale tag to format with, or blank to use the domain-based default locale |
formatDateTime(Object o, String timezone, String localeId)
Returns: String
Formats a date-like value as date and time text in the given timezone and locale.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
timezone | a timezone id to format in, or blank to use the current user's or organisation's timezone |
localeId | a locale tag to format with, or blank to use the current user's or organisation's locale |
formatDateTime(Object o, ZoneId zone, Locale l)
Returns: String
Formats a date-like value as date and time text in the given zone and locale, using the locale's default date-time pattern.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
zone | the timezone to format in, or null to use the current user's or organisation's timezone |
l | the locale whose default date-time pattern is used, or null to use the current user's or organisation's locale |
formatDate(Object o)
Returns: String
Formats a date-like value as date-only text using the current user's or organisation's timezone and locale.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
formatDate(Object o, String timezone, String localeId)
Returns: String
Formats a date-like value as date-only text in the given timezone and locale.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
timezone | a timezone id to format in, or blank to use the current user's or organisation's timezone |
localeId | a locale tag to format with, or blank to use the current user's or organisation's locale |
formatDate(Object o, ZoneId zone, Locale l)
Returns: String
Formats a date-like value as date-only text in the given zone and locale, using the locale's default date-only pattern.
| Parameter | Description |
|---|---|
o | a date-like value (String, Date, Long epoch millis, ZonedDateTime, Instant or Resource) |
zone | the timezone to format in, or null to use the current user's or organisation's timezone |
l | the locale whose default date-only pattern is used, or null to use the current user's or organisation's locale |
dateTimePattern(String context)
Returns: String
The locale's default date-time display pattern, either as a client-side (JavaScript) pattern string or a Java DateTimeFormatter pattern string.
| Parameter | Description |
|---|---|
context | "js" for the client-side pattern, or any other value for the Java pattern |
datePattern(String context)
Returns: String
The locale's default date-only display pattern, either as a client-side (JavaScript) pattern string or a Java DateTimeFormatter pattern string.
| Parameter | Description |
|---|---|
context | "js" for the client-side pattern, or any other value for the Java pattern |
getDefaultDateTimeFormatter()
Returns: TemporalParser
The registered parser that is the locale default for formatting date-time values, resolved for the current user's or organisation's locale.
getDefaultDateOnlyFormatter()
Returns: TemporalParser
The registered parser that is the locale default for formatting date-only values, resolved for the current user's or organisation's locale.
isUSDefaultLocale()
Returns: boolean
Whether the domain-based default locale for the current request resolves to US English.
getTimezoneId()
Returns: String
The id of the timezone currently in effect, taken preferentially from the current user's profile, then the organisation, then the server's domain-based default.
getLocale()
Returns: Locale
The locale currently in effect, taken preferentially from the current user's profile, then the organisation, then the server's domain-based default.
startOfDay(ZonedDateTime zdt)
Returns: ZonedDateTime
Returns a copy of the given ZonedDateTime set to the very start of its day (00:00:00.000000000), in the same zone.
| Parameter | Description |
|---|---|
zdt | the ZonedDateTime to adjust |
endOfDay(ZonedDateTime zdt)
Returns: ZonedDateTime
Returns a copy of the given ZonedDateTime set to the very end of its day (23:59:59.999999999), in the same zone.
| Parameter | Description |
|---|---|
zdt | the ZonedDateTime to adjust |
calculateDuration(ZonedDateTime startDate, ZonedDateTime endDate, String type)
Returns: long
Calculates the duration between the start and finish dates in the specified duration type.
| Parameter | Description |
|---|---|
startDate | the start date and time as a {@code ZonedDateTime} |
endDate | the end date and time as a {@code ZonedDateTime} |
type | the type of duration to calculate. Must be a valid {@code ChronoUnit} |
© 2025 Kademi Ltd