Skip to content

Manage term store changes

Use this procedure to add, rename, deprecate, or remove managed metadata terms. This procedure keeps the Brief Connect environments aligned.

For an explanation of the configuration, term store, and record connections, see Understanding managed metadata in Brief Connect.

Use Office Resources as the source of truth

Make term changes in the version-controlled Office Resources repository. Deploy these changes through its pipeline.

A direct SharePoint change makes the environment different from the source. A later deployment can overwrite or conflict with the direct change.

Before you begin

Make sure that the people involved have the required access:

  • A business administrator can define the required change and assess its business impact.
  • A deployment administrator can update the Office Resources repository, obtain approval, and run its build and release pipelines.
  • An authorised Brief Connect administrator can clear the application cache for an immediate review.

Record the following information for the change:

  • The term set and full term path.
  • The current and intended labels.
  • The environments that contain the term.
  • Whether the term is already used on records.
  • Whether existing record labels must also change.

Review these dependencies before implementation:

  • Managed metadata fields whose Data Source Name points to the term set.
  • Default values or field conditions that use the term label.
  • Permission rules, workflows, plugins, templates, and integrations.
  • Dashboard filters, search, reports, and exports.

If you cannot identify all dependencies, contact Engage Squared before you make the change.

Request and assess the change

Business administrator

  1. Provide the deployment administrator with the term set, full term path, current label, intended label, and reason for the change.
  2. Identify any records, configuration, reporting, or integrations that use the term.
  3. Confirm whether the change applies to all environments.
  4. Obtain the required business approval.
  5. If existing portal records must show a new label, raise a request with Engage Squared Support to assess the available metadata update options.

Deployment administrator

  1. Confirm that the Office Resources source matches the deployed environments before editing it.
  2. Review the impact information supplied by the business administrator.
  3. Select the supported change type below.
  4. Include dependent configuration changes in the same pull request or coordinated release.

Implement the change in Office Resources

Use the customer-specific Office Resources repository and follow its existing branch, review, and release controls.

Add a term

  1. Add the term to Scripts/SchemaSiteCollectionTerms.xml under the correct term set and parent term.
  2. Preserve the existing hierarchy and sort-order conventions.
  3. Include any field defaults or other configuration that uses the new term.

Rename a term

  1. Add a RenameTerm invocation to Scripts/TermsRenaming.ps1.
  2. Use the current term-set and term path as the first argument and the intended label as the second argument.
  3. Update any schema declarations and dependent configuration that still use the old label.

The following example renames a top-level term using a generic term set and label:

RenameTerm "Example Term Set|Old term label" "New term label";

For a nested term, include each parent in the pipe-delimited path.

Deprecate a term

  1. Add a DeprecateTerm invocation to Scripts/TermsDeprecating.ps1.
  2. Use the complete pipe-delimited path to the existing term.
  3. Confirm that defaults and required fields do not depend on the term remaining selectable.

The following example deprecates a top-level term:

DeprecateTerm "Example Term Set|Term to retire";

Delete a term

Prefer deprecation

Delete a term only when Engage Squared has confirmed that no records or dependencies use it. Deletion can break historical references.

  1. Add a DeleteTerm invocation to Scripts/TermsDeleting.ps1.
  2. Remove declarations or dependencies that would recreate or continue to reference the term.
  3. Include evidence that the term is unused in the change review.

The following example deletes a top-level term after its use has been assessed:

DeleteTerm "Example Term Set|Unused term";

Rename a term set

Do not treat a term-set rename as a normal term rename. The term-set name is referenced by Data Source Name in managed metadata field configuration.

Coordinate the Office Resources change, field configuration change, and Content Types sync with Engage Squared.

Review and deploy the change

  1. Review the Office Resources change and its dependency assessment through the normal pull-request process.
  2. Build the Office Resources artifact from the approved source.
  3. Deploy the artifact to the first non-production environment.
  4. Complete the validation checks below.
  5. Promote the same approved artifact through the remaining environments in order.
  6. Record the deployment outcome and any follow-up work for existing records.

For pipeline setup and operation details, see Deploy Office Resources.

Validate the change

  1. Confirm that the Office Resources release completed successfully for the target environment.
  2. Confirm that the expected term and hierarchy appear in the environment's SharePoint term store.
  3. Allow the Brief Connect term cache to refresh, then reload the application. If required, an authorised administrator can clear the cache.
  4. Confirm that the expected choices appear when creating a record and editing an existing record.
  5. Confirm that defaults, permission conditions, workflows, filters, reports, and integrations still behave as intended.
  6. Repeat these checks in every environment before promotion.

Existing record labels

Renaming a term changes the available label after the term cache refreshes. It does not rewrite the label stored on existing Brief Connect records. SharePoint can show the new label while the portal still shows the old label. Contact Engage Squared Support if existing record metadata must be updated.

Handle an approved direct SharePoint change

Use a direct SharePoint term-store edit only when the normal pipeline process cannot meet an approved operational need.

  1. Obtain approval for the exception and record the exact change.
  2. Apply the change to the authorised environment.
  3. Update the Office Resources repository immediately so that source control describes the intended state.
  4. Review and deploy the reconciled Office Resources change to align the other environments.
  5. Do not run a release from stale Office Resources source while the direct change remains unreconciled.
  6. Validate the choices and existing-record behaviour as described above.