Entity change log

Introduction

When data is dynamically modified by users or services such as APIs or Cron jobs, it can be challenging to understand what has happened in the system.

To address this need, the SmartPlatform enables the implementation of a modification history: the Entity change log.

example of an entity change log entry

Scope of entity change log monitoring

This feature is not intended to be used for statistical purposes.

Usage

Adding the entity change log

During the design phase, we validate together the relevance of implementing the change log for each models in your project's database.

We then configure the platform to enable the change log and determine its visibility for each of your project's interfaces.

Technically, we have chosen a JSON storage format directly at the entity level for simplicity and easier cleanup.

Automatic history for actions on entities with change log

If the change log is enabled for your entities, the platform will automatically report the changes and data for the following actions in its history:

Creation

• Regardless of the source triggering the creation (addition form, import screen, API call, etc.): the change log will capture the information.
• We store the date and time when your entity was added to your database.

Modification

• Similarly, all possible modification channels will be identified with an entry in the history by the date and time of the action.
• Each modified field will be listed in the following format:
  %Field name% : (%Old value%) → %New value%
  Examples:
  • Client name: (ANDRE) → ANDRÉ
  • Postal code: (26200) → 26000
• Changes in the lifecycle statuses of your entities will be clearly visible with their associated color codes, example:

Soft delete and archiving

• The change log ensures that you know when soft deletions or archiving occurred.
• This allows your support team to have a complete view of the lifecycle of your business objects.
• We store the date and time when your entity is marked as softly deleted or archived in the database.

Email sending

• All entities in your project capable of receiving emails with the change log enabled will have an entry in their history for each email sent, with the following information:
  • The subject of the email
  • The recipient email address used at the time of sending
  • The email status history if the email was sent via our mailer API, example:

Generic behavior: origin and author of modifications

For each change log entry, we store the context of the change's origin (Client Interface, Backoffice, Cron, API call) as well as the author of the action (corresponding to the current authenticated user, if applicable).

Storing additional events

In addition to the generic actions mentioned above, which are automatically handled by the platform, we can manually log an activity entry in an entity's change log at any time.

This usage mode allows you to track any business event related to your project entities, such as:

• Single-payment or subscription receipts
• Expiration of user product licenses
• Or any other custom action results we can add (prioritization, reassignment, etc.)

Display and rendering templates for the change log

Timeline Rendering

This type of change log display provides a complete and continuous view of the various activity flows on your entity, from the most recent to the oldest:

Enriched change log entry

The platform also allows adding HTML text in the description or comment of a change log entry to detail the action that has occurred.
This additional information is particularly useful for logging business events related to your project.

example of description and comment HTML rendering

API call and Cron links

If your target entities are manipulated by API calls or Cron jobs, the change log entry will include a link to the treatment log's ID related to the API call or Cron job.
This enables transitioning from the micro-view of your entity to the macro-view in our monitoring screens.

example rendering with Cron Id monitoring link

Filtering fields to log and make visible

Change log filtering

By default, entities with the change log enabled will have all their modified fields logged and visible in their history.

Sometimes, certain fields are purely technical data (performance indexes, compiled data).

These fields should be filtered out to avoid unnecessary saved data to optimize database storage.

Our change log configuration for your entities allows filtering out such modified fields so they will never be logged.

    public function getHistoryDiffFieldsToSkip(): array
    {
        return [
            'search' => true,
            'canonical' => true,
        ];
    }

example code for excluding search indexes and unique identifiers from storage

After completing this filtering step, we proceed with a final configuration to manage the visibility of these fields.

Change log visibility

For each type of interface and user profile, we can hide or display certain history entries and/or specific data, for example:

• For an administrator backoffice, we can display all the data from your prospect records, giving you a complete overview of all interactions.
• For another operator interface in your project, we can limit the visible history of the record to only calls made for the call center.
• For a client interface, it is possible to hide other change log entries, or even remove it entirely, depending on the sensitivity of the information.