Enable and Build a Hierarchy in the Console

Enable the hierarchy

Every Environment starts on flat access control. Switching it to the hierarchy model happens on Access Control → Overview, where the two models are presented as cards. The switch is per Environment: enabling it on Development leaves Production flat.

Application: Developer Console
Path: Access ControlOverview
Opens with: applications.view Read the Account's Applications and Environments, and open an Environment's Overview.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment.

Enable the hierarchy

Open Access Control → Overview for the Environment in the switcher. Two cards show: Flat Access Control, currently active, and Hierarchical Access Control, whose button reads Enable Hierarchy.

Click Enable Hierarchy. The Enable Hierarchical Access Control wizard opens on an explainer step, What is Hierarchical Access Control?. Click Next.

On Define Your Levels, add the tiers of your organization from the top down, for example Region, District, Store. Next stays disabled while there are no levels, an empty row, or two levels with the same name.

On Review Your Structure, check the table: the root row (Organization, tagged Root · auto), then your levels tagged Level 1, Level 2, Level 3. Click Enable Hierarchy.

The wizard switches to Hierarchy Enabled with a single action. Click Build Your Hierarchy to go straight to the Environment's Hierarchy page, where the Access Tree holds a single root node named after the Application.

Back on Overview, the Hierarchical Access Control card is now the active one and its button reads Manage Hierarchy; the flat card's button reads Enable Flat.

Build the tree

Access Control → Hierarchy is the tree editor. Select a node in the Access Tree on the left to see it on the right; creating, moving, editing, and deleting all start from the selected node. Each level may contain any level below it, so the Node Type offered when you create a node is always a tier beneath its parent.

Application: Developer Console
Path: Access ControlHierarchy
Opens with: env_structure.view Read the Environment's hierarchy tree and its levels.
Context: Select an Application and an Environment in the switcher first; the page belongs to that Environment. The entry shows only while the Environment runs the hierarchy model.

Build the tree

Select the root node in the Access Tree. The panel header shows a + button (Create Node); it appears only while you may manage the selected node.

Click Create Node. The Add Node dialog opens. Under the root, Node Type offers every level; pick the top one, such as Region, enter a Name, and click Create Node. A Node created successfully toast appears and the new node is selected under the root.

Select the new node and click Create Node again. Node Type now offers only the levels below it; the deepest level offers no child types at all.

To move a node, drag it in the tree and drop it onto its new parent. A Node moved successfully toast appears. A move the schema does not allow fails with a Failed to move node. Please try again. toast and the tree reloads. If someone else moved the same node first, a Conflict detected dialog offers Keep my edits, which retries the move against the fresh version, or Discard my changes; either way the tree refreshes.

To rename a node, select it, open its Details tab, and click Edit. The Edit Node dialog opens with the current name; change it and click Save Changes. A Node updated successfully toast appears and both the panel headline and the tree label update.

To delete a node, select it and use Delete node in the Delete this node group of its Details tab. The Delete node dialog warns that the node and everything beneath it go, child nodes and the role assignments made there, and that it can't be undone. Type the node's name to enable Delete and click it; a Node deleted toast appears.

Read how inheritance and node types work →

Change the levels later

The levels you defined in the wizard can be added to, renamed, and reordered afterwards. This happens from the Environment's card on the Applications page rather than on the Hierarchy page.

Application: Developer Console
Path: TenantApplications
Opens with: applications.view Read the Account's Applications and Environments, and open an Environment's Overview.
Context: Account-wide. No Application or Environment selection applies.

Change the levels later

Open Tenant → Applications and find the Environment's card under its Application.

Open the card's ⋮ menu and click Manage Levels. The item is present only for an Environment on the hierarchy model.

In the Manage levels dialog, add a tier, rename one, or drag to reorder, then click Save Changes. A Levels updated in "Development". toast confirms it.

A tier that already has nodes of its type is locked in the dialog: its name can't be edited and its remove button is disabled, though it can still be reordered. Delete those nodes first if the tier has to go.

Revert to flat

An Environment can go back to flat access control at any time. Everything below the root is deleted and every active role assignment is consolidated to the Environment level, so the confirmation asks you to type the Environment's slug.

Revert to flat

Open Access Control → Overview. The Flat Access Control card's button reads Enable Flat; click it.

The Disable hierarchy dialog explains that every node below the root is deleted and that active assignments consolidate to the Environment level. Type the Environment's slug, for example development, to enable the Disable hierarchy button, then click it.

A Hierarchy has been disabled. All assignments are now environment-wide. toast appears. The revert is refused with a Failed to disable hierarchy toast while an Admin Workspace administrator is scoped to a node in the Environment; re-scope those administrators first. Otherwise the flat card is active again, and the Hierarchy page shows Hierarchy not enabled with a Configure Hierarchy action that opens the wizard.

If you don't see this

Each control on these pages exists only for someone who may use it. When something described above is missing, one of these is why:

Hierarchy is not in the left nav. The entry shows only while the Environment in the switcher runs the hierarchy model; on a flat Environment, enable it from Overview first. It also needs your administrator role to carry env_structure.view.

Overview shows the cards but no Enable Hierarchy or Enable Flat button. Switching the model needs applications.manage; with applications.view alone you can read the Overview but not change it.

The tree opens but there is no Create Node, Edit, or Delete node. You hold env_structure.view but not env_structure.manage, or the selected node is outside the part of the tree you may manage.

Create Node offers no Node Type. The selected node is on the deepest level; nothing can be created beneath it. Select its parent instead.

The Environment card has no Manage Levels item. That Environment is on flat access control. Levels exist only on the hierarchy model.

Your nodes are missing. Each Environment owns its own tree. Check the Environment in the switcher: nodes created in Development do not exist in Production until you promote them.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.