Predefined Commerce Engine minions
The Commerce Engine plugins contribute default minions that play key roles in various types of processing, such as indexing, or order flow processing, for example. This topic provides a description of minions that are defined by default.
Indexing minions for Sitecore web and master indexes
The Catalog plugin defines minions that are responsible for the full or incremental indexing of catalog entities, including catalogs, categories, and sellable items. The search provider used by Sitecore (Solr, for example) can then use the catalog entities indexed by the Commerce Engine when rebuilding Sitecore web or master indexes to provide up-to-date search results to Sitecore Content Editor and storefront users.
ItemFullIndexMinion
The ItemFullIndexMinion minion is responsible for re-indexing all catalog entities in the Commerce Engine, allowing for their inclusion in Sitecore master and web indexes. The minion is manually invoked when a user requests a full rebuild of the Sitecore master or web indexes, either using the Sitecore Control Panel or using a Postman sample request.
ItemIncrementalIndexMinion
The ItemIncrementalIndexMinion minion runs every 10 minutes (as defined in the default index updates strategy), and is responsible for keeping Sitecore master and web indexes up-to-date, so that Sitecore item search results can include new, updated, or deleted catalog entities. You can invoke the Run IncrementalIndex Minion - Storefront (Master) request in Postman to manually trigger an incremental index rebuild.
Indexing minions for Business Tools search
The Search plugin contributes minions that perform tasks for the indexing of Commerce entities (such as orders, customers, or catalog items). The search provider (such as Solr) that is servicing the Business Tools can then use the Commerce indexes to return search results to Business Tools users.
FullIndexMinion
The FullIndexMinion minion indexes all items in a list. It runs on demand, calling the IPrepareFullIndexMinionPipeline and the IFullIndexMinionPipeline to perform indexing functions.
The FullIndexMinion minion watches three lists: Catalogs, Categories, and SellableItems. The following is an example of a FullIndexMinion definition in the PlugIn.Minions.PolicySet-1.0.0.json file:
{
"$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
"ListsToWatch": [
"Catalogs",
"Categories",
"SellableItems"
],
"FullyQualifiedName": "Sitecore.Commerce.Plugin.Search.FullIndexMinion, Sitecore.Commerce.Plugin.Search",
"ItemsPerBatch": 1000,
"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"
]
}
},IncrementalIndexMinion
The IncrementalIndexMinion minion watches for new items that need to be updated in the index. It runs every 3 minutes and calls the IPrepareIncrementalIndexMinionPipeline and the IncrementalIndexMinionPipeline.
DeleteIndexMinion
The DeleteIndexDocumentsMinion minion watches a list. It runs every 3 minutes, calling the IPrepareDeleteIndexDocumentsMinionPipeline and the IDeleteIndexDocumentsMinionPipeline pipelines.
Other minions available out-of-the-box, such as DeletedCustomersIndex and DeletedCatalogItemsIndex, for example, delete different entities lists from the search indexes.
Commerce Orders minions
Order process minions play a key role in the overall order process flow, moving orders from list to list, as they transition from the initial pending status, to the final order completed status.
Purge Carts minion
The PurgeCartsMinion minion runs as a maintenance process that deletes abandoned or empty carts from the database, after they have become eligible for deletion based on a predefined threshold.
The PurgeCartsMinion minion watches a list of carts ("ListsToWatch": "Carts") and runs every 24 hours ("WakeupInterval": "01.00:00:00").
The PurgeCartsPolicy configuration determines the threshold (in number of days) after which the minion deletes empty or abandoned carts from the cart list. The following example shows the policy settings as defined in the sample Plugin.AdventureWorks.CommerceMinions.json file (packaged as part of the Sitecore.Commerce.Engine.SDK).
{
"$type":"Sitecore.Commerce.Plugin.Carts.PurgeCartsPolicy, Sitecore.Commerce.Plugin.Carts",
"AbandonedCartsThreshold": 14,
"EmptyCartsThreshold": 2
},Based on the preceding policy definition:
-
an abandoned cart becomes eligible for deletion after 14 days of inactivity.
-
an empty cart becomes eligible for deletion after 2 days of inactivity.
The PurgeCartsMinion minion calls the IPurgeCartsMinionPipeline pipeline.
Purge Catalogs minion
The PurgeCatalogsMinion minion runs as a maintenance process that purges deleted catalogs from the database. When catalogs are deleted, for example using the Business Tools user interface or using the sample Delete Catalog request in Postman, they are placed on a list of deleted catalogs. The Purge Catalogs minion watches that list ("ListsToWatch": "PurgeCatalogs"), and purges the database of listed deleted catalogs at a set interval. By default, the minion runs every 5 minutes.
In the Sitecore XC Business Tools, deleted catalogs continue to appear in search results until the Purge Catalogs minion runs and effectively deletes them from the database.
When deleted catalogs are purged from the database:
-
Sellable items that are only associated with deleted catalogs are deleted from the database.
-
Categories that are associated with deleted catalogs are also purged from the database.
The following example shows the default PurgeCatalogsMinions policy, as defined in the Plugin.Minions.PolicySet-1.*.*.json file:
{
"$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
"WakeupInterval": "00:05:00",
"ListsToWatch": [
"PurgeCatalogs"
],
"FullyQualifiedName": "Sitecore.Commerce.Plugin.Catalog.PurgeCatalogsMinion, Sitecore.Commerce.Plugin.Catalog",
"ItemsPerBatch": 10,
"SleepBetweenBatches": 500
},You can execute the Run Purge Catalogs Minion request in Postman to forcefully purge deleted catalogs from the database.
Considerations when purging large catalogs
The PurgeCatalogsMinion and PurgeCategoriesMinion minions run as transactional processes. They are based on the System.Transactions.TransactionScope class, and use the Sitecore.Commerce.Core.Commands.CommerceCommand.PerformTransaction() method for deleting catalogs or categories from the database.
The MachineSettingsSection.MaxTimeout property sets a maximum amount of time allowed before the transaction times out. The timeout default value is 10 minutes. When you purge a very large number of entities from the database, the transaction can timeout before the purge operation completes. To avoid timeout error, consider changing the value of the MachineSettingsSection.MaxTimeout property. Deleting categories from the catalog before you execute the purge operation can also help avoid timeout errors.
When you invoke the Import Catalogs request using the replace mode, the command also triggers the PurgeCatalogsMinion minion in the background. This is required to remove existing catalogs that are being replaced. Changing the value of the MachineSettingsSection.MaxTimeout property during large catalog import operations can help avoid timeout errors.
Purge Categories minion
The PurgeCategoriesMinion runs as a maintenance process that purges deleted catalog categories from the database. When categories are deleted from a catalog, for example using the Business Tools user interface or using the sample Delete Category request in Postman, they are placed on a list of deleted categories. The Purge Categories minion watches that list ("ListsToWatch": "PurgeCategories"), and purges the database of listed deleted categories at a set interval. By default, the minion runs every 5 minutes.
In the Sitecore XC Business Tools, deleted categories continue to appear in search results until the Purge Categories minion runs and effectively deletes them from the database.
The following shows an example of the default PurgeCategoriesMinion policy, as defined in the Plugin.Minions.PolicySet-1.*.*.json file:
{
"$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
"WakeupInterval": "00:05:00",
"ListsToWatch": [
"PurgeCategories"
],
"FullyQualifiedName": "Sitecore.Commerce.Plugin.Catalog.PurgeCategoriesMinion, Sitecore.Commerce.Plugin.Catalog",
"ItemsPerBatch": 10,
"SleepBetweenBatches": 500
},You can execute the Run Purge Categories Minion request in Postman to forcefully purge deleted categories from the database.
Archive entities minion
The ArchiveEntitiesMinion runs as a maintenance process that archives Commerce entities based on eligibility, such as cancelled or completed orders, or staled order journal entries.
The PlugIn.Minions.PolicySet-1.0.0.json file defines two instances of the ArchiveEntitiesMinion minion, each one responsible for the archiving of a Commerce entity type, that is, order entities and journal entry entities.
The path to the sample minions policy set file is wwwroot/data/Environments/PlugIn.Minions.PolicySet-1.0.0.json.
Entity archiving is disabled by default and is configurable per entity type, per environment by updating the entity archiving policies.
By default, entity archiving minions are configured to run every 24 hours. Before changing this default behavior, consider these recommendations and best practices.
Archive entities minion for journal entries
The instance of the ArchiveEntitiesMinion minion that is responsible for archiving entries from the orders journal watches a list of order journal entries (ListsToWatch":"JournalEntries"). It runs every 24 hours ("WakeupInterval": "01.00:00:00"), and archives order journal entries after a configurable number of days.
The following shows an example of the ArchiveEntitiesMinion minion instance configured to archive entities of type "Sitecore.Commerce.Plugin.Journaling.JournalEntry, Sitecore.Commerce.Plugin.Journaling":
{
"$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
"WakeupInterval": "01.00:00:00",
"ListsToWatch": [
"JournalEntries"
],
"FullyQualifiedName": "Sitecore.Commerce.Plugin.Archive.ArchiveEntitiesMinion, Sitecore.Commerce.Plugin.Archive",
"ItemsPerBatch": 10, //NOT USED//
"SleepBetweenBatches": 500,
"Entities": {
"$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
"$values": [
"Sitecore.Commerce.Plugin.Journaling.JournalEntry, Sitecore.Commerce.Plugin.Journaling"
]
}
},The archive entity minion that archives staled journal entries does not use the "ItemsPerBatch" property. Instead, It uses the "BatchCount" property defined in the ArchiveOrderPolicy policy, which is configurable in the minions environment file ( PlugIn.Habitat.CommerceMinions-1.*.*.json ).
Archive entities minion for inactive orders
The instance of the ArchiveEntitiesMinion minion that is responsible for archiving inactive orders watches a list of orders ("ListsToWatch":"Orders"). It runs every 24 hours ("WakeupInterval": "01.00:00:00"), and archives orders that have been completed or cancelled for a configurable number of days.
The following shows an example of the ArchiveEntitiesMinion minion instance configured to archive entities of type "Sitecore.Commerce.Plugin.Orders.Order, Sitecore.Commerce.Plugin.Orders":
{
"$type": "Sitecore.Commerce.Core.MinionPolicy, Sitecore.Commerce.Core",
"WakeupInterval": "01.00:00:00",
"ListsToWatch": [
"Orders"
],
"FullyQualifiedName": "Sitecore.Commerce.Plugin.Archive.ArchiveEntitiesMinion, Sitecore.Commerce.Plugin.Archive",
"ItemsPerBatch": 10, //NOT USED//
"SleepBetweenBatches": 500,
"Entities": {
"$type": "System.Collections.Generic.List`1[[System.String, mscorlib]], mscorlib",
"$values": [
"Sitecore.Commerce.Plugin.Orders.Order, Sitecore.Commerce.Plugin.Orders"
]
}
},The archive entity minion that archives inactive orders does not use the "ItemsPerBatch" property. Instead, It uses the "BatchCount" property defined in the ArchiveOrderPolicy policy, which is configurable in the minions environment file, for example, PlugIn.Habitat.CommerceMinions-1.*.*.json.
The policies that define the eligibility criteria for entity archiving are also configurable in the minions environment file, for example PlugIn.Habitat.CommerceMinions-1.*.*.json.
Recommendations for archiving minions configuration
When entity archiving is enabled, the process of moving large amount of data to the archiving database can impact the performance of your SQL service. It is good practice to keep the amount of data to archive to a minimum.
To avoid burdening the SQL service with unmanageable amount of data to archive, Sitecore recommends to run archiving minions on a daily basis. Default minions configuration reflects this recommendation, where minions are set to run every 24 hours ("WakeupInterval: "01.00:00:00").