User indexes

A user index is an index of all user data on a solution – standard user fields and standard custom fields. It does not contain information about user behavior – order value, other statistics, etc. User indexes are typically used when you want to e.g. publish a list of users to frontend using the query publisher and when you want to use queries to select lists of recipients for email marketing campaigns.

To create a user index:

1. Go to Settings > Repositories and open/create a repository.
2. Under the indexes section, click manage.
3. Click New index.
4. Provide a Name to the index.
5. Select a Balancer
   • Dynamicweb.indexing.balancing.ActivePassive - selects the next instance on the list of instances – so if instance A is unavailable (building, has failed), instance B will be used unless it’s unavailable, in which case instance C will be used, and so on.
   • Dynamicweb.indexing.balancing.LastUpdated - directs operations to the most recently updated index, ensuring users interact with the freshest data.
6. Click Save and close.

On solutions with heavy traffic and frequent product data updates we recommend using the LastUpdated mode to ensure that visitors are always shown the most recently updated product data. On solutions with only two instances (the vast majority of solutions) it is not necessary to select a balancer mode, as the “other index” will always be used when an index is unavailable.

When this is done, an empty index has been created. You should now add instances to it.

Adding Instances

An instance refers to a specific file stored in the file archive. When a query is executed, it's this file that gets searched. It's common for instances to be rebuilt regularly to incorporate the latest changes to product data. For this reason, it's recommended to maintain at least two instances. Having multiple instances ensures that while one is being updated or rebuilt, the other remains available for searches.

To create two instances:

1. In the Indexes section in your repository, and enter the index in which you want to add an instance to
2. Click the Actions button the on top right corner and select Manage instances
3. Click New instance
4. Provide a name – you could call the first instance ‘ Users A’ and the second instance ‘Users B’
5. Select the LuceneIndexProvider
6. Specify a folder to place the instance file under
7. Click Save and close
8. Repeat the process for the second instance

Once created, the two instances will look like this: When an instance is built a set of index files are generated under System > Indexes > YourIndexName > YourInstanceName – but before you can build it you must create a build configuration.

Adding a Build Configuration

So now that you have two instances you want to build them – to do so, you need to create a build definition. Each type of index has a specific builder associated with it – in the case of a user index this builder is helpfully called the UserIndexBuilder.

To add the build configuration:

1. Enter the Index in which you want to create a Build
2. Under the Builds section, select Manage
3. Click New build
4. Provide a name
5. In the Builder section, select Dynamicweb.Security.UserManagement.Indexing.UserIndexBuilder - this opens a selection of builder settings
6. Select a Builder action:
   • Full rebuilds the whole index
   • Update rebuilds the products which have edited in the timespan between the current time and the HoursToUpdate builder setting
   • UpdateWithIds is a mode used by the system to update smaller batches of products as they are saved in e.g. PIM
7. Review the builder settings
8. Set up Notifications if appropriate
9. Click Save and close

The following builder settings are available – please review carefully to see if any of them are relevant for your setup:

Setting	Value	Comments
HoursToUpdate	Integer – default is 24	Used by the Update builder action to find a list of users to index
DoNotFailOnMismatchingCount	Boolean - defaults to true	When true, the index will not fail to build if a user has been created or deleted while the index was being built

Now, a build button has been added to your instances: So now you’ve specified how you want the index to be built – you should now specify what you want to include in the index.

Adding Fields

Lucene indexes are composed of small documents, with each document divided into named fields which contain either content which can be searched or data which can be retrieved. Each field added to the index can therefore be stored, indexed, and analysed depending on what you want to use it for:

• Stored fields have their values stored in the index
• Indexed fields can be searched, the value is stored as a single value
• Analysed fields have their values run through an analyser and split into tokens (words)

Generally speaking:

• A field you want to display in frontend must be indexed
• A field where you want to search for part of the value in free-text search must be analysed
• A field which are to be published using the Query publisher should be Stored
• A field you want to display as facets should be indexed, but not analysed

To make things (a lot) easier for you, we’ve created a default set of fields typically used in user indexes – this default field set is defined in something called the UserIndexSchemaExtender.

To add the fields from the schema extender to the index:

1. In your index, click the Fields tab
2. Under the Fields section, click Manage
3. Click New index field and select Schema extender
4. Provide a name
5. Provide a system name
6. In the Field section, select UserIndexSchemaExtender
7. In the Settings section, select the fields you want to include
8. Click Save and close

This adds a whole bunch of fields to the index. Most of these fields are standard user fields or custom user fields. However, there are also several fields that are generated every time the index is rebuilt:

Field	Field content
Groups	An array of user group IDs where the user is a member
GroupNames	An array of user group names where the user is a member
Is Admin	True if System Administrator or Administrator
Combined order totals	The sum of Order Price with VAT from orders completed by this user
Largest order price	Largest Order Price with VAT entry associated with this user
Order count for last 30 days	A count of completed orders associated with this user within the last 30 days
Bought products	An array of product IDs from order completed by this user
Loyalty points total	The sum of LoyaltyUserTransactionPoints from EcomLoyaltyUserTransaction associated with this user
Loyalty point last added	A DateTime entry of the last time loyalty points were added to the users
Loyalty point next expiry	Oldest loyalty point transaction date by the user summed with global setting /Globalsettings/Ecom/LoyaltyPoints/ExpirationPeriodInMonths

For each field you can see the Name, System Name, and Type – and whether the field is stored, indexed and/or analysed. You can also add fields to the index manually – see the Custom Fields article.

Building the Index

Once you’ve added instances, a build configuration, and a set of fields to the index you should build it – to do so click the build button at the bottom of the instance. Of course, you don’t want to do this manually every time – you want to do a combination of the following:

• Rebuild the index every time an integration job has been executed
• Rebuild the index on a schedule – see the article on tasks