Tools (Beta)

Tools (Beta) defines the admin's left navigation menu: the sections in it, the tools inside each section, and the order of both. You can also create custom content tools here.

Adding Tools (Beta) to the Admin Menu#

---

Tools (Beta) isn't in any menu by default, and there is no feature flag to enable. To make it available, add the Tools (Beta) tool to a section, then grant that section to the roles that should use it. Until Tools (Beta) is available, use the Tools tab of Settings › Roles & Tools to do this (see Custom Tool Groups).

Once added, it appears in the menu as Tools (Beta) and opens at /dotAdmin/#/tools-beta.

To remove Tools (Beta), take it out of the section again. Adding or removing it doesn't change the existing navigation.

Who Can Use It#

A user without the CMS Administrator role who tries to change a section sees an Access denied message, and nothing is changed.

How the Screen Is Organized#

---

The screen has two panels:

• Sections (left) lists every section in the order it appears in the navigation, with the tools in each section listed underneath it. Getting Started is selected when the screen opens.
• The right panel shows the selected section's name and the catalog of every available tool. A checked tool is in the selected section.

Hover over the ⓘ icon next to the section name for a reminder that this is the master list: tools appear in someone's menu only after their section is granted to a role.

Every change you make is saved immediately. There is no separate Save button.

Managing Sections#

---

Sections are the groups in the left navigation, such as Content, Sites or Settings.

Creating a Section#

1. Click New Section.
2. Enter a Name. Section names must be unique.
3. Choose an Icon. Type in the list to search the available icons.
4. Click Create.

The new section is added at the end of the list, with no tools. Add tools to it as described in Adding Tools to a Section.

Renaming a Section or Changing Its Icon#

1. Hover over the section and click its ⋮ menu, or click the ⋮ menu at the top of the right panel when the section is selected.
2. Choose Edit.
3. Change the Name or Icon, and click Save.

Reordering Sections#

Drag a section by its handle (⋮⋮) to a new position in the Sections panel. The navigation menu follows the same order.

When users log in, dotCMS opens the first tool in the first section they can access. Reordering sections can therefore change which screen users see first.

Deleting a Section#

1. Open the section's ⋮ menu and choose Delete.
2. Read the confirmation, which tells you how many tool assignments will be removed, and click Delete.

Deleting a section removes it from the navigation, along with its list of tools and every grant of it to a role or user. Users who could reach a tool only through that section lose access to it. Deleting a section can't be undone.

The Getting Started section can be renamed and edited, but it can't be deleted or left with no tools.

If you choose Delete for Getting Started, dotCMS shows a Bad request error and nothing is deleted.

Managing the Tools in a Section#

---

Select a section in the Sections panel to manage its tools.

Adding Tools to a Section#

In the right panel, check the tools you want to add. Each one is added to the end of the section and appears under it on the left.

To find a tool quickly, type part of its name in Search tools. The catalog shows 40 tools at a time; click Load N more at the bottom to see the rest.

Removing Tools from a Section#

Uncheck the tool in the right panel, or hover over it in the Sections panel and click ×. Removing a tool from a section doesn't delete the tool.

Reordering Tools#

Drag a tool by its handle (⋮⋮) to a new position within its section in the Sections panel.

Custom Tools#

---

A custom tool is a filtered content list: a tool that shows content of the base types or content types you choose. Once created, it appears in the tool catalog and can be added to any section like any other tool.

Creating a Custom Tool#

1. Click New Tool.

2. Enter a Name. This is the tool's label in the menu.

3. Leave the Id as generated from the name, unless an integration depends on a specific id. The id can't be changed later.

4. Choose what the tool lists:

   • Base types: whole categories of content, such as Content. New tools start with Content selected.
   • Content types: specific content types.
   • Leave both empty to list all content.

   Base types take precedence. If you choose content types, clear Base types too; otherwise the tool lists everything of the selected base type. For example, a tool with base type Content and content type Blog lists all Content items, not just blogs.

5. Choose a Data view mode: List shows a table; Card shows content as cards with thumbnails. Either way, the tool opens the Content Search screen, where users can switch between the two views.

6. Click Create.

The new tool isn't in any section yet. Check it in a section to add it to the navigation.

Editing or Deleting a Custom Tool#

Custom tools have a ⋮ menu in the catalog with Edit and Delete. Tools that come with dotCMS don't have this menu and can't be edited or deleted.

• Edit lets you change the name, base types, content types and data view mode.
• Delete removes the tool from the catalog and from every section that contains it. The confirmation tells you how many sections it's in. Deleting a tool can't be undone.

How Changes Reach Users#

---

• Changes appear in the navigation of users who are already logged in, without them reloading the page.
• A section appears in a user's menu only if it's granted to one of their roles and contains at least one tool.
• If two administrators change the section order, or the tools in the same section, at the same time, the last change saved wins.

Where These Settings Used To Be#

---

Before Tools (Beta), sections were called tool groups. In Settings › Roles & Tools, you select a role and open its Tools tab, which both grants tool groups to that role and creates new ones (Create Custom Tool Group). Tools (Beta) takes over only the second job; granting sections to roles is still done per role. That screen still works and edits the same navigation. Some differences:

• Tools inside a section can now be reordered by dragging.
• Sections can exist with no tools; they're simply hidden from menus until they have some.
• Custom content tools, created with Create Custom Content Tool on the old screen, are created with New Tool here.

Developer Notes#

---

• Portlet id: tools-beta, shown as Tools (Beta), served at /dotAdmin/#/tools-beta. It isn't in any default layout and isn't added by an upgrade task.
• To roll back, remove tools-beta from its section. No code change or redeploy is needed.
• The screen uses these REST endpoints:

• Reading sections requires the tools or tools-beta portlet; changing them also requires CMS Administrator. The section writes replace whole lists, with no version check.
• The legacy Roles & Tools screen and its DWR (RoleAjax) methods remain in place.