Salesforce Timestamp Timezone Conversion
For Global level all need to be added into system properties. For profile level add it to config properties.
Overview
Salesforce APIs return all datetime fields in UTC format (e.g., 2024-01-15T10:30:00.000Z).
This feature introduces an opt-in, property-driven timezone conversion mechanism that allows storing timestamps in a client-defined IANA timezone within the target system.
Default behavior (backward compatible):
Feature disabled
No runtime overhead
No schema or behavioral changes
The feature activates only when explicitly configured.
Configuration Model
Timezone conversion is controlled entirely via properties.
Target Timezone (Mandatory to Enable)
salesforce.timezone=America/Chicago
Rules:
Must be a valid IANA Timezone ID
If absent or blank → feature is fully disabled
Invalid timezone → startup failure (fail-fast validation)
Validation occurs during connector initialization
Global Field List
Behavior:
Comma-separated Salesforce field names
Case-insensitive (systemmodstamp = SystemModstamp)
Applies to all tables
Used as a fallback if no per-table override exists
Per-Table Override
Format
<TableName>.salesforce.timezone.fields=<field1>,<field2>,...
Important:
Per-table configuration replaces the global list
It does not merge
Case-insensitive (table + fields)
If absent → global field list is used
Example Configuration
# Enable conversion to US Central Time
# Default fields (all tables)
# Account override
# Event override
Supported IANA Timezone Examples
Timezone ID
Description
America/New_York
US Eastern (EST/EDT)
America/Chicago
US Central (CST/CDT)
America/Denver
US Mountain (MST/MDT)
America/Los_Angeles
US Pacific (PST/PDT)
America/Phoenix
Arizona (No DST)
Europe/London
GMT / BST
Europe/Paris
CET / CEST
Asia/Kolkata
IST
Asia/Tokyo
JST
Australia/Sydney
AEST / AEDT
Runtime Behavior
Conversion Flow
Salesforce returns a timestamp in UTC
System checks if:
The timezone property is set
Field is configured for conversion
Timestamp converted using java.time.ZoneId
Stored in the target database in the converted timezone
All other values pass through unchanged.
Incremental / Delta Sync Safety
During incremental sync:
The stored last-synced timestamp is in the converted timezone
The system automatically converts it back to UTC
SQL queries are executed correctly in UTC
This guarantees:
Accurate delta detection
No duplicate or missed records
No manual user intervention required
Daylight Saving Time (DST)
Handled automatically by the java. time.ZoneId engine.
Example: America/Chicago
Season
UTC Offset
Winter
UTC - 6 (CST)
Summer
UTC - 5 (CDT)
No manual DST logic required.
Scope & Exclusions
The following are intentionally not affected:
Not Converted
Date-only fields (2024-01-15)
Fields not in the configured list
Non-datetime string values
User-defined .filter property values (SOQL expects UTC)
Safety Guard
Date-only fields are skipped via format/length detection.
Error Handling & Validation
Scenario
Behavior
Invalid timezone ID
Startup failure (fail-fast)
Timezone set but no fields configured
WARNING at startup
Unparseable timestamp
Returned unchanged + FINE log
Feature not configured
Fully disabled, zero overhead
Architectural Characteristics
Property
Behavior
Backward compatible
Yes
Runtime overhead
Only when enabled
Thread safe
Yes (ZoneId immutable)
CDC compatible
Yes
Multi-table safe
Yes
Multi-timezone per job
No (single timezone per job)
Recommended Usage Patterns
Use When:
Reporting systems expect business-local time
Data warehouse consumers require localized timestamps
Compliance mandates storage in the regional timezone
Avoid When:
Downstream systems expect UTC
Cross-region aggregation depends on uniform t
Last updated