Propagate and reconcile SharePoint metadata

Draft documentation

This guide is a draft. Validate it against the approved release package and customer operating procedure before using it for a production operation.

Use this guide to populate selected fields on existing child documents in SharePoint Document Sets. Configure Shared Fields, preview the database-to-parent and parent-to-child differences, apply reviewed corrections, then verify the children.

The tool uses the Brief Connect database as the source of truth. It updates Document Set parent values and relies on SharePoint Shared Fields to propagate those values to child documents. During Apply, it can also update the ABCDocumentMetadata snapshot on child documents directly.

For the normal operator path, use the quick start. This guide also covers connection setup, explicit scope limits, diagnostics, and recovery.

Use an authorised operator

Run this tool only from the approved Election Readiness tools virtual machine (VM). The operator needs access to the tool package and its output folder but does not need access to the secrets stored in Azure Key Vault.

Before you begin

Check the following prerequisites for your VM and target environment:

The complete win-x64 self-contained tool package is installed on the VM.
The VM system-assigned managed identity is enabled and has access to the required Key Vault secrets.
The Brief Connect Server App certificate and required Microsoft Graph and SharePoint permissions are configured.
The VM can connect to Key Vault, Microsoft Graph, SharePoint, and the active Brief Connect database services.
You can write to a protected output location with enough free space for all reports and logs.
You know the target environment's DbType and Key Vault secret names. Do not copy database settings from a different environment.
You have selected the approved site, record types, and fields. You can check VM connections before making this selection.

Use PowerShell for all commands in this guide. Run the commands from the folder containing E2.BriefConnect.MetadataPropagation.exe. Each command is independent and does not require PowerShell variables from an earlier step. Replace quoted example report paths and hashes directly in the command with your exact retained values.

Estimate scope and size the VM and disk

Before running a large production job, estimate how many fields, Document Sets, and child documents are in scope and confirm that the tools VM has enough disk space and RAM.

1. Determine how many fields, Document Sets, and child documents are in scope

Total workload is driven by two numbers:

Document Sets ($D$) — the number of parent record folders across all matching libraries.
Evaluated comparisons ($R$) — the total library items ($I_{\text{total}} = D + C$, combining Document Sets $D$ and child documents $C$) multiplied by the number of selected fields ($F$): Comparisons (R) = Total library items (D + C) × Selected fields (F) (Using $I_{\text{total}} \times F$ covers both parent-to-database comparisons $D \times F$ and child-to-parent comparisons $C \times F$, including NoChildren rows when Document Sets are empty.)

Use these read-only checks to determine $F$, $D$, and $C$ before making any changes:

Count selected active fields ($F$): If your run.json lists explicit Fields, $F$ is the number of fields configured for that record type. If you set "AllFields": true (or want to confirm how many active fields exist in Brief Connect), run read-only field diagnosis:
```
.\E2.BriefConnect.MetadataPropagation.exe check-fields --config .\run.json --output-format table
```
The console summary and diagnostic report.json list every resolved active field for each selected record type.
Confirm matching libraries with read-only preparation: Run read-only preparation to confirm the active field count ($F$) and discover all matching libraries for the selected record types without modifying SharePoint:
```
.\E2.BriefConnect.MetadataPropagation.exe prepare --config .\run.json
```
Review the resolved libraries in report.json. (By default, prepare validates content-type schemas only; exact Document Set count $D$ and child document count $C$ are recorded when fill-child-docs / scan runs, or when TriggerSharedFieldsPropagation=true is previewed.)
Estimate total library items ($I_{\text{total}} = D + C$) and total comparisons ($R$): Before running fill-child-docs, open SharePoint Site contents and check the total item count ($I_{\text{total}}$) of the discovered libraries for that record type. Multiply $I_{\text{total}} \times F$ (and sum across record types if several record types are in scope) to estimate $R$. Once fill-child-docs runs, its console summary and report.json report the exact DocumentSetCount ($D$) and ChildDocumentCount ($C$).

2. Choose VM RAM and data disk capacity

The tool streams child-document inventories, comparisons, database lookups, and verification rows through disk-backed spools (FileBackedKeyIndex, FileBackedJsonList, FileBackedRowGroups) rather than holding all child rows in memory:

Process RAM vs. Windows OS and file-cache RAM: Even at 1,000,000 child-field comparisons (10,000 child documents × 100 fields), the tool process working set stays around ~190–200 MiB (~405 MiB peak aggregate RSS; < 10 MiB managed heap after GC), while parent-level reconciliation state adds approximately ~12 MiB of managed memory per 100,000 parent-field pairs ($D \times F$) (for example, ~12 MiB per 1,000 Document Sets at 100 fields). However, Windows Server 2022 Datacenter + Trusted Launch + Microsoft Defender (MsMpEng.exe) + an active RDP session consumes ~2.0–2.4 GiB of RAM before the tool starts, and the OS requires additional free RAM to cache the .lookup/.index/.data spool files on disk.
Disk space and IOPS scale linearly with total comparisons ($R$): Retaining full hash-verified JSON, CSV, and checkpoint evidence across the complete Golden Path (prepare → fill-child-docs → apply → verify) requires approximately 22 KB of retained storage per comparison (~24.5 KB per comparison for a single-pass peak, or ~32.2 KB per comparison with headroom for a repeat verify pass).
- Phase breakdown per 1,000,000 comparisons: prepare (~0.5 MB), fill-child-docs (~8.8 GB retained / ~12.7 GB phase peak), apply (~8.2 GB retained / ~11.9 GB phase peak), verify (~5.0 GB retained / ~7.5 GB phase peak).

Workload tier	Evaluated comparisons ($R$)	Example scope (`DocSets × Children/DocSet × Fields`)	Observed / expected tool process RAM	Recommended VM size (Windows Server 2022)	Cumulative Golden Path disk (`prepare` + `fill-child-docs` + `apply` + `verify`)	Required free disk space before starting
Small	Up to `10,000`	`100 × 10 × 10` or `20 × 5 × 100`	~185–250 MiB	2 vCPU, 4 GiB RAM (minimum baseline) or 8 GiB RAM	~0.22 GB retained (~0.35 GB peak)	>= 5 GB free
Medium	`100,000`	`1,000 × 10 × 10` or `20 × 50 × 100`	~200–350 MiB	2 vCPU, 8 GiB RAM (4 GiB minimum if no other tools run)	~2.2 GB retained (~2.5–3.2 GB peak)	>= 10 GB free
Large (benchmarked)	`1,000,000`	`10,000 × 10 × 10` or `10 × 1,000 × 100`	~190–405 MiB (+ ~12 MiB per 100k $D \times F$)	2–4 vCPU, 8 GiB RAM (non-burstable; 16 GiB if $D > 25,000$)	22.0 GB retained (24.5 GB single-pass peak; 32.2 GB with repeat `verify`)	>= 45 GB free
Extra Large (extrapolated)	`5,000,000`	`50,000 × 10 × 10` or `50,000` children × `100` fields	~500–900 MiB	4 vCPU, 16 GiB RAM (non-burstable)	~110 GB retained (~123–161 GB peak)	>= 200 GB free (or split by site/record type)
Maximum (single scope) (extrapolated)	`10,000,000`	`100,000 × 10 × 10` or `1,000,000` children × `10` fields	~850 MiB–1.5 GiB	4 vCPU, 16 GiB RAM (non-burstable)	~220 GB retained (~245–322 GB peak)	>= 400 GB free (or split into smaller library/type runs)

See Infrastructure Requirements for the corresponding Azure VM SKUs (Standard_D2s_v5, Standard_D4s_v5) and managed disk tiers (Premium SSD P10/P15/P20).

Keep at least 1.5x peak disk headroom and do not open multi-GB reports in memory on the VM

Adding RAM does not reduce the disk space required for retained JSON/CSV reports and journals. If a single job exceeds 1,000,000–1,500,000 comparisons on a baseline 64 GiB data disk, either expand the data disk before starting or run one RecordType or explicit LibraryServerRelativeUrl scope at a time and archive completed run folders to approved storage between jobs.
On large runs (1,000,000+ comparisons), report.json and report.csv are several gigabytes on disk. Do not open them in Notepad or Excel on the runner VM, and do not run Get-Content -Raw | ConvertFrom-Json on report.json—copy ReportHash from the console summary or use Select-String instead.

Run the workflow

The release ZIP contains only the executable and Readme.txt. Configuration examples and operating instructions are provided in this published User Guide, not in the package. Copy the example matching your environment from Create the run configuration into run.json, then fill its connection settings, site URL, record types, and fields. Store resource identifiers and Key Vault secret names, never credentials.

Check the VM connections first

Check the virtual machine (VM), output location and environment connections before selecting fields:

.\E2.BriefConnect.MetadataPropagation.exe check-vm --config .\run.json

This command does not require RecordTypes or Run.SharedFieldAudit. You may start with only Environment and the top-level SiteUrl. Each check reports Passed, Failed, or NotChecked; fix the reported property using the guidance below, then rerun it. If you omit both SiteUrl and Sites, site authentication/access is NotChecked and the overall result is PARTIAL, not a ready-to-run confirmation. Exit code 0 means there are no failed checks; also require ConnectivityComplete=true before treating connectivity as checked.

The command reads application configuration and probes database connectivity without reading business-record values. It checks certificate retrieval and Graph read access to each supplied site. It performs no remote writes. Write permissions, field-specific SharePoint/CSOM access, operation-specific disk capacity, and child propagation are not proven by this check.

Select the site, record types and fields

Set the top-level SiteUrl once. Fill RecordTypes[].Name with the exact Brief Connect record-type names and select the approved field InternalName values. The tool creates a scope for each selected site/type and finds matching libraries and Document Sets. You do not need partition keys, record IDs, monthly library lists, or repeated site URLs. ContentTypeId is optional; you do not need to look it up for the normal workflow.

The job covers all matching libraries in the selected site. Review that scope before writing. It processes existing SharePoint Document Sets; it does not create missing Document Sets or find database-only records. Use explicit scope limits when the approved job must be narrower.

The minimal examples use automatic child checks and schema-only preparation. They leave retry, concurrency, and output filenames at their defaults. Do not set AllFields=true merely because you want all documents in the approved scope; that option selects all active fields, not more documents.

The short commands use dry-run by default and create a unique evidence directory beneath Run.OutputRoot. If the configuration omits Run.OutputRoot, the tool uses a runs directory beside the config. At the end of the run, use the Reports section to locate the JSON report for handoff to the next phase. Retain the complete report folder and copy the exact printed path, not an example path. Long paths can span several lines; reconstruct the full path when copying it and preserve any spaces in the original folder names. Keep the same approved configuration across preparation, preview and Apply.

If you need to investigate selected fields before preparation, run check-fields first (see Diagnose selected fields before preparation). Its diagnostic report is not a preparation manifest; you must still run prepare and use that preparation report for later workflow phases.

.\E2.BriefConnect.MetadataPropagation.exe check-fields --config .\run.json --output-format table

Preview Shared Fields preparation

Inspect the existing content type and its library copies without changing them:

.\E2.BriefConnect.MetadataPropagation.exe prepare --config .\run.json

Resolve the listed blockers before writing. If IsReadyForReconciliation=true, retain this read-only report and continue to the child preview. Otherwise, review the proposed schema changes and the complete preparation scope before authorising live preparation.

Preparation scope is broader than the audit library

SharedFields preparation works on the selected site content types and their library copies. Run.SharedFieldAudit.Scopes[].LibraryServerRelativeUrl restricts the audit, not schema changes. Review every library in the preparation report. With the minimal configurations, preparation does not trigger parent updates.

Apply only reviewed SharedFields schema changes when preparation is needed:

.\E2.BriefConnect.MetadataPropagation.exe prepare `
  --config .\run.json `
  --write `
  --confirm PREPARE

Use the ready report from this live preparation for subsequent steps. Preparation readiness does not mean that child values have been populated.

Preview child-document repairs

Replace the quoted example path with the exact ready preparation report path printed by the tool, then preview child-inclusive drift without writing:

.\E2.BriefConnect.MetadataPropagation.exe fill-child-docs `
  --config .\run.json `
  --preparation-report 'D:\approved-runs\prepare\report.json'

fill-child-docs uses the existing Scan workflow and includes child values even if IncludeChildValuesInScan is absent or false. It does not change the configuration file, approve the report, prepare schema, or apply corrections. It rejects write, force, resume and other workflow options. A ready preparation report is still required.

Review the complete scope, missing/unsupported fields, coverage and proposed corrections. A preview may return exit code 1 because it found drift; do not treat that as approval to write or ignore errors and incomplete coverage. Require PreflightPassed=true, an empty Errors list, and SharedFieldAudit.IsIncomplete=false. Review all applicable corrections in DatabaseRows, including any clearing of values. An absent database field is skipped; an explicitly empty value can clear a parent field.

Document Sets without a readable record identity, such as ABCRecordId, are skipped. Review their Skipped rows in the report. These rows cannot be applied and do not prove that the documents were processed.

Empty Document Sets produce neutral NoChildren warning rows by default (unless AllowEmptyDocumentSets is explicitly set to false). They do not prove that child values were filled. If there are no corrections or failures, skip Apply and continue to Verify. Otherwise, approve the exact JSON ReportHash. Do not edit the report.

Apply the reviewed repair and verify children

Replace both quoted example paths with the exact retained preparation and reviewed preview paths, and replace the quoted hash placeholder with the approved preview ReportHash. Then explicitly authorise Apply:

.\E2.BriefConnect.MetadataPropagation.exe apply `
  --config .\run.json `
  --write `
  --approval-report 'D:\approved-runs\child-preview\report.json' `
  --preparation-report 'D:\approved-runs\prepare\report.json' `
  --approval-hash '<approved-64-character-report-hash>' `
  --confirm APPLY

By default, Apply also attempts to synchronize database documentmetadata snapshots to the ABCDocumentMetadata column on eligible child documents. Set Run.SyncDocumentMetadataSnapshots to false to disable this step. The snapshot step is best-effort. Review its outcomes in the Apply report. If a Document Set is stale, eligible unrelated Document Sets can still receive snapshot updates.

Verify parent-to-child agreement independently after Apply, replacing the quoted example path with the same ready preparation report path:

.\E2.BriefConnect.MetadataPropagation.exe verify `
  --config .\run.json `
  --preparation-report 'D:\approved-runs\prepare\report.json'

Require exit code 0 and complete checks, then confirm the expected child coverage. Empty Document Sets do not prove propagation. Verify does not compare the database; run a new Scan when you also need database-to-parent agreement. If all approved parent writes succeeded but child values still differ, wait for SharePoint and repeat read-only Verify in a new output folder. Do not repeat Apply to force propagation.

Resolve common startup blockers

Use the terminal's property path and remedy to correct the reported setting:

Blocker	Action
Invalid JSON or an unknown property	Fix the indicated property, quotes or line break. Copy names from this guide's configuration examples; unknown or misplaced properties are rejected.
Modern connection/password secret name missing	Fill both secret names from this environment's backend Key Vault references. `ApplicationDatabaseSecretName` is required for Modern; do not remove it as a Legacy-only setting.
Field not active in the database record type	Confirm the exact `InternalName` and check that the field is active in the configured Brief Connect record type.
Column missing from a site/library content type	Synchronize active fields to SharePoint from the Brief Connect Admin Panel, then rerun read-only `prepare`. The tool does not create missing columns.
Taxonomy preparation cannot match a parent to the database	Check the environment, record type, and SharePoint identity column. Normal preparation reads exact records for discovered parents; it does not require a partition key. Do not guess a key to bypass a missing or ambiguous record.
Missing or mismatched persisted SharePoint link	Resolve the record's database/SharePoint link through the approved application process. Discovery alone does not establish a safe write target. Do not bypass the Apply guard.
Preparation is ready but children remain empty	Preview with `fill-child-docs`, review and Apply its report, then Verify. Repeating ordinary preparation may be a no-op when SharedFields are already correct.
Parent writes succeeded but child checks failed	Keep the failed Apply report. Wait for SharePoint, then run read-only Verify with a new output folder. Do not repeat writes only to retry child checks.

Use --output-dir <new-folder> to choose a specific run directory; it must not already exist. Optional per-artifact path overrides remain available, but every output must stay under the validated output directory. See the command-line reference for short commands and flag-based modes.

Create the run configuration

Choose exactly one example matching your environment's DbType, save it as run.json, and replace every connection URL, identifier and secret-name placeholder. Select the approved record-type names and field internal names. These complete minimal examples use one site URL and automatic site/type scopes. They check child values and keep preparation limited to schema changes. Confirm that all matching libraries are approved.

Modern

Use this Modern example when the Brief Connect database uses Azure DocumentDB's MongoDB-compatible API:

{
  "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect",
  "Environment": {
    "KeyVaultUri": "https://brief-connect-example.vault.azure.net/",
    "DbType": "Modern",
    "ApplicationDatabaseSecretName": "<modern-connection-string-secret-name>",
    "MongoDatabasePasswordSecretName": "<modern-password-secret-name>",
    "ClientId": "00000000-0000-0000-0000-000000000001",
    "TenantId": "00000000-0000-0000-0000-000000000002",
    "CertificateSecretName": "<server-app-certificate-secret-name>"
  },
  "RecordTypes": [
    {
      "Name": "Example Record",
      "Fields": [{ "InternalName": "Reference" }]
    },
    {
      "Name": "Another Record",
      "Fields": [{ "InternalName": "Department" }]
    }
  ]
}

Legacy

Use this Legacy example when the Legacy database connections are supplied through Key Vault connection-string secrets:

{
  "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect",
  "Environment": {
    "KeyVaultUri": "https://brief-connect-example.vault.azure.net/",
    "DbType": "Legacy",
    "ApplicationDatabaseSecretName": "<legacy-table-connection-secret-name>",
    "ConfigurationStorageSecretName": "<legacy-configuration-storage-secret-name>",
    "ClientId": "00000000-0000-0000-0000-000000000001",
    "TenantId": "00000000-0000-0000-0000-000000000002",
    "CertificateSecretName": "<server-app-certificate-secret-name>"
  },
  "RecordTypes": [
    {
      "Name": "Example Record",
      "Fields": [{ "InternalName": "Reference" }]
    },
    {
      "Name": "Another Record",
      "Fields": [{ "InternalName": "Department" }]
    }
  ]
}

Do not copy connection-string values into the JSON. Use the names of this environment's Key Vault secrets.

Legacy with managed identity

If this environment uses managed identity for Legacy Table and Blob access, use this alternative Legacy configuration. It omits the connection-string secret names and still creates the site/type scope automatically:

{
  "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect",
  "Environment": {
    "KeyVaultUri": "https://brief-connect-example.vault.azure.net/",
    "DbType": "Legacy",
    "LegacyStorageUseManagedIdentity": true,
    "LegacyTableServiceUri": "https://examplestorage.table.core.windows.net/",
    "LegacyBlobServiceUri": "https://examplestorage.blob.core.windows.net/",
    "ClientId": "00000000-0000-0000-0000-000000000001",
    "TenantId": "00000000-0000-0000-0000-000000000002",
    "CertificateSecretName": "<server-app-certificate-secret-name>"
  },
  "RecordTypes": [
    {
      "Name": "Example Record",
      "Fields": [
        {
          "InternalName": "Reference"
        }
      ]
    }
  ]
}

In either Legacy configuration, confirm the record identity field and access method against this environment's Brief Connect configuration. Do not combine Modern and Legacy database settings in one run.

Find your environment's connection settings

Use this environment's approved Brief Connect Function App configuration and its Key Vault references, not values from a different customer's run file. For a Key Vault reference, use the secret name identified by the reference, not the retrieved secret value. You do not need permission to reveal secrets.

Setting	Where to find it	What goes in the JSON
`SiteUrl`	The approved SharePoint site	The site HTTPS URL, once at the top level. The normal job discovers all matching libraries in that site.
`Environment.KeyVaultUri`	The environment's Key Vault overview and approved backend configuration	The vault HTTPS URL, not a secret URL or value.
`Environment.DbType`	This environment's active Brief Connect backend database configuration	`Modern` or `Legacy`; select explicitly.
`Environment.ApplicationDatabaseSecretName`	The active backend's record-store connection Key Vault reference	The secret name for the Modern MongoDB-compatible or Legacy Table connection string. Required except for Legacy managed identity.
`Environment.MongoDatabasePasswordSecretName`	The Modern backend's database-password Key Vault reference	The password secret name, never the password. Required for Modern.
`Environment.ConfigurationStorageSecretName`	The Legacy backend's application-configuration storage Key Vault reference	That connection secret name. Required for Legacy connection-string access only.
`Environment.CertificateSecretName`	The backend's Brief Connect Server App certificate-secret reference	The certificate secret name, never certificate data.
`Environment.ClientId`	The existing Brief Connect Server App registration's Overview page	Its Application (client) ID, not an object ID or secret name.
`Environment.TenantId`	The same application registration's Overview page	Its Directory (tenant) ID.
`Environment.LegacyTableServiceUri` / `LegacyBlobServiceUri`	The approved Legacy storage account's service endpoints	Table and Blob HTTPS endpoints when `LegacyStorageUseManagedIdentity=true`.

All three examples use the default SharePoint record identity column, ABCRecordId. Confirm the column's internal name for your environment; do not infer it from DbType. If it differs, use the custom identity setting.

For Modern, the secret named by ApplicationDatabaseSecretName contains the connection string. If it includes a password slot, keep the literal <password> placeholder there; the tool fills it from the secret named by MongoDatabasePasswordSecretName. For Legacy connection-string access, ApplicationDatabaseSecretName and ConfigurationStorageSecretName refer to separate Key Vault secrets. For Legacy managed identity, set LegacyStorageUseManagedIdentity to true and use the environment's Table and Blob service URIs instead of connection-string secret names.

Set a custom record identity column

If Document Sets store their database record ID in a column other than ABCRecordId, add this Run section to your chosen configuration. Replace RecordId with the approved internal name:

{
  "Run": {
    "SharedFieldAudit": {
      "RecordIdentityFieldInternalName": "RecordId"
    }
  }
}

This is an addition to the complete configuration, not a separate job file. Scopes are still created automatically. For explicit scopes, set RecordIdentityFieldInternalName on each scope instead.

Check the JSON syntax before running the tool

Run this local check after saving the configuration. It parses the file without connecting to Azure, SharePoint, or the database:

Get-Content -LiteralPath .\run.json -Raw | ConvertFrom-Json | Out-Null

If the local parser or tool reports invalid JSON with a line or byte position, fix the syntax before troubleshooting credentials or connectivity. Check that every quoted value has matching quotes and that no raw line break was pasted inside a quoted value. A successful parse confirms JSON syntax only; it does not confirm that secret names, permissions, or field configuration are correct.

All three complete configurations use the default read-only preparation. Short phase commands remain read-only unless you supply a supported explicit --write option. Review the report before authorising a write.

Keep optional settings at their defaults

Select the site, record types, and fields. Omit tuning and artifact filenames unless your operation requires an explicit override:

Setting	Required or default behaviour
`SiteUrl`	Set once for a normal single-site job. It supplies the selected site and fills omitted scope or target URLs.
`Sites[].SiteUrl`	Use for an explicit site list. Omitting both `SiteUrl` and `Sites` gives partial site-connectivity evidence in `check-vm`.
`RecordTypes[].Name`	Required for operational phases; not needed by `check-vm`. Use the exact Brief Connect record-type name.
`RecordTypes[].Fields`	Select at least one exact `InternalName`, or explicitly use `AllFields=true` with empty `Fields` when every active field is approved.
`RecordTypes[].ContentTypeId`	Optional; resolved from Brief Connect configuration or the unambiguous content-type name.
`Run.SharedFieldAudit.Scopes`	Optional for the normal job; generated from selected sites and record types. Use explicit scopes for library limits or partition-wide database audits.
`LibraryServerRelativeUrl`	Optional in an explicit audit scope. Omit it to discover matching libraries within that scope's site. It does not limit schema preparation.
`RecordPartitionKey`	Omit for normal preparation, Scan, and child preview, including taxonomy fields. Set it in explicit scopes for partition-wide database inventory.
`Run.SharedFieldAudit.RecordIdentityFieldInternalName`	Default `ABCRecordId` for automatic scopes. Confirm the SharePoint column for your environment; explicit scopes have their own identity setting.
`Run.SharedFieldAudit.IncludeChildValuesInScan`	Default `true` for automatic scopes, `false` for explicit scopes. An explicit value wins. `fill-child-docs` always checks children.
`Run.SharedFieldAudit.AllowEmptyDocumentSets`	Default `true` for both automatic and explicit scopes. An explicit value wins. Set `false` only when empty Document Sets (`NoChildren`) should fail Scan and Verify.
`Run.TriggerSharedFieldsPropagation`	Default `false` with top-level `SiteUrl` or automatic scopes. Otherwise defaults to `true`. Set explicitly when you need a preparation parent trigger.
`Environment.MongoDatabaseName`	Default `BriefConnect`; override only for an approved different database.
Output filenames, retries, concurrency and polling	Omit for normal use; short commands create unique report folders beneath `Run.OutputRoot`, or a `runs` folder beside the configuration.
Audit limits	Defaults: `2,147,483,647` (`int.MaxValue`) for `MaxDocumentSets`, `MaxDatabaseRecords`, and `MaxAuditRows`. Explicit smaller caps remain supported; reaching an explicit limit is not complete coverage.

Set explicit site and library limits

Use the root SiteUrl for one site. For several sites, replace it with a Sites list and add an empty Run.SharedFieldAudit object. Keep Environment and RecordTypes from your chosen complete example:

{
  "Sites": [
    { "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect" },
    { "SiteUrl": "https://contoso.sharepoint.com/sites/another-site" }
  ],
  "Run": {
    "SharedFieldAudit": {}
  }
}

The tool creates one scope for each selected site/type. By default, MaxDocumentSets, MaxDatabaseRecords, and MaxAuditRows use the maximum supported integer limit (2,147,483,647). If you set an explicit Run.SharedFieldAudit.MaxAuditRows cap, automatic scopes divide that budget among them. Increase or lower limits only within the approved scope and available disk headroom (see Estimate scope and size the VM and disk). Unreadable or truncated discovery still fails.

To audit one library, add explicit scopes instead. This Run section limits value checks to Example Record in the named library, while keeping child checks and empty sets enabled:

{
  "Run": {
    "SharedFieldAudit": {
      "IncludeChildValuesInScan": true,
      "AllowEmptyDocumentSets": true,
      "Scopes": [
        {
          "RecordTypeName": "Example Record",
          "LibraryServerRelativeUrl": "/sites/brief-connect/Shared Documents"
        }
      ]
    }
  }
}

Keep the root SiteUrl, Environment, and selected RecordTypes in the complete job file. Select only the record types intended for preparation: a library audit limit does not limit schema changes. Merge additions into one Run object; do not create duplicate JSON properties.

An omitted scope URL uses the root SiteUrl, or the only selected site. Explicit Sites and scope URLs take precedence over defaults. With several sites and no root default, provide the URL for each explicit scope.

LibraryServerRelativeUrl is optional in Run.SharedFieldAudit.Scopes. If provided, the tool audits only that library; it does not restrict SharedFields schema preparation. If omitted, the tool discovers eligible document libraries containing the configured Document Set content type within the configured site. It blocks the scan if the discovered scope cannot be read completely. The WhatIf preparation report lists the resolved library paths and summarizes the library count. MaxDocumentSets and MaxAuditRows bound the total auto-discovered scope.

Choose SharePoint-first reads or database inventory

The normal prepare, scan, and fill-child-docs commands need no RecordPartitionKey. The tool uses SharePoint-first point reads: it reads each Document Set's configured record identity and looks up that exact database record. The Legacy adapter derives the point-read partition from the RecordId; Modern uses an exact RowKey lookup. This mode does not find database records that have no SharePoint Document Set. To inventory a whole database partition and detect those records, set an exact RecordPartitionKey in each explicit scope; that selects the full bulk-inventory mode. The flag-based --scan-drift bulk mode requires exact partitions for either database provider. Use short scan or fill-child-docs for the no-partition workflow. Target-scoped scans read one exact record and do not require a bulk partition key.

Taxonomy preparation also uses the bounded SharePoint parent inventory when no partition is set. It validates the selected values from each exact linked database record. Missing identities, missing or ambiguous records, wrong record types, and incomplete discovery remain blockers. Automatic discovery does not repair persisted database/SharePoint links.

For prepare with Run.TargetDocumentSet and TriggerSharedFieldsPropagation=true, provide the target's positive SharePoint ParentListItemId as well as its exact ServerRelativeUrl. The SharedFields propagation preflight uses a direct read of that list item and verifies the returned URL; it does not enumerate or plan triggers for other Document Sets in the library. Bulk preparation without TargetDocumentSet retains its existing library-wide behaviour.

Find a Legacy or Modern partition key for one target

If you need the key for a specific target record, run the read-only partition-key command with the same configuration. It uses the tool's configured database credentials and does not require you to access the database directly or connect to SharePoint. Run.TargetDocumentSet.RecordId and RecordTypeName are required, while RecordPartitionKey may be omitted:

.\E2.BriefConnect.MetadataPropagation.exe partition-key --config .\run.json

The command writes a JSON result to stdout and never enumerates the database. Modern performs a bounded point lookup by RowKey and returns a key only for one matching record with the expected type; missing or ambiguous matches fail closed. Legacy derives the point-read partition from the RecordId using its supported suffix rule (remove the final four sequence characters), then verifies the exact record and type. If RecordPartitionKey is already configured, the command verifies that value instead. The optional --json-report <new-path> flag writes the same result to a new JSON file; the path must not already exist.

The reported key applies only to that exact record. It does not establish which key covers a bulk scope or provide a full database inventory. Treat the stdout and optional JSON file as sensitive because they contain the partition key.

For a bulk database audit, add an exact RecordPartitionKey to the appropriate Run.SharedFieldAudit scope. This changes the short scan command from SharePoint-first point reads to partition-scoped database inventory. Do not guess a partition key: verify it against this environment's record-store configuration or use the read-only partition-key command for one exact target record.

RecordTypes[].ContentTypeId is optional. If omitted, the tool uses the content type ID from the application-database record-type definition. If that definition has no ID, Graph resolves by the configured content-type name and fails closed if the name is missing or ambiguous. Set the ID only when you want to pin an exact SharePoint content type.

Set RecordTypes[].AllFields to true only when every active field on that record type is in scope. When AllFields is true, leave Fields empty.

For a Legacy database environment, use the connection method and Key Vault secret names from its Brief Connect backend configuration. A run must use only one database model and cannot fall back to the other model.

Flag-based commands and custom output paths

Flag-based commands can set all five paths explicitly: CheckpointJournalPath, EventLogPath, CsvLogPath, DiagnosticLogPath, and JsonReportPath. Keep them under OutputRoot and use a different output folder per attempt. Short phase commands treat OutputRoot as a parent folder and generate new artifact paths; per-file paths configured in JSON are used only by flag-based commands.

Diagnose selected fields before preparation

Run this check when prepare blocks a selected field, or when you need to identify missing columns, content-type links, or Document Set Shared Fields before arranging a repair:

.\E2.BriefConnect.MetadataPropagation.exe check-fields --config .\run.json --output-format table

Use the approved environment settings, SiteUrl or Sites, and RecordTypes. Select fields by Fields[].InternalName, or set AllFields=true to check all active fields for a record type. Use explicit field names to investigate disabled or unconfigured fields; AllFields does not include disabled fields.

This command reads application configuration and SharePoint schema only. It does not scan business records, Document Sets, or child documents, read their metadata values, or write to SharePoint or the database. It needs no record ID, partition key, or SharedFieldAudit scope. Do not add --write, confirmations, force/resume options, or preparation/approval inputs; check-fields rejects them. Existing target/audit settings do not narrow this check: it inspects every matching library content-type copy within the configured sites and record types, including hidden columns.

Read the field diagnostic summary

Start with Status, then check Scope and the Fields table. Use What needs attention for field-specific reasons and actions, Next step for the follow-up command, and Reports for the complete diagnostic JSON.

Read the table from left to right:

Database identifies whether the field is active, disabled, or not configured for the selected record type. An existing SharePoint column does not make the field active.
Column checks the site column. CT link checks the field link on the site's Document Set content type (CT). Shared checks that site's Shared Fields membership.
Libraries shows linked / shared content-type copies. For example, 6/6 / 0/6 means all six library copies have the field link, but none include it in Shared Fields.
- means not checked. Unknown, or ? in library coverage, means the read could not be confirmed; it is not evidence that a field is missing. Resolve read/access failures first.

The console shows up to ten fields, with problems first, and combines identical actions. Use the complete JSON for omitted fields, per-library results, and detailed errors. If the report says the evidence limit was reached, narrow the selection and rerun; do not treat truncated evidence as a successful check.

Require exit code 0 for confirmed selected schema. Exit code 1 means field-configuration issues, schema gaps, or incomplete/read-failed checks; 2 means startup or output validation failed. Neither exit code 0 nor a Schema checked status confirms child values, write permissions, or readiness for reconciliation.

Diagnostic evidence is not approval

The check-fields report is read-only, diagnostic-only evidence, not a preparation or approval manifest. Do not supply it to --preparation-report or --approval-report. Resolve the reported issues, then run read-only prepare before reviewing any write.

Quickly verify SharedFields membership

Use the focused membership check when you need a quick ready/not-ready answer without running a preparation PATCH, scanning business records, updating Document Set parent values, or triggering SharedFields propagation.

Use check-fields instead when you need to diagnose disabled/unconfigured fields or compare columns, links, and Shared Fields. This membership check has a different purpose: it can produce a preparation confirmation for later workflow phases.

Run the read-only membership check with a separate set of output paths:

.\E2.BriefConnect.MetadataPropagation.exe `
  --config .\run.json `
  --verify-shared-field-membership `
  --json-report .\runs\membership\membership.json `
  --csv-log .\runs\membership\membership.csv `
  --event-log .\runs\membership\events.csv `
  --diagnostic-log .\runs\membership\diagnostic.log `
  --checkpoint-journal .\runs\membership\checkpoints.jsonl

The command reads the configured record-type metadata needed to resolve the field selection, but does not read business-record values. It freshly inspects the selected SharedFields membership on the site content type and each expected library copy. Review missing scopes/fields and read errors in the JSON/CSV report. A ready report is a hash-protected read-only preparation confirmation and can be supplied to Scan/Verify through --preparation-report.

Diagnose taxonomy mappings

Use the optional taxonomy diagnostic when preparation reports a managed-metadata field/value problem. It uses the exact Legacy/Modern database partition/type scopes in Run.SharedFieldAudit and compares configured field shape and term-set name, SharePoint field metadata, and persisted taxonomy values against that field's configured SharePoint term catalog. It does not scan Document Sets or child documents, change schema, or write to SharePoint or the database. Clear Run.TargetDocumentSet for this mode and provide bulk, exact-partition audit scopes. This diagnostic requires partition keys; normal taxonomy preparation does not.

.\E2.BriefConnect.MetadataPropagation.exe `
  --config .\run.json `
  --diagnose-taxonomy `
  --json-report .\runs\taxonomy\taxonomy.json `
  --csv-log .\runs\taxonomy\taxonomy.csv `
  --event-log .\runs\taxonomy\events.csv `
  --diagnostic-log .\runs\taxonomy\diagnostic.log `
  --checkpoint-journal .\runs\taxonomy\checkpoints.jsonl

By default the report redacts persisted term GUIDs and labels while retaining counts, resolution categories, whether GUID/label components were present, match cardinalities, and up to 20 value references per field/scope. To include up to 20 distinct non-exact GUID/label examples for operator investigation, explicitly add --include-taxonomy-values; those JSON/CSV artifacts contain customer taxonomy data and must stay in a restricted run folder. The command requires every configured SharedFieldAudit scope to use CompareWithDatabase=true and an exact RecordPartitionKey. A completed report may contain findings and still exit successfully; check IsComplete separately from the diagnostic findings.

Preview the Shared Fields preparation

Run preparation in its default what-if mode before making any SharePoint changes.

.\E2.BriefConnect.MetadataPropagation.exe prepare --config .\run.json

Use the console's Results, Work summary, and Next step sections to review the outcome, then locate the JSON and CSV in Reports. Full run identities and hashes appear separately under Run evidence. To keep a machine-readable console summary, use --output-format json; the file reports remain the complete retained evidence. Confirm that:

The site, libraries, record types, content types, and fields match the approved scope.
The report contains no errors or unsupported fields.
The planned Shared Fields changes are expected. Parent triggers are included only when explicitly enabled for the normal workflow.
ConfigurationFingerprint identifies the configuration you intend to use.
IsReadyForReconciliation is true, or the reported changes are safe to prepare.

If IsReadyForReconciliation is already true and there are no failures, retain the complete report generation and continue to Scan for metadata drift. Otherwise, resolve errors first. Perform live preparation only for reviewed schema changes.

Fix field configuration before writing

RecordTypes[].Fields[].InternalName selects a field for the workflow; it does not create the field, activate it in Brief Connect, or add it to SharePoint content types. Use the exact field internal name, not its display label.

If preparation stops during startup, read What needs attention and run check-fields with the same configuration. The startup table uses already loaded application metadata; its SharePoint cells are - (not checked). The startup artifact in Reports is diagnostic evidence, not a successful preparation manifest.

Resolve the reported database reason before arranging SharePoint changes:

Disabled means IsActive=false. Ask your Brief Connect administrator to confirm whether the field should be enabled. SharePoint cleanup cannot activate it.
Not configured means the field has no definition for this record type. Confirm the selected record type and exact internal field name before any approved configuration update.
Not active, Unavailable, Ambiguous, or Not checked requires further configuration investigation. Do not assume a missing column or bypass the startup gate.

Confirm that the DbType and secret names match the intended environment, correct the approved configuration, and repeat the read-only diagnosis.

If the field is active in the database configuration but is missing from the SharePoint site or library Document Set content types, confirm that the column exists and run the Brief Connect Admin Panel's SharePoint content-type synchronization for the active fields intended for synchronization. A field with ShowOnDashboard=false is excluded from that sync; confirm its intended configuration before changing it. Content-type synchronization and cleanup do not repair Shared Fields membership.

If field links are present but Shared Fields membership is missing, resolve any remaining configuration/read failures, then rerun read-only prepare to preview the Shared Fields changes. Review the resolved site, libraries, and fields before following the separate live preparation steps. Do not use live preparation to create a missing column or content type; this tool does not create them. Continue only when the report contains the intended scope with no missing-field or incomplete-coverage errors.

Prepare Shared Fields

Run live preparation only after you have reviewed the what-if report. The confirmation value is case-sensitive.

.\E2.BriefConnect.MetadataPropagation.exe prepare `
  --config .\run.json `
  --write `
  --confirm PREPARE

The tool adds existing configured fields to the Document Set Shared Fields configuration and pushes the configuration to relevant library content types. It does not create, remove, or change the type of SharePoint columns or content types.

The minimal configurations use schema-only preparation. Child repair happens through a reviewed fill-child-docs preview and Apply, not through preparation. To request a preparation parent trigger, explicitly set Run.TriggerSharedFieldsPropagation=true before starting the workflow. With this option enabled, preparation triggers parents only for scopes whose SharedFields need repair, or an explicitly forced preparation. Ordinary preparation does not re-trigger an already-prepared scope. Do not use --force as a shortcut for child repair; use a reviewed child-inclusive preview and Apply instead.

When enabled, the preparation trigger sends a same-value update to each selected Document Set parent to start SharePoint Shared Fields propagation. The tool reads the current value, protects the update from concurrent changes, and verifies the parent afterward. A conflict or failed verification is reported; do not repeat the write manually. The parent check does not confirm that child documents received the value, so run Verify when you need to confirm child values.

Require exit code 0 and confirm that the live preparation report has IsReadyForReconciliation set to true. Retain the JSON, CSV, manifest, and associated artifact-generation folder together.

Retry only failed preparation units

If a retained preparation report has failed units, replace the quoted example input path with the exact JSON report path printed by that failed run, then preview a targeted retry. Do not substitute a ready report or assume that short commands use a fixed prepare.json filename. Successful source units are checked against fresh reads and are never replayed. The retry uses the same configuration and preparation report. It rejects changed scope or configuration, does not replay successful units, and refuses --force. Use this retry only for schema-unit failures after successful preflight. If the source report's top-level Errors contains preflight errors, correct those blockers and run a new read-only prepare instead; targeted retry rejects that report.

.\E2.BriefConnect.MetadataPropagation.exe `
  --config .\run.json `
  --retry-failed-preparation `
  --preparation-report 'D:\approved-runs\failed-preparation\report.json' `
  --json-report .\runs\retry-preview\retry.json `
  --csv-log .\runs\retry-preview\retry.csv `
  --event-log .\runs\retry-preview\events.csv `
  --diagnostic-log .\runs\retry-preview\diagnostic.log `
  --checkpoint-journal .\runs\retry-preview\checkpoints.jsonl

The preview is read-only even when the config has WhatIf=false. After reviewing it, any write requires the explicit CLI pair below. Replace the quoted input path with the same failed preparation JSON path. Use new output paths and retain both the source and retry reports. Targeted retry repairs only the failed SharedFields schema units; it does not replay a global --force run, scan parents, or run parent-value triggers. A unit whose retained failure came from the parent trigger remains failed and must be handled through the approved propagation procedure rather than this schema-only retry.

.\E2.BriefConnect.MetadataPropagation.exe `
  --config .\run.json `
  --retry-failed-preparation `
  --preparation-report 'D:\approved-runs\failed-preparation\report.json' `
  --what-if false `
  --confirm PREPARE `
  --json-report .\runs\retry-live\retry.json `
  --csv-log .\runs\retry-live\retry.csv `
  --event-log .\runs\retry-live\events.csv `
  --diagnostic-log .\runs\retry-live\diagnostic.log `
  --checkpoint-journal .\runs\retry-live\checkpoints.jsonl

Review the preparation report's diagnostics for failed or incomplete units. When a write has an uncertain outcome, the tool checks current SharePoint state before deciding whether another attempt is safe. Do not repeat an uncertain write manually; resolve the reported issue and follow the retry instructions for eligible failed preparation units.

Scan for metadata drift

Use the retained preparation JSON to run a read-only database-to-parent and parent-to-child comparison. Automatic scopes include child values by default. Use fill-child-docs when you always want a child-inclusive preview; it checks children even when the configured scan option is false.

For a deliberate parent-only scan, set Run.SharedFieldAudit.IncludeChildValuesInScan=false before preparation. Explicit scopes default to parent-only unless this option is true. A parent-only scan cannot detect child-only drift or propose parent updates to repair it.

Replace the quoted example path with your exact ready preparation JSON path, then run the scan:

.\E2.BriefConnect.MetadataPropagation.exe scan `
  --config .\run.json `
  --preparation-report 'D:\approved-runs\prepare\report.json'

The scan is read-only even if WhatIf is false in the configuration.

For taxonomy fields, normal Prepare, Scan, and Apply validate the value structure but do not check whether every term is present in the SharePoint Term Store. The GUID identifies a term; a different label for the same GUID is reported as a warning and is not rewritten. Use --diagnose-taxonomy for a read-only Term Store membership check. Invalid values or field metadata remain blocking errors.

Review the scan JSON, scan CSV, and the generated .shared-fields reports. Use fill-child-docs for reviewable child-repair proposals and verify for independent child checks. Do not approve a scan that contains:

Errors, unsupported values, or stale outcomes.
Missing database records or missing Document Sets.
Parent, child, or database mismatches that you do not understand.
Truncated or incomplete coverage.
Sites, libraries, record types, fields, or record identifiers outside the approved scope.

NoChildren rows are neutral when Run.SharedFieldAudit.AllowEmptyDocumentSets=true. They do not establish that any child document received a value.

Record the scan JSON ReportHash separately after approving the report. Do not edit the report. Editing a published report invalidates its integrity checks.

Apply the approved reconciliation

Use the exact retained preparation report, approved scan report, and approved ReportHash. The confirmation value is case-sensitive. Replace both quoted example report paths and the quoted hash placeholder with the exact retained and approved values:

.\E2.BriefConnect.MetadataPropagation.exe apply `
  --config .\run.json `
  --write `
  --approval-report 'D:\approved-runs\child-preview\report.json' `
  --preparation-report 'D:\approved-runs\prepare\report.json' `
  --approval-hash '<approved-64-character-report-hash>' `
  --confirm APPLY

Before each write, the tool re-reads the database and SharePoint values. It skips stale units and units whose current values are correct and do not require child propagation. When the approved preview identifies missing child values, Apply can reapply the matching parent value to trigger SharedFields propagation. It updates only the Document Set parent and then verifies the parent and child values.

Each candidate must have an exact database identity and a matching persisted SharePoint link. Automatic scope discovery does not bypass this check or repair missing links.

Review RefreshRequired in the apply report. For each listed unit, run a new, narrowly scoped scan and obtain a new approval. Do not reuse the previous approval hash or use --force to bypass a stale result.

If values change after you approve a scan, Apply blocks the stale units and lists them in RefreshRequired. Run a new, narrowly scoped Scan, review the updated report, and approve its new hash before trying again. Do not reuse the old approval hash or use --force to bypass stale values. If a write's outcome is uncertain, rely on the report's read-back result; do not repeat the write manually.

SharePoint propagation can be delayed. If all approved parent writes succeeded and only child values remain missing or different, wait and run read-only Verify with a new output folder. Do not repeat Apply only to retry child checks. Keep the original failed Apply report; a later successful verification does not change that run's result.

Verify Shared Fields

Run an independent read-only verification after apply or whenever you need to confirm parent-to-child propagation. Replace the quoted example path with your retained ready preparation JSON path:

.\E2.BriefConnect.MetadataPropagation.exe verify `
  --config .\run.json `
  --preparation-report 'D:\approved-runs\prepare\report.json'

Require exit code 0, IsComplete=true, an empty Errors list, and Summary.FailureCount=0. CoverageIncomplete, InventoryCoverageIncomplete, and Truncated must be false. Mismatches, missing child values, failed reads, and incomplete or truncated inventories still fail.

Both automatic and explicit scopes allow empty Document Sets by default (AllowEmptyDocumentSets=true). Their NoChildren rows remain visible as warnings and count as skipped, not as propagation matches or failures. Set AllowEmptyDocumentSets=false on the scope or Run.SharedFieldAudit only when empty Document Sets must fail Scan and Verify. Change it only before starting preparation with new reports.

Check Summary.ChildDocumentCount against the expected coverage. If all selected Document Sets are empty, there are no child values to verify; do not report that as successful propagation. If documents were expected but not found, investigate the scope.

If only child values are missing or different after successful parent writes, wait and repeat this read-only command. Use a new --output-dir, or let the tool create a new run folder. For other failures, retain all evidence and resolve the reported error before continuing.

Verify compares the parent with its children; it does not compare against the database. Run a separate Scan when database-to-parent agreement is also required. With an exact Run.TargetDocumentSet, Scan's audit and Verify resolve that parent directly and inventory only its bounded subtree, including ordinary subfolders but excluding nested Document Sets. Unrelated library items do not consume the target's inventory allowance. Bulk runs retain library-wide inventory; missing identities, denied reads and configured limits still fail or mark coverage incomplete. Verification JSON explicitly records ChildAuditEnabled; mismatch and failure counts are in Summary. Require actual coverage evidence rather than assuming an omitted flag means children were checked.

Resume an interrupted run

Preserve all reports, manifests, logs, and artifact-generation folders from the interrupted attempt. Resume from a supported CSV report or event log by adding --resume-log to the original phase command. Replace the quoted example paths with the ready preparation JSON path and the exact retained CSV report or event-log path from that interrupted run:

.\E2.BriefConnect.MetadataPropagation.exe scan `
  --config .\run.json `
  --preparation-report 'D:\approved-runs\prepare\report.json' `
  --resume-log 'D:\approved-runs\interrupted-scan\report.csv'

The tool validates resume evidence against the phase, configuration, unit, and relevant report hash. It confirms current state before skipping completed work. Use --force only when you intentionally need to reprocess completed units; it does not make stale or unsupported values safe.

Command-line reference

Use one short command or one mode flag per run; do not combine mode selectors. Use short commands for the normal workflow. With no mode selector, the tool selects preparation. Run .\E2.BriefConnect.MetadataPropagation.exe --help (or -h) to display usage.

Command or mode flag	Purpose and key requirements
`check-vm`	Read-only environment readiness without record-type or field selection. `SiteUrl` or `Sites` enables Graph site checks; omitted checks are partial. It does not prove write or field-specific permissions.
`check-fields`	Read-only selected-field configuration and SharePoint schema diagnosis, including all matching library content-type copies. Requires environment, sites, and record types/fields; produces diagnostic evidence, not preparation approval.
`fill-child-docs`	Read-only child-inclusive Scan preview; requires a ready `--preparation-report` and approved audit scope. Does not prepare, approve or apply changes; rejects write/force/resume options.
`prepare` / `--prepare-shared-columns`	Preview SharedFields preparation by default. For the short command, apply with `--write --confirm PREPARE`. For the legacy flag, set `WhatIf=false` or use `--what-if false`, then confirm with `--confirm PREPARE`.
`scan` / `--scan-drift`	Read-only drift scan; requires `--preparation-report`. Short `scan` uses point reads without a partition and includes children by default in automatic scopes. Flag-based bulk `--scan-drift` requires exact partitions for either provider.
`verify` / `--verify-shared-fields`	Read-only parent-to-child verification in the selected scopes, or one exact target; requires `--preparation-report`. Treats empty Document Sets (`NoChildren`) as neutral warnings by default unless `AllowEmptyDocumentSets=false` is configured.
`apply` / `--apply-reconciliation`	Apply an approved report. The short command requires `--write`; the legacy flag requires `WhatIf=false` or `--what-if false`. Both require `--approval-report`, `--preparation-report`, `--approval-hash`, and `--confirm APPLY`.
`partition-key`	Read-only, standalone point lookup for one `TargetDocumentSet`; always prints JSON. Use only `--config`, optional `--output-format json`, and optional `--json-report`.
`--retry-failed-preparation`	Retry only eligible failed preparation units from the exact `--preparation-report`. Preview is read-only; write requires `--what-if false --confirm PREPARE`.
`--verify-shared-field-membership`	Fast read-only check of selected SharedFields on site and library content types.
`--diagnose-taxonomy`	Read-only Term Store diagnostic; requires bulk `SharedFieldAudit` scopes, not `TargetDocumentSet`, with database comparison and exact partition keys.

Option	Purpose and constraints
`--config <path>`	Required JSON configuration path, except when showing help.
`--help`, `-h`	Display command-line usage without running a workflow.
`--write`	Explicit write intent for the short `prepare` or `apply` commands. Legacy flag-based writes use `WhatIf=false` or `--what-if false`; `scan` and `verify` remain read-only.
`--confirm PREPARE` / `--confirm APPLY`	Case-sensitive confirmation required for the matching write.
`--what-if <true\\|false>`	Override `WhatIf` for legacy flag-based workflows (including default preparation) or targeted preparation retry. Short commands, including `partition-key`, reject this option; use `--write` for supported phase writes.
`--output-dir <new-folder>`	Choose a new evidence folder for a short phase command.
`--job-id <id>`	Override the stable run identity.
`--force`	Reprocess units previously marked successful where supported; it does not bypass stale-value validation and is not allowed for targeted preparation retry.
`--resume-log <path>`	Override the prior CSV log path for a supported resume workflow.
`--checkpoint-journal <path>`, `--event-log <path>`, `--csv-log <path>`, `--diagnostic-log <path>`, `--json-report <path>`	Override individual output paths. Keep every output inside the validated run folder.
`--preparation-report <path>`	Preparation manifest for scan/verification/apply, or the exact retained report for retry.
`--approval-report <path>`, `--approval-hash <64-character SHA-256>`	Exact reviewed scan report and its approved hash for apply.
`--output-format auto\\|table\\|json`	Final console summary format. `auto` uses a table interactively and JSON when redirected; `partition-key` always prints JSON, so omit this option or set it to `json`.
`--include-taxonomy-values`	With `--diagnose-taxonomy`, include up to 20 distinct non-exact value examples per field and scope; the reports may contain customer data.
`--skip-unresolved-taxonomy-values`	Deprecated and rejected. Use `--diagnose-taxonomy` for an explicit Term Store membership check.

Interpret exit codes

Exit code	Meaning
`0`	The workflow completed successfully, help was displayed, or `check-vm` had no failed checks. For readiness also inspect `ConnectivityComplete`; omitted site checks produce `PARTIAL`. For `check-fields`, only the selected schema is confirmed; this is not preparation approval.
`1`	The workflow completed with failures, mismatches, stale or unsupported units, missing records, or incomplete coverage. For `check-fields`, field-configuration issues, schema gaps, or incomplete/read-failed checks need attention.
`2`	Command, configuration, package, path, capacity, capability, or startup preflight validation failed.
`130`	The operator cancelled the run with Ctrl+C.

Handle a failed run

If preparation fails, use the field-specific reasons and check-fields to investigate the selected configuration and schema. Correct the reported problem and repeat the what-if preparation before making another live attempt. Keep the diagnostic report and failed startup artifact, but do not use either as preparation approval.

If scan or verification is interrupted, retain the partial generation and resume it. Never approve an incomplete report.

If Apply finished all approved parent writes but failed only on child-value checks, wait for SharePoint propagation and run read-only Verify in a new output folder. Retain the failed Apply report. Do not repeat writes only to get a successful child check.

If apply is interrupted, assume that some Document Set parent values may already have changed. Retain all output, resume with the same approved report and hash, and run independent verification. The tool re-reads current values and treats already-correct units as no-write recovery outcomes.

If a report is truncated, divide the work into smaller, non-overlapping scopes and rerun it. Configuration properties that claim to allow truncation do not make truncated evidence complete.