Commerce Engine minions

Current version: 9.2

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 a list

  • 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, a minion can iterate a list and call a pipeline to perform business functions on items in that list. 

Minion policy

A minion policy defines each minion. Minion policies are defined in the Plugin.Minion.PolicySet-1.0.0.json file, or in the .json file that contains policies specific to an environment. The minion policy (MinionPolicy) is a configuration that specifies the name of the minion, the list the minion must watch (ListToWatch), and the fully qualified assembly name (FullyQualifiedName) of the minion. Like other configuration, minion policy settings are registered in the Commerce Engine during the bootstrapping process.  

In Sitecore XC 9.2 and later, 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 are running that are configured to process the same entity types as it processes. If another such minion is running, 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 a minion policy:

RequestResponse
   {
     "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
     "WakeupInterval": "00:05:00",
     "ListToWatch": "CatalogItemsIndex",
     "FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.IncrementalIndexMinion, Sitecore.Commerce.Plugin.Search",
     "ItemsPerBatch": 10,
     "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.

RequestResponse
   {
     "$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
     "WakeupInterval": "24:00:00",
     "ListToWatch": "Carts",
     "FullyQualifiedName": "Sitecore.Commerce.Plugin.Carts.PurgeCartsMinion, Sitecore.Commerce.Plugin.Carts",
     "ItemsPerBatch": 10,
     "SleepBetweenBatches": 500
   },

Scaling minions

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.

RequestResponse
{
 "$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",
       "ListToWatch": "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",
       "ListToWatch": "PendingOrders.2",
       "FullyQualifiedName": "Sitecore.Commerce.Plugin.Orders.PendingOrdersMinion, Sitecore.Commerce.Plugin.Orders",
       "ItemsPerBatch": 10,
       "SleepBetweenBatches": 500
      }
     ]
    },
    "WakeupInterval": "00:05:00",
    "ListToWatch": "PendingOrders",
    "FullyQualifiedName": "Sitecore.Commerce.Plugin.Orders.PendingOrdersMinionBoss, Sitecore.Commerce.Plugin.Orders",
    "ItemsPerBatch": 10,
    "SleepBetweenBatches": 500

Do you have some feedback for us?

If you have suggestions for improving this article,