Every entity in the data models has an element "lastChangeTimestamp" defined in harmonized-commons.xsd as:

"Technical versioning used for differences tracking - this is not to be used as business data"

Why?

The lastChangeTimestamp serves the only purpose of allowing clients to search and detect any change to the API response payload that describes to an entity. Its value will be reset to the current (local server) time in the events of:

• any business metadata value changes
• the data model has changed (e.g. elements have been added, removed, re-ordered or re-shuffled)
• data was fixed on the server and some (sometimes many) metadata have been regenerated
• a technical issue or update or upgrade on the server required reindexing all contents

Therefore, an entity may have its lastChangeTimestamp reset to now if, by order of likelihood:

1. some business metadata value has / have indeed changed (this case is interesting for business process)
2. the model was updated, and a new field was made available (this case is needed for technical sync)
3. nothing actually changed, but we fixed an issue (we are sorry in this case)

Cases 2 & 3 above imply that you cannot rely on the lastChangeTimestamp to indicate that a project or publication was indeed updated by any business process. For example, even the oldest project or publication, which is frozen for years, may have its lastChangeTimestamp dated a week ago, corresponding to the latest update of the data model.

You can read more real cases of when the lastChangeTimestamp is modified by reading here

*Notice that for the initial exposing of the APIs, ISO decided to have all lastChangeTimestamp set to August 2018. IEC and CEN decided to anti-date corresponding to real business data change. This has an impact on your algorithm for the initial bulk-load, see below.

As defined above, the lastChangeTimestamp will allow you to remain in full synchrony with our metadata. This won't allow you to trigger business process on real metadata changes on your side. For that, please see the section on detecting changes.

How to use it

The proper use of lastChangeTimestamp is to query a search endpoint for only those entities whose technical content (payload) has changed since last processing, and therefore need a local refresh.

Example of a request:

.../projects?lastChangeTimestampFrom=2019-10-05&size=100&page=0

Watch out, if you don't specify a time, this means day D + 00:00:00.000. Therefore if you request for changes after day D, and before day D, this is NOT a full-day, as in:

.../projects?lastChangeTimestampFrom=2019-10-09&lastChangeTimestampTo=2019-10-09

Algorithm:

1. Retrieve the date+time of your last successful request from local storage
2. Query the search endpoint with adding the request parameter as in the example above
3. Watch out you still need to take care of pagination because many entities may still be returned in the response payload
4. Process the response entirely (all pages)
5. If the response was processed successfully (this is VERY important), update the date+time of the request (not of the end of processing) into local storage for the next iteration's step (1)