Entity journaling

Abstract

Overview of Commerce entity journaling that you can use to preserve a complete log of all changes made to an entity.

The Commerce Engine encompasses extensible services that enable you to customize commerce functionality.

Note

Do not extend or inherit from out-of-the-box policies; instead, create your own. You can change the values in a policy by modifying the PolicySet JSON or the Environment JSON, depending on where the policy is defined and then re-running Bootstrap.

When enabled for an entity type, entity journaling sets a flag to update a journal whenever the entity changes. The journaling process saves a complete copy of the previous version of the changed entities, providing a log of all changes.

Important

The journaling entries can considerably increase the size of the Shared Environments database since journaling creates a copy of the complete entity, and not just the changed entity fields or properties. For example, every time an order status changes, a complete copy of the order entity is stored in the database.

You can consider disabling entity journaling for Commerce entities that do not have auditing requirements.

The following policy can be configured through the Journaling plug-in.

Policy

Description

Properties / Default Values

EntityJournalingPolicy

Defines the name of the journals list and the full entity type.

Journal \ "EntityJournal"

EntityFullName\ string.Empty

The following is an example of a EntityJournalingPolicy:

{
     EntityFullName = "Sitecore.Commerce.Plugin.Orders.Order",
     Journal = "OrdersJournal"
 }

The EntityPersistenceJournalingBlock checks the EntityJournalingPolicy for rules on how to journalize the entity.

You can enable or disable journaling for a Commerce Entity by changing the EntityJournalingPolicy policy in the Commerce environment configuration file. For example, to change the journaling behavior in the sample Habitat Authoring environment, you modify the wwwroot\CommerceAuthoring_Sc\wwwroot\data\EnvironmentsPlugIn.Habitat.CommerceAuthoring-*.*.*.json file.

To enable journaling, for example, of changes to the Customer entity in the sample Habitat Authoring environment:

  1. Open the wwwroot\CommerceAuthoring_Sc\wwwroot\data\EnvironmentsPlugIn.Habitat.CommerceAuthroing-*.*.*.json file.

  2. In the file, add the EntityJournalingPolicy policy, specify the entity name (EntityFullName), and the journal name:

    "$type": "Sitecore.Commerce.Plugin.Journaling.EntityJournalingPolicy, Sitecore.Commerce.Plugin.Journaling",
            "EntityFullName": "Sitecore.Commerce.Plugin.Customers.Customer",
            "Journal": "CustomersJournal"
  3. Save your changes and bootstrap the Commerce Engine.

    Note

    To disable journaling of a given Commerce entity type, delete the corresponding EntityJournalingPolicy policy block from the environment configuration file.

    If journaling is disabled for an entity where it was previously enabled, the journal entries are not removed; it will simply no longer create new ones.