Explicitly assign a category tree after an update

This operations guide is for administrators of an existing installation. After the update, assign the previous categories to a shop tree and bind the sales channel and sites. Existing category IDs, hierarchy, approvals, product placements, and routes are retained. Allow for a brief interruption of category delivery: Workspace does not substitute the old category view when the new bindings are absent. Administration and assignment remain available.

Prepare the update

Back up the database, configuration, and site sources using your update procedure. This schema version does not support returning to the old server binary on the same database. Keep the new version available for forward recovery; a complete return uses a verified pre-update backup and its restore procedure.

Check the active tenant and effective permissions with nucli whoami --scopes. You need category read, tree create, channel and site maintenance, and explicit first-assignment permissions. Repeat the workflow for each affected tenant.

Check categories:inventory, categories:adoption_plan, and categories:adoption_verify. Apply needs categories:update and categories:adoption_apply at ADMIN level. Tree management uses the corresponding category_trees CRUD scopes; channel and site changes need saleschannels:update and site:update. The current StaffAdmin preset includes the new permissions, but existing roles do not automatically gain them. Have an authorized IAM administrator explicitly grant missing scopes on the appropriate role and recheck the session afterward. nucli --tenant <tenant> resources list --json lists discoverable resources. Use ordinary IAM administration; missing permissions must not be bypassed through a different privileged access path.

Read inventory and prepare bindings

bash
nucli --tenant <tenant> pim categories inventory --json

Inventory includes categories, trees, channel allowances, and site selections. Review the previous roots and associated publications. Create a shop tree, for example “Previous shop”, with a stable key and purpose=shop. Explicitly allow it through categoryTreeIds on the existing channel. Sites without a tree binding remain unbound until after assignment; category delivery remains closed during this interval. Existing non-null site bindings must match the target tree and existing routes. After apply, select the tree through navigationCategoryTreeId on affected sites and an optional entry category.

Assign complete forests. A selected root includes its live descendants; individual children are not separated from their existing hierarchy. The operation does not restructure the tree. Use a separate shop tree with separate nodes for a later B2B shop requiring a different hierarchy.

Plan and apply the assignment

Write the target tree and selected root IDs from inventory to zuordnung.json:

json
{
  "treeId": "<shop-tree-uuid>",
  "rootCategoryIds": ["<root-category-uuid>"]
}
bash
nucli --tenant <tenant> pim categories adoption plan --input zuordnung.json --output plan.json

Planning does not change categories. Review the target tree, roots, and every listed node. The server binds the plan to the tenant and current revisions. Do not edit the generated plan. Avoid editing affected categories and bindings between plan and apply.

Explicitly apply the reviewed plan:

bash
nucli --tenant <tenant> pim categories adoption apply --plan plan.json --apply
nucli --tenant <tenant> pim categories adoption verify --plan plan.json --json

Assignment is atomic. A stale plan or a different tree binding produces a conflict; read inventory again and generate a new plan. An identical repeat of the same valid plan does not overwrite a different assignment. verified=true confirms assignment, but not landing page readiness.

Verify public delivery

For every site and locale, check in order:

  1. The channel allows the shop tree. The site selects it and, if required, an entry category within that tree.
  2. The category and required ancestors have approved publications.
  3. The category has an active registered site route and a canonical URL for the locale. No static page occupies the same path.
  4. The source includes the matching categoryLanding shell and required variant snippets. Validate and build source changes; publish explicitly.
  5. Public navigation and category URLs work in German and English or all locales actually in use. Test a populated and an empty category.

Resume normal traffic after these checks succeed. Assignment does not create missing shells or snippets. Inspect the registered path rather than deriving a slug from its final segment. Category IDs remain unambiguous when branches use the same slug.

Next steps