Timezone Handling

Overview

WFM (Workforce Management) applications handle shift management, timesheet submission/approval, candidate availability, and more. From version 4.0 onwards, the platform introduces configurable and consistent timezone support across all apps via structured metadata records and context-aware display logic.

This documentation outlines how timezones are managed, how to configure them using context providers, and what behavior to expect under various scenarios.

Timezone Handling in the Apps

🕒 How Time is Stored

All date and time values are stored in UTC (Coordinated Universal Time) in the system. This ensures consistency across users in different time zones.

When users view, enter, or edit times, the system converts times between UTC and their preferred timezone, depending on your selected configuration.

Applications & Configuration

Each WFM application is configured using a JSON-based context definition provided through metadata records:

Application	Description	Configuration Type
Scheduler	Internal UI for recruiters to manage shifts	`Scheduling Context Provider`
Mobile App	External app for candidates to manage shifts, availability, and expenses	`Component Clock Configuration` (Type__c = `Clock In / Out Component`)
Timesheet Submission	UI for candidates to submit timesheets and expenses	`Component Clock Configuration` (Type__c = `Timesheet Submission`)
Timesheet Approval	UI for clients to approve timesheets and expenses	`Component Clock Configuration` (Type__c = `Timesheet Approval`)
Client Shift Manager	Simplified UI for clients to create and track shift requests	`Component Clock Configuration` (Type__c = `Client Shift Manager`)

Timezone Configuration Schema

A sample JSON configuration:

{
  "timezonePreference": "client",
  "firstDay": 0,
  "is24Hour": true,
  "schedulables": {
    "shift": {
      "objectType": "b3s__Shift__c",
      "startFieldPath": "b3s__Scheduled_Start_Time__c",
      "endFieldPath": "b3s__Scheduled_End_Time__c",
      "actualStartFieldPath": "b3s__Actual_Start_Time__c",
      "actualEndFieldPath": "b3s__Actual_End_Time__c",
      "absoluteStartFieldPath": "b3s__Absolute_Start_Time__c",
      "absoluteEndFieldPath": "b3s__Absolute_End_Time__c",
      "siteTimezoneFieldPath": "b3s__Site__r.b3s__Site_Timezone__c",
      "lookBackExtendDays": 1,
      "lookForwardExtendDays": 1,
      "title": [...]
    },
    ...
  }
}

Global Settings

`timezonePreference`

Controls which timezone context to use when rendering datetime values.

"client": Uses the timezone of the client device accessing the UI. Ideal for mobile-first deployments.
"user": Uses the Salesforce user's configured timezone regardless of device location.

Example Behavior:

timezonePreference = "client": A recruiter using the Scheduler in London sees times in London timezone. If they travel to Amsterdam, times adjust to Amsterdam time.
timezonePreference = "user": If their Salesforce timezone is London, times remain in London time, regardless of actual location.

`firstDay`

Configures the first day of the week in calendar-style UIs.

0: Sunday
1: Monday (default)

`is24Hour`

Controls the formatting style of time displays:

true: Times shown in 24-hour format (14:30)
false: Times shown in 12-hour format with AM/PM (2:30 PM) (default)

Schedulable-Specific Timezone Support

Each schedulable (e.g., Shift, Break, Expense, Request) can define a siteTimezoneFieldPath. This field defines the timezone context for that specific object. If present, it enables dual-timezone rendering:

User Timezone: Based on timezonePreference
Target Timezone: From the siteTimezoneFieldPath

Example

A user in New York (EDT) creates a shift for San Francisco (PDT).

Display:

Start Time: 09:00 (PDT)

Site Time: 06:00 (EDT)

Default Timezone Field Paths

Schedulable	Field Path
`shift`	`b3s__Site__r.b3s__Site_Timezone__c`
`break`	`b3s__Shift__r.b3s__Site__r.b3s__Site_Timezone__c`
`invitation`	`b3s__Shift__r.b3s__Site__r.b3s__Site_Timezone__c`
`expense`	`b3s__Contact__r.b3s__Site_Timezone__c`
`request`	`b3s__Contact__r.b3s__Timezone__c` (candidate's home timezone)

Title Field Timezone Support

Title field definitions can now include siteTimezoneFieldPath, allowing timezone-specific formatting of UI-rendered labels.

"title": [
    {
        "label": "Shift Times",
        "fieldPath": "b3s__Shift__r.b3s__Scheduled_Start_Time__c:b3s__Shift__r.b3s__Scheduled_End_Time__c",
        "formatter": "startEnd",
        "siteTimezoneFieldPath": "b3s__Shift__r.b3s__Site__r.b3s__Site_Timezone__c",
        "hideIfNull": false
    },
    {
        "label": "Shift Times With Date",
        "fieldPath": "b3s__Shift__r.b3s__Scheduled_Start_Time__c:b3s__Shift__r.b3s__Scheduled_End_Time__c",
        "formatter": "startEndWithDate",
        "siteTimezoneFieldPath": "b3s__Shift__r.b3s__Site__r.b3s__Site_Timezone__c",
        "hideIfNull": false
    },
    {
        "label": "Date Invited",
        "fieldPath": "CreatedDate",
        "formatter": "dateTime",
        "siteTimezoneFieldPath": "b3s__Shift__r.b3s__Site__r.b3s__Site_Timezone__c",
        "hideIfNull": false
    },
    //Default timezone on the schedulable will be used
    {
        "label": "Date Invited",
        "fieldPath": "CreatedDate",
        "formatter": "dateTime",
        "hideIfNull": false
    },
    ...
]

If siteTimezoneFieldPath is omitted, the system defaults to the timezonePreference.

Formatter Enhancements

Two new formatters have been introduced:

`startEnd`

Requires two colon-separated field paths (start and end).
Formats: HH:mm - HH:mm

`startEndWithDate`

Requires two colon-separated field paths.
Formats: yyyy-mm-dd HH:mm - HH:mm

UI Display Behavior

Scheduler & Candidate App Calendars

The rendering logic for event times in calendar views behaves as follows:

1. Same Timezone

timezonePreference = client
Current location = London
Shift site timezone = London

Display:

09:00 - 17:00

2. Different Timezone

timezonePreference = client
Current location = London
Shift site timezone = Amsterdam

Display:

09:00 - 17:00

10:00 - 18:00 (GMT+2)

3. Different User Timezone

timezonePreference = client
Current location = London
Salesforce User timezone = Europe/Sofia
Shift site timezone = India

Display:

09:00 - 17:00 (GMT+1)

13:30 - 21:30 (GMT+5:30)

Note:

We only append timezone names (e.g., GMT+1) when:

The Salesforce User's timezone is different from the device’s current location
timezonePreference does not override this by locking to the user timezone

Summary

Release 4.0 introduces flexible, granular, and consistent timezone support across all WFM components. Admins can now:

Choose whether to rely on the device or user-configured timezone
Configure field-level timezone behavior
Present time data in dual-timezone mode for clarity and accuracy
Customize week start day and time display format

Proper configuration of timezonePreference and siteTimezoneFieldPath will ensure correct and predictable behavior across all user interfaces.

Important

In order for siteTimezoneFieldPath setting to work correctly, ensure that you load the b3s__Site_Timezone__c field in the Site Loader.

{
    name: "sites",
    objectName: "b3o__Site__c",
    filterRecordsBy: function () {
        return 'Id != null';
    },
    groupRecordsBy: "Id",
    fieldToLoad: ['Name', 'b3o__City__c', 'b3o__Street_Address__c', 'CreatedDate', 'b3s__Site_Timezone__c'],
    filteringItems: function () {
        return [
            `'${contextRecordId}'`
        ]
    }
}

Timezone Handling

Contents

Overview