# 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

{% code overflow="wrap" %}

```
salesforce.timezone.fields=SystemModstamp, CreatedDate,LastModifiedDate
```

{% endcode %}

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

{% code overflow="wrap" %}

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

{% endcode %}

{% code overflow="wrap" %}

```
Event.salesforce.timezone.fields=ActivityDateTime
```

{% endcode %}

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

{% code overflow="wrap" %}

```
salesforce.timezone=America/Chicago
```

{% endcode %}

\# Default fields (all tables)

{% code overflow="wrap" %}

```
salesforce.timezone.fields=SystemModstamp,CreatedDate,LastModifiedDate
```

{% endcode %}

\# Account override

{% code overflow="wrap" %}

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

{% endcode %}

\# Event override

{% code overflow="wrap" %}

```
Event.salesforce.timezone.fields=ActivityDateTime
```

{% endcode %}

***

### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mydbsync.com/cloud-replication-main/source-setup/salesforce/salesforce-timestamp-timezone-conversion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.