Taxonomy Operations

Taxonomy Operations

Taxonomy Operations is a modular toolkit for auditing and maintaining taxonomy quality in Drupal 10, 11 and 12.

The core module provides integrated taxonomy overviews, similar-term review and contextual cleanup, with a hard dependency only on Taxonomy. Governance is enabled automatically when the main module is installed. Optional submodules add portable import/export and usage trends. Node and Paragraphs are soft dependencies detected at runtime.

Modular architecture

• taxonomy_operations (core) — Similar-term detection, contextual unused-term cleanup, vocabulary/term overviews and Drush automation.
• taxonomy_operations_governance (enabled automatically) — Action plans with review, approval, simulation, locks, audit, rollback and operation history.
• taxonomy_operations_transfer — Portable import/export of terms (including field data).
• taxonomy_operations_trends — Cron usage snapshots and per-term trend charts.

Action Plans is the main administration entry point. Governance provides reviewable workflows for merges, imports and cleanups. Transfer and Trends remain optional.

The standalone Taxonomy Insights, Unused Terms and Top Terms reports have been removed. Unused-term review and cleanup remain available inside the vocabulary and term overviews.

Core features

Contextual unused-term review and cleanup

• Select unused terms in the overview, review the exact selection and confirm creation of a cleanup action plan.
• With a term selected, only its descendants are considered. Without a selected term, candidates cover the vocabulary; hierarchy searches further restrict the scope.
• Current and historical references, hierarchy relationships and permissions are rechecked to protect terms from unsafe deletion.

Similar terms and merge

• Groups near-duplicate labels by normalized similarity.
• Suggests a canonical term from usage counts.
• Similarity groups appear inside the overview with a configurable threshold. A selected term limits comparisons to its descendants; without a selection, the whole vocabulary is considered.
• Impact preview for node/paragraph references (when those modules exist).
• Optional per-bundle exclusions.
• Creates a merge action plan (requires the governance submodule).

Vocabulary and term overviews

• Searchable hierarchy with exact-name match preference and branch context.
• Inline editing of names, formatted descriptions, translations, parents and weights, with stale-edit and hierarchy-cycle checks.
• Single-term overview page using the same interface.
• Current references, contextual cleanup, similar-term groups and optional branch export/import from the same surface.
• Filtered taxonomy overview form on vocabulary admin screens.

Governance submodule (enabled automatically)

• Action plan list with filters, pagination and CSV export.
• Lifecycle: pending → approved → running → completed / failed / cancelled (with retry).
• Single or double approval; production can enforce stricter rules.
• Real dry-run simulation with per-entity before/after diffs (no writes).
• Integrity check before execute (target terms, replacements, referenced fields); aborts on drift.
• Concurrency locks so two plans cannot touch the same tids/fields at once.
• Per-item audit trail and estimated vs executed impact comparison.
• Assisted rollback builds an inverse plan from audit rows (e.g. merge without delete).
• Filterable operation history with timing metrics and CSV export.
• Operation history has its own administration tab alongside Action Plans and Settings. Its responsive filter grid keeps submitted values, including the date range.
• Cron alerts for consecutive plan failures and rising unused-term ratios.
• Long runs use Drupal Batch API with configurable chunk size and max operations per plan.

Transfer submodule

• Portable vocabulary, selected-term and branch exports in YAML or the versioned CSV transfer format, with selectable fields, translations, descendants and dependencies.
• Global or vocabulary-specific import: analyze an uploaded or pasted export, preview differences, select terms, then create an import action plan for simulation, approval and execution.
• Stable import keys on terms for cross-site identity.

Trends submodule

• Cron-driven usage snapshots at configurable intervals.
• Per-term trend chart and tabular history.

Permissions

Core: view reports (for enabled report extensions), merge terms, cleanup terms and administer settings. Taxonomy administration and entity-level access checks also apply.

Governance: view / create / approve / execute / simulate / rollback action plans; view operation history.

Transfer: export terms; import terms.

Controls are shown only when the user has the required access. Governed imports and cleanups also require permission to create and view action plans. Permissions must be assigned explicitly to the appropriate roles.

Drush commands

• drush taxonomy-operations:cleanup-unused — options: --vid, --dry-run
• drush taxonomy-operations:similar-groups <vid> — options: --threshold, --min-size
• drush taxonomy-operations:similar-merge <vid> — interactive; options: --threshold, --dry-run, --remove-merged

Main admin paths

• /admin/reports/taxonomy/action-plans — Action plans (governance)
• /admin/reports/taxonomy/action-plans/{plan} — Review / simulate / audit
• /admin/reports/taxonomy/history — Operation history (governance)
• /admin/reports/taxonomy/trend/{tid} — Term trend (trends)
• /admin/config/system/taxonomy-operations-settings — Settings
• /admin/structure/taxonomy/manage/{vocabulary}/overview — Integrated vocabulary overview
• /taxonomy/term/{term}/term-overview — Term overview
• Vocabulary tabs: Overview, List, and Export / Import when Transfer is enabled. Similar-term groups are part of Overview.

Requirements

• Drupal 10, 11 or 12
• Taxonomy (core)
• Optional: Node, Paragraphs
• Governance is enabled automatically; Transfer and Trends are optional.

Operational notes

• After updates: drush updb -y and drush cr.
• Update 9010 enables Governance for existing installations. New installations enable it automatically, except during configuration imports, which respect the exported module list. Include Governance in exported configuration.
• Prefer dry-run before large cleanups or merges.
• Use approve vs execute permissions for separation of duties.
• No generic action-plan plugin API yet — plan types stay first-party until there is a real extension need.