-
Type:
Improvement
-
Status: Open
-
Priority:
Major
-
Resolution: Unresolved
-
Affects Version/s: V4.01_CS02
-
Fix Version/s: V4.02
-
Component/s: JSON Format, Protocol, Vocabularies
-
Labels:None
-
Proposal:
In a delta response, Added and Changed entities are represented as Entities in the delta response. There is no way for the client to distinguish between an Inserted entity and a Changed entity. If the client is using the delta response to keep data in a cache or data warehouse in sync, then the distinction between an Inserted and Updated entity doesn't really matter. The client would do an upsert of the Inserted / Updated entity. If the entity exists it gets updated and if it doesn't it gets inserted.
However, in cases where the changes are being tracked for auditing or reporting purposes, it is useful to be able to distinguish between an inserted or updated entity. There is a difference between inserted and updated entities in a delta response in that an inserted entity must include all selected properties where as an updated entity must only include all selected properties that changed. The distinction is not reliable for detecting the difference though. It is possible that all of the selected properties of an existing entity have change and it is also possible that a server would always return all selected properties of an updated entity.
Consider adding an optional @inserted or @updated annotation or both to make the distinction between the Inserted and Updated entities, This is similar to the @removed annotation that already exists.
When a delta payload is provided to the service in the body of an update request, the @inserted or @updated annotations would typically would not be needed, but it should be fine to include them if for example the delta payload was originally received as a delta response.
Mike: concern that delta until now is idempotent, so you can apply the same delta twice, giving the same result. Indicating that an entity is inserted versus updated might tempt implementations to break this.
Hubert: make sure that we describe that entities in delta payloads are UPSERT-ed and that UPSERT rules are applied.
I think the only two states we can state are "it previously existed" and "i don't know if it already existed".
I like limiting what the payload can claim to those two states.
We could have an enum-valued "@Core.PreviousState:" with a value of "Existing" ("Existed?") and (optionally) "unknown".
Scenario we had was that M365Connectors have certain operations which get triggered only when a new message arrives (e.g. [Office 365 Outlook - Connectors | Microsoft Docs|https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdocs.microsoft.com%2Fen-us%2Fconnectors%2Foffice365%2F%23when-a-new-email-arrives-(v3)&data=04%7C01%7Cmikep%40microsoft.com%7Cf1c6efdb7947472623b408d9e1c2c9ac%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637789048992342089%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=jgY0x4Q7J8%2F1a94BgKmvNj0mF347LfdHIodMY6q1G%2Bg%3D&reserved=0]). So, if a message was known to already exist, these operations would not be triggered.
Why not use a nullable Boolean for the three states instead of a three-valued enum type?
I'm struggling with the "PreviousState" as the annotation's name, doesn't feel like it fits with other annotations we have. At the time can't think of anything better then "updated", similar to "removed". Could/should we also allow details about the update to be included?
For deleted entities we have the annotation @removed to allow specifying a reason why the entity was removed: really deleted, or just changed so that it no longer matches the filter
{ "@context":"#Customers/$deletedEntity", "@removed":{ "reason":"deleted", "@myannoation.deletedBy":"Mario" }, "@id":"Customers('ANTON')" }We could define a similar annotation telling whether the entity was