SAP Knowledge Base Article - Public

3020341 - Behavior of Date Fields in ODATA API - Recruiting Management

Symptom

This article describes the general behavior of Recruiting custom date fields when upserted and queried via ODATA API.

"Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental."

Environment

SAP SuccessFactors Recruiting Management

Resolution

The samples in this document are from a DC 8 instance (UTC-5) and a DC 12 instance (UTC+1). The upserted date fields are in millisecond format.

A. Upserting the custom Date Field

The system only records the date part of an upserted date/time value. This is a system limitation.

Upserted Payload on a DC 8 instance:

{

"customDate":"/Date(1608073188000)/",
"__metadata":{
"type": "SFOData.JobApplication",
"uri": "JobApplication(applicationId=1628)"
 }
}

Data Center: DC 8 (UTC-5)
Upserted Date: /Date(1608073188000)/
Expected Date: Tue Dec 15 2020 22:59:48 GMT+0000 (Greenwich Mean Time)
Actual Stored Date: Tue Dec 15 2020 00:00:00

In this example, when customDate is upserted in millisecond format as /Date(1608073188000)/, the system only actually records the date part (Tue Dec 15 2020) and ignores the time part (22:59:48). The time is stored in the system as 00:00:00.

B. Recording the Custom Date Field

The system records the date value and is tagged with the Data Center's timezone.

Following the example above, the upserted date /Date(1608073188000)/ is stored as Tue Dec 15 2020 00:00:00 UTC-5, when upserted on a DC 8 instance because the DC 8 timezone is UTC-5. 

Data Center: DC 8 (UTC-5)
Upserted Date: /Date(1608073188000)/
Expected Date: Tue Dec 15 2020 22:59:48 GMT+0000 (Greenwich Mean Time)
Actual Stored Date: Tue Dec 15 2020 00:00:00 UTC-5

If the same date is upserted on a DC 12 instance, the recorded timezone would be UTC+1 instead. The upserted date /Date(1608073188000)/ will be stored as Tue Dec 15 2020 00:00:00 UTC+1.

Upserted Date: /Date(1608073188000)/
Actual Stored Date in DC 8: Tue Dec 15 2020 00:00:00 UTC-5
Actual Stored Date in DC 12: Tue Dec 15 2020 00:00:00 UTC+1

Note: 

a. The time part of the value is always 00:00:00 since the system only records the date part and ignores the time part.

b. There is no conversion happening when the system records the date. The system merely saves the date part, ignores the time part (i.e., 00:00:00), and adds the timezone of the Data Center where the instance is.  

C. Querying the Custom Date Field

Custom date fields when queried are converted to UTC timezone.

Following the examples above, the stored dates are converted to UTC before being returned in the query.

Upserted Date: /Date(1608073188000)/
Actual Stored Date in DC 8: Tue Dec 15 2020 00:00:00 UTC-5
Actual Stored Date in DC 12: Tue Dec 15 2020 00:00:00 UTC+1

DATA CENTER 8
Actual Stored Date: Tue Dec 15 2020 00:00:00 UTC-5
Queried Date: Tue Dec 15 2020 05:00:00 UTC

Stored date vs Queried Date: Queried date becomes 05:00 AM December 15 because we added 5 hours from UTC-5 to get the UTC conversion (as UTC-5 is 5 hours behind UTC).

DATA CENTER 12
Actual Stored Date: Tue Dec 15 2020 00:00:00 UTC+1
Queried Date: Tue Dec 14 2020 23:00:00 UTC+1

Stored date vs Queried Date: Queried date becomes 23:00 December 14 because we subtracted 1 hour from UTC+1 to get the UTC conversion (as UTC+1 is 1 hour ahead UTC). This is the reason why the date fields are one day late on API queries against Data Center 12.
 
Note:

a. In the UI, the dates are correct regardless of Data Center, since there are no conversions when displaying the dates in the UI. 

b. The time part for standard date fields are not truncated e.g., applicationDate. Only custom fields have truncated time due to changes made in RCM-80845. 

c. Moreover, on query, the Daylight Savings Time is being considered by the servers. This would mean the following: 

DC 8 which originally has UTC-5 timezone (EST) would have UTC-4 timezone (EDT). 
DC 12 which originally has UTC+1 timezone (CET) would have UTC+2 timezone (CEST). 

D. What is the current workaround for dealing with mismatching dates in the upsert and the query?

The current workaround is to convert the date fields after doing the query, from UTC to your Data Center timezone (taking into consideration Daylight Savings Time). This would mean the following: 

If the instance is in Data Center 8 and you query a date field:

During Non-Daylight Savings time: The resulting date has to be converted from UTC to UTC-5.
During Daylight Savings time: The resulting date has to be converted from UTC to UTC-4.

If the instance is in Data Center 12 and you query a date field:

During Non-Daylight Savings time: The resulting date has to be converted from UTC to UTC+1.
During Daylight Savings time: The resulting date has to be converted from UTC to UTC+2.

Note: The date when the value is upserted (whether in Daylight Savings Time or not) does not matter. The adjustment is based on when the query is done (whether in Daylight Savings Time or not). 

Keywords

Custom Dates, Query, Truncated, API, Recruiting Management, RCM, Integration , KBA , LOD-SF-RCM-API , Webservices & APIs , How To

Product

SAP SuccessFactors HXM Core 2011