Commerce Engine minions

The Sitecore XC Commerce Engine leverages the use of minions as basic units of work to perform specific tasks in a process. Predefined Commerce Engine minions perform key processes in the following areas:

  • Commerce transactional processes (for example, orders and sales activities)

  • Commerce entity indexing (for example, indexing of orders, customers, or catalog items)

  • Management operations (dev-ops operations, for example)

Minions perform basic actions on lists. Some of the common tasks that minions perform include: 

  • Watching one or multiple lists

  • Adding items to a list

  • Deleting items from a list

  • Moving items from one list to another

A minion can perform a single task and stop. Alternatively, some minions are triggered by a scheduler to iterate a list and call a pipeline to perform business functions on that list, such as order processing minions, for example.

Minion policies are defined in the Plugin.Minion.PolicySet-1.0.0.json file, or in the .json file that contains Commerce Engine policies specific to an environment. Like other configuration, minion policy settings are registered in the Commerce Engine during the bootstrapping process.  

The MinionPolicy includes an Entities parameter that specifies the entity types that the minion processes.

Before a minion runs, it checks to see if any other minions that are running are configured to process the same entity types as it processes. If another such minion is processing the same entity types, the minion waits until that first minion has finished running before starting its own process. This prevents concurrency errors that arise if two minions attempt to update the same entity at the same time.

For example, before the FullIndexMinion runs, it checks to make sure that neither the DeleteIndexDocumentsMinion nor the IncrementalIndexMinion (both of which work with the same entity types) are running at the same time, to avoid corrupted data in the indexes.

The following shows an example of an indexing minion policy:

   {
     "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
     "WakeupInterval": "00:05:00",
     "ListsToWatch": [
       "CatalogItemsIndex"
     ],
     "FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.IncrementalIndexMinion, Sitecore.Commerce.Plugin.Search",
     "ItemsPerBatch": 1000,
     "SleepBetweenBatches": 500,
     "Entities": {
       "$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
        "$values": [
          "Sitecore.Commerce.Plugin.Catalog.Catalogs, Sitecore.Commerce.Plugin.Catalog",
          "Sitecore.Commerce.Plugin.Catalog.Category, Sitecore.Commerce.Plugin.Catalog",
          "Sitecore.Commerce.Plugin.Catalog.SellableItem, Sitecore.Commerce.Plugin.Catalog"
         ]
       }
     },

The Entities property is optional. If the Entities property is left empty, the minion only checks for another minion of the same type before running.

For example, with the following minion policy configuration, the PurgeCartsMinion only runs if there is no other instance of the PurgeCartsMinion running already.

   {
     "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
     "WakeupInterval": "24:00:00",
     "ListsToWatch":[
       "Carts"
      ],
     "FullyQualifiedName": "Sitecore.Commerce.Plugin.Carts.PurgeCartsMinion, Sitecore.Commerce.Plugin.Carts",
     "ItemsPerBatch": 1000,
     "SleepBetweenBatches": 500
   },

The following table describes minion configuration properties:

Property

Description

type

Declares the class types that the minion is based on.

WakeupInterval

Sets the interval at which the minion runs.

ListsToWatch

Specifies the name of lists the minion is watching. A minion can watch multiple lists, for entities of a similar type, such as "promotions" and "promotionsBooks", for example.

Note

When watching multiple lists, the minion reads data from the first list, then reads the second list, and so on.

This property is introduced with Sitecore XC release 9.3 and replaces the deprecated ListToWatch property.

This property is mandatory.

FullyQualifiedName

Specifies the fully qualified name of the minion class.

ItemsPerBatch

Specifies the number of documents the minion processes for indexing documents in batches.

SleepBetweenBatches

Indicates the period of time to wait between each documents batch.

Entities

Specifies the entity types that the minion processes.

The Commerce Engine makes use of a boss minion, which acts as a parent minion that delegates work to children minions to perform. Each child minion defines a list that it is acting on. This allows minions to scale without the contention of multiple minions reading from a single list.  

The pending order process provides a good example of a boss minion implementation that scales. The PendingOrdersMinionBoss is defined as a parent minion configured to watch the PendingOrders list. The main task of the the boss minion is to distribute pending orders to its children minions for processing. The PendingOrdersMinionBoss has two children minions defined. Each child watches its own list of pending orders (PendingOrder.1 and PendingOrder.2, respectively) that it processes independently. 

Below is an example of a scaling minion configuration showing a parent boss minion that contains two children minion definitions.

{
 "$type": "Sitecore.Commerce.Core.MinionBossPolicy, Sitecore.Commerce.Core",
 "Children": {
   "$type": "System.Collections.Generic.List`1[[Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core]], mscorlib",
   "$values": [
     {
       "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
       "WakeupInterval": "00:05:00",
       "ListsToWatch": [ 
          "PendingOrders.1"
         ]
        "FullyQualifiedName": "Sitecore.Commerce.Plugin.Orders.PendingOrdersMinion, Sitecore.Commerce.Plugin.Orders",
       "ItemsPerBatch": 10,
       "SleepBetweenBatches": 500
      },
      {
       "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
       "WakeupInterval": "00:05:00",
       "ListsToWatch": [ 
          "PendingOrders.2"
        ]
        "FullyQualifiedName": "Sitecore.Commerce.Plugin.Orders.PendingOrdersMinion, Sitecore.Commerce.Plugin.Orders",
       "ItemsPerBatch": 10, 
       "SleepBetweenBatches": 500
      }
     ]
    },
    "WakeupInterval": "00:05:00",
    "ListsToWatch": [  
       "PendingOrders"
     ],
    "FullyQualifiedName": "Sitecore.Commerce.Plugin.Orders.PendingOrdersMinionBoss, Sitecore.Commerce.Plugin.Orders",
    "ItemsPerBatch": 10,
    "SleepBetweenBatches": 500
    }
  ]
},