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

salesforce.timezone.fields=SystemModstamp, CreatedDate,LastModifiedDate

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

Account.salesforce.timezone.fields=SystemModstamp,CreatedDate,Custom_Date__c

Event.salesforce.timezone.fields=ActivityDateTime

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

salesforce.timezone=America/Chicago

# Default fields (all tables)

salesforce.timezone.fields=SystemModstamp,CreatedDate,LastModifiedDate

# Account override

Account.salesforce.timezone.fields=SystemModstamp,CreatedDate,Custom_Date__c

# Event override

Event.salesforce.timezone.fields=ActivityDateTime

---

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