Add concept of a Delta to `UpdateComplexType`

[at055612]

The current UpdateComplexType supports the recording of the before and after states of an audited entity. Systems may not always have access to both states. E.g. if they are adding an extra permission to a user but do not have access to all the before or after states.

In these cases it may be preferable to be able to record a delta instead, i.e. just the information about what has changed, i.e. the addition of permission X.

The proposal is to add a choice to the existing UpdateComplexType like so

where DeltaType would be enumerated to Add|Remove.

If we add the Delta element then we could consider making Before mandatory, but that would introduce a breaking change.

[burnalting]

I do like the idea of an Add/Remove enumeration given the concept of 'Update' would be solved by using just Update/After one assumes. And yes, the earth shook at the concept of making Before mandatory :-)

[at055612]

I don't think we want to expand the meaning of the existing Update/(Before|After). The idea of those is to provide the complete before and after states so you can see what is different.

For clarity, here is an example we a list of fruits is stored and modified.

The before/after way: Before = banana, apple, pear After = banana, apple, pear, orange

The delta way: Delta = orange (ADD)

Which way is used will depend on the system and how it is doing the update. If it has easy access to the before and after states then it can use those. If it is just say inserting an orange record into a table then it may not have any before/after state without performing extra queries so a delta is more suited.

Maybe the Delta element needs something extra to capture details of what the delta is being applied to, e.g. in this case list of fruits though without the full detail of what it contains.

If we are modelling a simple string value change, e.g. someone changing their email address then there is no need for the Delta. We can just use After and optionally Before if we know what it used to be.

[burnalting]

I agree. Basically my comment is about

• if the change is adding something to an object then model is Update/Delta/Add,
• if the change is deleting something to an object then mode is Update/Delta/Remove,
• if the change is modifiying something about an object then the mode is Update/After (if only the after state) or Update/Before+After (if you have both)

and yes, it would have value to identify the object one is applying a Delta/Add or Delta/Remove to

[at055612]

Maybe rather than having the choice between Before+After and Delta, if Delta is just an optional element it can describe the object being added/removed (i.e. a fruit in the above example) and After can be used to describe the object being added to (or having something removed from it) but without necessarily providing the full picture of that object.

e.g.

<After>
  <Name>Fruit basket</Name>
  <!-- No detail on what is in it -->
</After>
<Delta>
  <DeltaType>ADD</DeltaType>
  <Name>Orange</Name>
<Delta>

[burnalting]

Why not put the subject of the action within Delta ... e.g.

<Delta>
  <Object>
    <Name>Fruit Basket</Name>
  </Object>
  <DeltaType>ADD</DeltaType>
  <Name>Orange</Name>
<Delta>

[at055612]

Fixed in v4.1.0