Skip to content

Quick start: fill document metadata

This is a short version of the full metadata propagation guide. It covers the normal prepare, preview, apply, and verify workflow.

Select a site, record types, and fields. The tool finds the matching libraries and records, then updates Document Set parents. SharePoint copies the SharedFields values to child documents.

Draft documentation

Check this guide against your approved tool package and operating procedure before a production run.

Before you start

Ask your administrator for the tool, working service access, and the connection settings for your target environment.

Run each command from the folder containing the tool and run.json. You can use a new PowerShell window for each step. No command needs variables from an earlier step.

The examples save reports under .\runs\job-01. Use a protected location and a new job name for another job. Do not overwrite previous reports.

Set up one job file

Copy one complete example into run.json. Choose the database type supplied by your administrator. Replace the example values before you run a command.

Modern

Use this example for a MongoDB-compatible database:

{
  "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect",
  "Environment": {
    "DbType": "Modern",
    "KeyVaultUri": "https://brief-connect-example.vault.azure.net/",
    "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 example for Legacy connection-string access:

{
  "SiteUrl": "https://contoso.sharepoint.com/sites/brief-connect",
  "Environment": {
    "DbType": "Legacy",
    "KeyVaultUri": "https://brief-connect-example.vault.azure.net/",
    "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" }]
    }
  ]
}

Fill in your values

  • SiteUrl: your SharePoint site URL. Set it once, at the top level.
  • Environment.KeyVaultUri: the Key Vault URL for the same environment.
  • Environment.ClientId: the Brief Connect Server App's application (client) ID.
  • Environment.TenantId: the Microsoft Entra directory (tenant) ID.
  • Properties ending in SecretName: the existing Key Vault secret names, not passwords, connection strings, or certificate values.
  • RecordTypes[].Name and Fields[].InternalName: the exact Brief Connect record-type names and field internal names, not display labels.

Add or remove record types and fields as needed. The job covers all matching libraries in the selected site. You do not need to add partition keys or library lists.

Run one step at a time and check $LASTEXITCODE after each tool command. Keep run.json unchanged between steps.

1. Check access

Check access without changing data:

.\E2.BriefConnect.MetadataPropagation.exe check-vm `
  --config .\run.json `
  --output-dir '.\runs\job-01\connections'

Continue only with ConnectivityComplete=true, no failed checks, and exit code 0. Otherwise, stop and contact your administrator.

2. Prepare SharedFields

Preview the SharedFields changes:

.\E2.BriefConnect.MetadataPropagation.exe prepare `
  --config .\run.json `
  --output-dir '.\runs\job-01\prepare-preview'

Open .\runs\job-01\prepare-preview\report.json. If IsReadyForReconciliation=true, there are no failures, and the exit code is 0, go to step 3.

Otherwise, stop on errors. If only SharedFields changes are needed, review all listed fields and libraries. After approval, apply them:

.\E2.BriefConnect.MetadataPropagation.exe prepare `
  --config .\run.json `
  --write `
  --confirm PREPARE `
  --output-dir '.\runs\job-01\prepare-write'

This changes the site content types and their library copies, not parent values. Continue only with a ready report, no failures, and exit code 0.

Use the ready preparation report in the remaining commands. The examples use prepare-preview\report.json. If you ran the write command, use prepare-write\report.json in each --preparation-report argument instead.

3. Preview document corrections

Check database, parent, and child values without changing them:

.\E2.BriefConnect.MetadataPropagation.exe fill-child-docs `
  --config .\run.json `
  --preparation-report '.\runs\job-01\prepare-preview\report.json' `
  --output-dir '.\runs\job-01\child-preview'

Review .\runs\job-01\child-preview\report.json, including all proposed changes in DatabaseRows and any clearing of values. Require PreflightPassed=true, an empty Errors list, and SharedFieldAudit.IsIncomplete=false.

Exit code 1 can mean differences were found. Stop for read errors, missing or unlinked records, unsupported values, or incomplete coverage.

Empty Document Sets produce neutral NoChildren rows. A correct parent can still need an update to fill child fields.

If no corrections or failures remain, skip Apply and go to step 5. Otherwise, approve the exact report before step 4.

Apply processes all applicable corrections in that report. If the scope is wrong, change the job and start again from preparation.

4. Apply the approved corrections

After approval, read the hash from the reviewed preview report:

Get-Content -LiteralPath '.\runs\job-01\child-preview\report.json' -Raw |
  ConvertFrom-Json |
  Select-Object -ExpandProperty ReportHash

Replace <approved-report-hash> below with the printed value, then apply that exact report:

.\E2.BriefConnect.MetadataPropagation.exe apply `
  --config .\run.json `
  --write `
  --approval-report '.\runs\job-01\child-preview\report.json' `
  --preparation-report '.\runs\job-01\prepare-preview\report.json' `
  --approval-hash '<approved-report-hash>' `
  --confirm APPLY `
  --output-dir '.\runs\job-01\apply'

Do not edit the approved report. Continue to step 5 if Apply returns exit code 0 with no failures.

If all parent writes succeeded but child values still differ, wait for SharePoint, then run step 5. Stop for other failures. Do not repeat Apply without a fresh approved preview.

5. Verify the document values

Check parent and child values without changing data:

.\E2.BriefConnect.MetadataPropagation.exe verify `
  --config .\run.json `
  --preparation-report '.\runs\job-01\prepare-preview\report.json' `
  --output-dir '.\runs\job-01\verify'

Open .\runs\job-01\verify\report.json. Require exit code 0, IsComplete=true, an empty Errors list, and Summary.FailureCount=0.

Check that the expected child documents were found. NoChildren is not proof of propagation.

If SharePoint needs more time, wait and repeat this read-only step. Change --output-dir to a new folder, such as .\runs\job-01\verify-02. Keep all report folders, including any failed Apply result.

For setup, other commands, or troubleshooting, use the full metadata propagation guide.