Skip to content

Journalled Entities Specification

Concept

Entities have a fixed identity, but their information can change over time. The system must record these changes to enable audits, meet compliance needs, and support forensic analysis. Tracking changes also allows business logic to reference the state of the system at any specific moment.

Journalled Entities are designed to support these requirements.

Business Value and Needs

Keeping complete history of changes to entities and providing access to immutable, previous versions of an entity is valuable for:

  • Audits: Reviewing the history of changes to ensure compliance with regulations and internal policies.
  • Forensic Analysis: Investigating issues or incidents by examining the state of entities at specific points in time and determine how the change happened.
  • Immutable Values: Once certain business transactions are committed or agreed, the information relating to that transaction must be immutable. This requirement extends not only to the records directly involved in the transaction but also to any reference data or other information that the system used to process the transaction. Although this could be achieved in an ad-hoc manner by copying information to separate storage, it is more desirable to have a general mechanism that allows the business logic to freeze the version of an entity at a particular point.
  • Latest Values: Business logic may need to access the latest version of an entity to refresh its state or to ensure that it is presenting the most up-to-date information to users or other systems.
  • Analytics: External analytics engines, timeseries reporting and similar use cases require access to the complete history of versions of an entity to compute trends, predictive models etc.

User Stories/Requirements

  1. Journalled Entities, upon creation, deletion or update operations, must keep record of:

    1. The values of the properties of the entity before the change
    2. The values of the properties of the entity after the change
    3. The identity of the user that made the change.
    4. An optional note (String) note about the change that the business logic can provide.
    5. The effective time of the change, that is the time when the change becomes effective for business logic and workflows.
    6. The recorded time of the change, that is, the time when the change is actually performed to the entity.

  2. An Entity or other business logic referring to a Journalled Entity must be able to access the Entity by using:

    1. A reference to a specific version
    2. A reference to the entity with the interpretation that the system will return the latest version as of the time of the request.
    3. A reference to the entity and values for the effective and recorded times. The system will return the latest version of the entity with effective and recorded times earlier than the specified values.

  3. The interpretation of latest for retrieving an entity version is the record with the highest effective time, selected from the set of records with lower effective time and lower recorded time than the specified values.

Design

Concepts

  1. TimeCoordinates: The pair of effective and recorded times that define when a change happens in the system.

    1. Effective Time: The time when the change becomes effective for business logic and workflows.
    2. Recorded Time: The time when the change is takes place and is recorded by the system.

    Implementation wise, these two values are represented as Timestamps in the system.

  2. Entity: Represents a part of the system’s state with a fixed identity and mutable contents. It can be considered as a Dictionary value with an additional identity property that is immutable and unique within the system. See Entities Description.

    1. An Entity can be a Journalled Entity if it supports the requirements described in this document.
    2. An Entity can be accessed by its identity, or by its identity and TimeCoordinates to retrieve a specific version of the Entity.
    3. An Entity can be updated, deleted or created, and these operations will result in the creation of a new Record.
  3. Record: An immutable snapshot of an entity’s state at a specific value of TimeCoordinates. A Record contains:
    1. A unique identity of the Record itself that is unique in the system.
    2. The TimeCoordinates for when the change was made.
    3. The identity of the user that made the change.
    4. An optional note about the change.
    5. The value of the Entity (including its identity) after the change.
    6. The identity of the Record upon which the change was made (the previous version of the Entity) except for the first record created for an entity.
    7. A boolean market indicating whether the Entity was deleted in this change or not.
  4. Universe: An access point to a collection of Entities that supports CRUD operations. See Universe Description.
  5. Journalled Entity: An Entity that supports the Journalled Entity requirements, together with at least one Universe that gives access to a set of instances of the Journalled Entity and supports the operations describe below.
  6. RIO: A RIO, standing for Result IO is an abstraction for a computation that produces a result of an error. It is similar to the concept of an Effect in functional programming languages. It is introduced here to make the signatures more representative of the actual implementation. The need for having operations return a RIO rather than a simple value of a Result<T> value is to allow operations to be composed together in a given context like a service request or a transaction.
  7. EntityId: A primitive data type for the identity of an Entity.

Implementation

To support the implementation of Journalled Entities the system provides generic implementations of Journalled Entities and Universes as well as Bitemporal persistence and querying capabilities documented in the Common Module Documentation

Comments