OData v4.0 Delta Capabilities for Data Exporter API

With the August '22 Release, OData v4.0 Delta change capabilities will be implemented for the Data Exporter API, starting with the user_ou_core object. This enhancement will provide OData v4.0 compatible Delta change tracking for inserted, updated, and deleted data for the Data Exporter API. Prior to this Release, customers had to manually supply date/time filters in the URL to retrieve new and updated information, and there was no way to be informed of deleted data for GDPR compliance.

This functionality is not available at the start of UAT.

OData v4.0 Delta Change Tracking Key Features

  • Inspect results of the $metadata endpoint to see which objects support change tracking
    • If ExtendedMetadata.ObjectSupportsChangeTracking’ = ‘true’, then can proceed with steps below
  • Do not need explicit date/time filter
    • Example: https://{corpname}.csod.com/services/api/x/dataexporter/api/objects/user_ou_core
  • Insert 'Prefer odata.track-changes’ into initial HTTP header to request that the service return a delta link
    • Response header will include ‘Preference-Applied: odata.track-changes’
    • Next pages will automatically reapply ‘Prefer: odata.track-changes’
    • If object does not support delta, will receive ‘501’ (Not Implemented) error
  • Last page of result set will include delta link with delta token
    • Example: "@odata.deltaLink": “user_ou_core?deltatoken=xxxx"
    • Delta token is encoded representation of original query and timestamp
    • Should retain delta link/token for next request and only replace when receive next delta link/token
      • If request is interrupted or otherwise unsuccessful, can use last token to request delta again. You do not need to keep track of timestamps.
  • Delta result sets may include two types of records (see sample image below):
    • Records deleted since the timestamp in the delta token. Record will include an ‘id’ field and a ‘reason’ field (with value = ‘deleted’). The ‘id’ field can be used to delete the corresponding record (if it exists) in the customer’s local database.

    • Records inserted/updated since the timestamp in the delta token. Customers should continue to use the current MERGE or UPSERT process used to process Data Exporter API data.

  • Records for data deleted in Cornerstone CSX will be maintained (primary keys only) for 15 days before hard deletion. Therefore, delta links/tokens are only valid for 15 days. After 15 days a new request for a full extract will be required

Resources

OData v4.0 / Delta Documentation

Implementation

On by default for current Data Exporter API users. Data Exporter API documentation will be updated to reflect Delta capabilities before the start of UAT

Enablement will occur on specific objects/endpoints in a phased approach, starting with the user_ou_core object, with the July 19 stage deployment. Delta for additional objects/endpoints will be added in patches and announced via the RTDW Documentation for Reporting API, RDW, and Data Exporter Community.