Handle dates, timestamps, and time zones

26R1 reference · Documentation-based tutorial draft · Not executed in IFS

Identify what the value means

A date, a local wall-clock time, and an instant with an offset are different contracts. Record the attribute’s data type and whether its metadata uses server time, site time, or no time-zone awareness.

Do not add a fixed offset to every timestamp. Daylight-saving changes and sites in different zones make that unreliable.

Follow the documented conversion boundaries

Boundary	Reference behavior
Time-zone-aware initiating request	Timestamp inputs converted to the relevant server/site time
Event input	Uses the entity’s server/site-time interpretation
API Task inside the workflow	Operates with time-zone-unaware workflow values
REST Task	Passes timestamps as supplied; no automatic conversion
Cascading workflow	Values already converted should not be converted again

Workflow Command conversion has format and context requirements, including the site context for site-aware data. A directly invoked workflow REST payload likewise needs the documented request header and typed timestamp fields. An ISO-looking string alone does not establish the intended conversion.

A diagnostic worksheet

For each timestamp capture:

Attribute:
Business meaning:
Source value including offset:
Source metadata / site:
Value observed at workflow entry:
Value sent to API or REST task:
Persisted value:
Value displayed to each test user:

This is a worksheet, not an import format.

Test the boundaries

Use one timestamp near midnight, one that crosses a date boundary between source and target zones, and cases around daylight-saving changes for affected sites. Test a time-zone-aware request and the supported legacy/unaware path separately.

Compare the business meaning, not just formatted strings. Two differently displayed timestamps can represent the same instant; two identical local strings can represent different instants.

Date-only input should not unexpectedly shift to the prior or next day.

Review upgrades explicitly

The API Task’s Timestamp Corrected for Backward Compatibility option records that a workflow has been reviewed for APIs requiring time-zone-aware behavior. Review and correct the mapping before enabling it on an upgraded workflow; do not tick it merely to clear a warning.

For literal date/datetime formats accepted by workflow fields, consult the release FAQ and the specific input contract. Avoid assuming browser JavaScript date parsing matches IFS formatting.

Acceptance evidence: captured values at each boundary, the applicable server/site zone, and correct persisted/displayed results across the chosen test cases.

Step-by-step: reproduce a one-hour timestamp discrepancy

1. Choose a specific instant and capture each boundary

Pick one fictional appointment and record its original string including offset, intended site zone, property metadata, raw API request, value at workflow entry, outgoing task value, persisted value, and UI display. Use the worksheet above. Do not start by adding/subtracting an hour.

For example, two different UTC instants can both display as 02:30 in Stockholm when clocks move back. A date-only field has a different meaning and should not be forced into this timestamp exercise.

2. Run a local daylight-saving fixture

Save this as time-boundaries.mjs and run node time-boundaries.mjs:

const display = new Intl.DateTimeFormat('en-GB', {
  timeZone: 'Europe/Stockholm', hour: '2-digit', minute: '2-digit', hourCycle: 'h23'
});
const fixtures = [
  ['2026-03-29T00:30:00Z', '01:30'],
  ['2026-03-29T01:30:00Z', '03:30'],
  ['2026-10-25T00:30:00Z', '02:30'],
  ['2026-10-25T01:30:00Z', '02:30']
];
for (const [instant, expected] of fixtures) {
  const actual = display.format(new Date(instant));
  if (actual !== expected) throw new Error(`${instant}: ${actual} != ${expected}`);
  console.log(`${instant} -> ${actual} Europe/Stockholm`);
}

This is a Node.js diagnostic using its time-zone database, not code to paste into an IFS Script Task. It demonstrates why storing only a local clock string loses information. Record the runtime/time-zone data version when using such fixtures in long-lived regression tests.

3. Inspect the IFS property’s time-zone contract

In API Explorer/metadata, determine whether the property is date-only, timestamp, server-time-aware, or site-time-aware. For a site-aware value, identify the site source. Check the actual request’s time-zone headers/typed fields against the release’s time-zone documentation.

Capture the value entering the workflow before adding conversions. An input already converted by the initiating request must not receive a second conversion just because the UI displays it differently.

4. Compare the task boundary

Use Inspect to record the variable immediately before the IFS API Task or external REST Task. For REST, explicitly serialize the instant/offset required by the external service; REST does not infer your business time zone.

For IFS API Tasks, follow the documented workflow/API conversion rules and review Timestamp Corrected for Backward Compatibility where applicable. Do not enable it as a trial-and-error fix without comparing the input and persisted output.

5. Resolve ambiguous local input deliberately

If an external Java service receives a local date/time plus a ZoneId, inspect zone.getRules().getValidOffsets(localDateTime): zero offsets indicates a gap, one an ordinary time, and two an overlap. Reject or ask for an explicit offset in the ambiguous cases according to the business rule; do not accept a library’s automatic adjustment without review.

Preserve the regional zone when future scheduling depends on local civil time. Preserve an instant/offset when the business meaning is an already observed event. These are different storage contracts.

6. Retest and remove the diagnostic changes

Run normal-day, near-midnight, spring-gap, and autumn-overlap cases through the actual trigger and task. Compare both the stored instant and display for two users/sites where applicable. Confirm date-only values do not shift days.

Remove temporary log statements and restore the lab workflow after recording the result. Keep the fixture and boundary worksheet with the change so a later release can be checked without rediscovering the discrepancy.

Java reference: ZoneRules valid offsets.

Release sources

Check daylight-saving gaps and overlaps

When an external Java service supplies a time, distinguish a local date/time from an instant. During a daylight-saving transition, a local time may occur twice or not occur at all. A fixed UTC offset captures an offset at a moment; it is not a replacement for a region’s changing timezone rules.

For a fictional inspection appointment, retain the intended regional zone and define how ambiguous or nonexistent local times are resolved before converting to an instant. Record observation time separately from receipt time. Do not fix a discrepancy by adding one hour globally: that can break normal dates and other regions.

Use three fixtures around each relevant transition: before, inside the gap/overlap, and after. Compare the source instant, serialized offset, workflow input, and displayed result. If the value is a business date without a time of day, preserve that meaning rather than applying an arbitrary midnight conversion. Apply these checks to weather context and scheduled work.