Edit-Draft-Publish of Reference Data

Reference Data is directly edited by Users. The values of Reference Data Entities are in turn used as part of other Reference Data Entities
or directly in transactional use cases.

Behavior¶

Reference Data behavior is:

Bitemporal: Each Reference Data Entity keeps history of when it was updated in the system (recordedAt) and when the value
is effective in the system for use by other processes (effectiveAt). The value at a pair of these TimeCoordinates is immutable.

Creation, Updates and Deletion of Reference Data Entities create new Bitemporal Entities a new record with its own time coordinates.

Consumer processes can retrieve the active value at any given time coordinates in the past or future.

Published: When a user performs a creation or update of a Reference Data Entity, it may save the value associated with the entity
as Draft or Published.
- When saved as Published, a new bitemporal record is created for the entity that is inserted in the entity’s history.
- When saved as Draft, no changes are made to the entity’s history. A temporary record holding the values is kept by the system that
  can be further edited and later Published or saved as Draft again.
Only one draft of a given entity is supported at any time and any edit actions on the entity will use the current values of an existing
draft as the starting point.

Reference Data Lifecycle with Draft Saving¶

States¶

Creating: An ephemeral state that exists only in the UI while the User is actively entering information to create a new
Reference Data Entity. No backend state is maintained in this state. From this state, it is not possible to save a draft as the
Entity does not yet exist.
Editing: The state where a user is actively making changes to a Reference Data Entity. In this state, the system keeps track of the current draft.
Published: A new record of the Reference Data Entity has been saved and recorded in the system. The system maintains a complete bi-temporal history of all changes made to the entity over time.
Deleted: The Reference Data Entity has been marked as deleted. In this state, the entity is no longer active, but its bi-temporal history is preserved.

Transitions¶

\(Start \rightarrow Creating\): create: The system presents the user with an input form to provide information to create a new Reference Data Entity.
\(Creating \rightarrow Published\): publish[validateOK]: The user confirms the creation of the new Reference Data Entity. The system validates the input and saves the
first creation record of the Entity.
\(Creating \rightarrow Creating\): publish[validateError]: The user attempts to publish the new Reference Data Entity, but validation fails. The system remains in the Creating state.
\(Creating \rightarrow End\): discard: The user cancels the creation of the new Reference Data Entity. The system closes the input UI and does not keep any record of the user interaction.
\(Published \rightarrow Editing\): edit: The user, while viewing a record of the entity, requests to edit it. The system transitions to the \(Editing\) state with the values of the current record as
the starting point for the draft.
\(Editing \rightarrow Editing\): save draft: The user saves a new set of values as an updated draft, remaining in the Editing state. No validation is performed.
\(Editing \rightarrow Deleted\): delete: The user deletes the entity. The system will mark the entity as deleted and remove the draft information.
\(Editing \rightarrow Published\): discard: The user discards the current draft, the system deletes it and leaves the Entity unchanged.
\(Editing \rightarrow Published\): publish[validateOK]: The user confirms the changes made to the Reference Data Entity, upon successful validation a new record for the entity is saved and
the draft information is discarded.
\(Editing \rightarrow Editing\): publish[validateError]: The user attempts to publish the changes made to the Reference Data Entity, but validation fails.
The system remains in the Editing state, keeping the existing values of the draft.
\(Published \rightarrow Deleted\): delete: The user requests to delete the Reference Data Entity. The system marks it as deleted with a new bi-temporal record.

Notes¶

Some edge cases are not described in this document. They will be considered in the future.

edit and delete actions may have additional validations that may prevent the associated transition to take place.
Upon publishing a new bi-temporal record, the module that manages the Reference Data Entity should emit notifications to other subscribed modules.
discard while in Editing state may have additional guards to require confirmation from the user.