Automated Collections for Moderators

Automated collections keep source collections organized without manually adding every source. A moderator defines a rule for a repository, and the system creates the required child collections from parts of the reference code, such as fund, inventory, and case. Matching sources are added to the deepest generated collection.

This guide is for admins, moderators, and sources moderators.

What Automated Collections Do

Automation works from a source's repository links. For each source, the system looks at the ReferenceCode for the selected repository, applies the configured regex, and extracts the logical parts of the archive signature.

For example, this code:

280-2-1476

can be extracted as:

fund = 280
inventory = 2
case = 1476

If hierarchy levels are fund, inventory, the system creates:

DAKO
  Fund 280
    Inventory 2
      sources for cases 1475, 1476, ...

The source is added only to the deepest generated collection. In this example, that is Inventory 2, not the root DAKO collection.

Who Can Configure Automation

Automation can be configured by:

admins;
moderators;
sources moderators.

A moderator can attach automation to an existing manually created collection, even if they are not the owner. Normal collection editing, child collection management, and manual memberships still follow owner, editor, or admin permissions.

Option 1: Root for a Whole Repository

Use this when the collection represents an entire repository or a broad repository section.

Example for DAKO:

DAKO
  Fund 280
    Inventory 2
      sources

In the collection form:

Title: DAKO
Repository: State Archive of Kyiv Oblast (DAKO)
Reference code regex:
^(?<fund>\d+)-(?<inventory>\d+)(?:-(?<case>\d+))?$

Capture mappings:

fund      -> groupName fund, required
inventory -> groupName inventory, required
case      -> groupName case, optional

Hierarchy levels:

fund, inventory

Rule text can be a simple human-readable description:

archiveRef(repository:<repository-id>, pattern:"^(?<fund>\d+)-(?<inventory>\d+)(?:-(?<case>\d+))?$")

Option 2: Root for a Specific Fund

Use this when the collection itself already represents a fund, such as Fund 280.

In that case, do not create another fund child. Fix the fund in the regex:

^280-(?<inventory>\d+)(?:-(?<case>\d+))?$

Capture mappings:

inventory -> groupName inventory, required
case      -> groupName case, optional

Hierarchy levels:

inventory

Result:

Fund 280
  Inventory 2
    source cases

When Funds Have Letter Prefixes

Ukrainian archive funds may include letters, for example:

Р5597-1-12051

If the rule should accept both ordinary numeric codes and Р-prefixed codes, use:

^[РP]?(?<fund>\d+)-(?<inventory>\d+)(?:-(?<case>\d+))?$

This accepts:

280-2-1476
Р5597-1-12051
P5597-1-12051

The group names stay the same:

fund
inventory
case

How to Fill Capture Mappings

Prefer named groups. They are much harder to misconfigure.

Correct:

key fund      -> groupName fund
key inventory -> groupName inventory
key case      -> groupName case

Do not put the fund number into groupIndex. groupIndex means the regex capture group number: 1, 2, 3. If you enter groupIndex = 127, the system will try to read regex group number 127, not fund 127.

For most rules, avoid groupIndex entirely.

How IsActive Works

IsActive controls automated processing.

IsActive = true means the system can add new automation-owned memberships, create missing child collections, and remove stale automation-owned memberships after source updates.
IsActive = false means the system skips adds and removals for that automation rule. The current state is effectively frozen.

Manual memberships are never removed by automation.

When Results Should Appear

There are two reconciliation paths:

When a source is created or updated, the system reconciles that one source.
A background job periodically scans active rules and repairs missed updates.

Important: creating a new automated collection does not immediately process every old source. For existing sources, wait for the background job or trigger it manually in Hangfire.

In local development, the job is named:

collection-automation-reconciliation

How to Test a Rule

Before saving the rule, take 3-5 real reference codes from sources linked to the same repository and check whether the regex accepts them.

Example:

280-2-1476        -> should match
Р5597-1-12051     -> should match only if the rule allows the Р prefix
ДАКО/280/2/1476   -> will not match a short-signature rule

If a source has several repository links, automation uses only the ReferenceCode that belongs to the selected repository. A FamilySearch or Wikisource code will not satisfy a DAKO rule.

Common Mistakes

Selecting the wrong repository.
Sources do not have a ReferenceCode for the selected repository.
The regex accepts only 280-2-1476, but real codes look like Р5597-1-12051.
The fund number is entered into groupIndex.
A mapping points to a group that does not exist in the regex.
Expecting an existing manual child collection to be adopted automatically. Automation currently finds generated children by ruleKey, not by title.
Expecting sources to appear on the root collection. Sources are added to the deepest generated level.

Editing a Rule

Edit the root automated collection. Generated child collections display automation metadata, but their automation settings are not meant to be edited manually.

When changing the regex or hierarchy levels:

Check which generated collections already exist.
Change the rule on the root collection.
Run or wait for reconciliation.
Verify whether older generated branches are still useful.

Automation manages source memberships, but it does not automatically delete old empty generated collections.

Practical Recipe for a New Archive

Create a root collection named after the archive or fund.
Enable automation.
Select the correct repository.
Add a regex that matches real archive signatures.
Add capture mappings using named groups.
Set Hierarchy levels.
Save.
Update one test source with a matching ReferenceCode.
Check that child collections were created.
For existing sources, run or wait for background reconciliation.