# 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