List locking

The List Manager uses the sitecore_analytics_index index as a data source. While lists are processed, Sitecore, by default, locks the contact lists and populates the sitecore_analytics_index index from the Analytics database.

This means that when you add or remove contacts from a list or clear an entire list, the list locks and you cannot use it in any application, such as EXM, until the processing is complete. This ensures that all contacts in a list are indexed and ready before the list is used. A list unlocks when the unlock list agent has checked and confirmed that all operations have finished.

Note

Refer to the Knowledge Base to troubleshoot list locking issues.

This topic outlines:

List locking when importing contacts

When you import contacts from a CSV file, the following actions occur in the background:

  • A contact list is generated based on the data in the CSV file.

  • The expected number of contacts in the import file is saved to the Recipients field on the contact list item.

    Note

    The expected number of contacts is the number of contacts in the CSV file minus the locked contacts or contacts with an invalid identifier.

  • The associated list is assigned to the imported contacts.

  • The imported contacts are added to the Analytics database in the Contacts collection.

  • A Mongo entry is created in the contact processing pool. It stores information about a contact and how it should be updated in the Reporting database and the Analytics index.

  • The imported contacts are updated in the Analytics index.

  • The unlock list agent (Sitecore.ListManagement.Analytics.UnlockContactListsAgent) checks that all jobs are complete and that all the contacts are added to the Analytics index, and then it unlocks the list.

Disabling list locking

There are situations where you want to make multiple changes to a list within a short period, for example, during email message dispatches or when large numbers of list subscriptions and unsubscriptions can occur at the same time. In these cases, list locking is not appropriate.

In Sitecore XP 8.2 Update 2 or later, to disable list locking:

  • Enable the Sitecore.ListManagement.DisableListLocking.config.disabled file.

    Note

    When you disable list locking, you can enable the EXM.CheckRecipientListsStatus setting in the Sitecore.EmailExperience.ContentManagement.config file to check if the expected and the actual number of contacts match before you dispatch the email campaign.

When you disable list locking, you must be aware that:

  • It can lead to inconsistencies in the number of contacts that are available in a contact list or in an EXM dispatch, versus the number of expected contacts. This can occur because the contact list is not locked and another user can access the contact list while you are editing it.

  • A contact list can be used in EXM immediately after import, even if most of the contacts in the list have not been processed yet. This can result in an email message being sent to a smaller number of recipients than intended. To ensure that the list count is as expected before an EXM dispatch, check the list count in the List Manager.

  • Incomplete contact lists are available for use as sources for other lists. This can result in incomplete child lists. To ensure that the list count is as expected before proceeding with a new list, check the list count of any source list in the List Manager.

  • Multiple users can edit incomplete contact lists at the same time. If the list sources are edited while the contact associations are being written and indexed, the resulting lists might not match your expectations. You must align your list management processes and user groups to take into account the potential impact of concurrent editing.