Hiding and Replacing Events

It is possible to hide and replace events in a history. History remains an immutable log, the original events are still part of the history record, but they are not returned in history queries. A new audit mode can be used to retrieve them. Hiding and replacing events also writes special metadata events as a log of what happened.

Three functions hideEvent(), replaceEvent() and unhideEvent() provide this functionality.

All three work the same underlying way: every event has an internal sequence number, N. Visible events run 1, 2, 3, ...; hiding an event moves it to the next free negative N (-1 is permanently skipped) and closes the gap in the visible sequence. Nothing is ever deleted.

Audit Mode

getHistories() and getEventValues() include the boolean operator auditmode, which defaults to false. Histories are returned without hidden events, and with replacements in the correct position. Events are numbered sequentially without gaps.

When true:

• Hidden events, replaced-away originals, and hide/unhide/replace metadata events are all included, each with a negative pos[0]/N (never -1)
• For any event that was a replacement, timestamp switches from the inherited original time to the genuine time the replacement happened
• fpos switches from ranking by N to ranking by insertion order - negative/reused N values aren't a meaningful sort key once hides and replacements are in the mix

Example

These two responses show the same history where eventId 502 has been hidden. In audit mode you can see the hidden event and the metadata event which describes the hide action.

Normal response:

"result": {
  "subject": { ... },
  "events": [
    { "eventId": 501, "event": {..."one"}, "pos": [1,2] },
    { "eventId": 503, "event": {..."three"}, "pos": [2,2] }
  ]
}

Audit mode:

"result": {
  "subject": { ... },
  "events": [
    { "eventId": 501, "event": {..."one"}, "pos": [1,2] },
    { "eventId": 503, "event": {..."three"}, "pos": [2,2] },
    { "eventId": 502, "event": {..."two"}, "pos": [-2,2] },
    { "eventId": 504,
      "event": { "eventMetadata": {
        "eventId": 502, "type": "hide" } },
      "pos": [-3,2] }
  ]
}

History Digests

History digests are not automatically updated by hiding, unhiding or replacing events.

Digests will be run in "user" mode. They will only include events which are visible at the time the digest runs:

• If the event was visible when the digestion happened, then it will be included in the digest
• If the event was hidden when the digestion happened, then it never gets digested

Stored Procedures (Data Reporting Server)

• getHistoriesLastSummary - Will only retrieve visible events
• getHistoriesLastValues - has a new AuditMode parameter:
  • In "user" mode, the latest values of visible events will be returned. The latest event will be the one with the highest n number
  • In "audit" mode, the latest values of all events will be returned. The latest event will be the one with the highest event id

Sealed Histories

It is possible to hide, unhide and replace events in sealed (historic) history records. It is not possible to "un-seal" a history.

Error Reference