Custom Tool Groups

Last Updated: Apr 5, 2024
documentation for the dotCMS Content Management System

In addition to the default Tool Groups provided with the dotCMS starter site, you can create your own Tool Groups. This allows you to create Tool Groups with the exact combination of tools needed to give each of your Roles access to just the tools they need, which both simplifies the back-end interface for your users and improves security.

Creating a Custom Tool Group

To create a custom Tool Group:

  1. Select System -> Roles & Tools from the navigation side bar.
  2. Select a Role that will receive access to the new custom Tool Group.
  3. Click the Tools tab.
  4. In the Role detail area, click the Create Custom Tool Group button.

Configure Custom Tool Group

The Edit Tool Group popup contains the following properties:

Tool GroupThe name of the Tool Group, which will display as a heading on the navigation side bar.
IconThe system name of a Material Icon.
  • If you do not supply an icon name, or if the name does not match a valid Material Icon, a default icon will be displayed.
  • Do not use label_important as a tool group icon; it invokes a default-icon fallback routine intended to help with version upgrades, and will be replaced automatically.
OrderAn integer specifying the order the Tool Group will display in the navigation side bar.
  • Tool Groups will display in ascending order based on this number.
ToolsDisplays a list of the tools in the Tool Group, and allows you to add, remove, and re-order the tools within the Tool Group.

Available Tools

The following tools are included by default with dotCMS, and can be assigned to any Tool Group. Note that some of these tools are deprecated legacy tools that are only provided for backward-compatibility for existing dotCMS customers, and it it is strongly recommended that you do not use any deprecated tools when creating new Tool Groups.

ToolFeature(s)Default Location
BrowserSite BrowserSite -> Browser
CalendarEvents CalendarContent -> Calendar
CategoriesCategoriesTypes & Tags -> Categories
ConfigurationConfiguration for your dotCMS instance, including
Branding & Basic Information,
License Management,
Cluster Status, and
Push Publishing server configuration
System -> Configuration
ContainersContainersSite -> Containers
Content TypesContent TypesTypes & Tags -> Content Types
Custom ContentCustomized Content SearchNone
DashboardSite DashboardHome -> Dashboard
ES SearchES SearchDev Tools -> ES Search
FormsForm BuilderMarketing -> Forms
Job SchedulerJob SchedulerNone
LanguagesLanguagesTypes & Tags -> Languages
Link CheckerLink CheckerContent -> Link Checker
LinksMenu LinksSite -> Links
MaintenanceSeveral Administration and maintenance tasksSystem -> Maintenance
PluginsDynamic PluginsDev Tools -> Plugins
Publishing QueuePush PublishingContent -> Publishing Queue
Query ToolQuery ToolDev Tools -> Query Tool
Reports(Legacy) ReportsNone
Roles & ToolsRole permissions and Tool GroupsSystem -> Roles & Tools
RulesRulesMarketing -> Rules
SearchContent SearchContent -> Search
Site SearchSite SearchDev Tools -> Site Search
SitesSitesSystem -> Sites
TagsTag ManagerTypes & Tags -> Tags
TasksUser's assigned Workflow tasksHome -> Tasks
TemplatesTemplatesSite -> Templates
Time MachineTime MachineSite -> Time Machine
UsersUser ManagementSystem -> Users
Vanity URLsVanity URLsMarketing -> Vanity URLs
WorkflowContent Type WorkflowsTypes & Tags -> Workflow

Custom Content Tool

The Custom Content Tool enables you to create a screen which allows users to interact with content in the same way as the default Content Search Tool, but limits the Content Types displayed and managed in the Tool. In addition when admins are creating a custom content tool they can choose if they want the default view to be cards or list form.

  • For example, rather than having a single Content Search screen for users to access Blog, News, and Product content types, you could create a separate Tools for “Blogs”, “News”, and “Products”.

Each Custom Content Tool can then be added and removed from different Tool Groups, allowing you to make different Content Types easily accessible to different users and Roles. Having different Content Types in different Tools can help you to simplify and organize your content in a way that makes it easier for your content contributors to work with the content.

  • For example, the “Vanity URL” tool is essentially a Custom Content Tool which only displays the Vanity URL Content Type. Placing it in under the “Marketing” Tool Group (instead of the “Content” Tool Group) makes it easier for content contributors who work on marketing activities to find and work with it.

It's important to understand that the Custom Content Tool does not affect user permissions on the content. This means that if a user does not have appropriate permissions to view and edit content of a given Content Type, giving the user access to a Custom Content Tool that displays that Content Type will not give the user the ability to view or edit the content.

Specifying Content Types

When configuring a Custom Content Tool, you may choose to include one specific Content Types (using the Velocity variable name of the Content Type), or all Content Types of one or more Base Content Types.

Create A Custom Content Tool Via User Interface

There are two ways to add a Custom Content Tool through the traditional interface: Either from within the Roles & Tools menu or the Content Types menu.

From the Roles & Tools Menu

From Settings > Roles & Tools, click the Tools tab and you will find the Create Custom Content Tool button.

Create Custom Content Tool button location.

This opens a dialog with the following fields:

Tool NameThe name of the custom Tool, which will display in the navigation sidebar
IdThe system variable name for the custom Tool
Base TypesComma-separated list that may include any of the following: CONTENT, WIDGET, FORM, FILEASSET, HTMLPAGE, PERSONA, VANITY_URL or KEY_VALUE
OR Content TypesComma-separated list of Content Type variable names (e.g. blog, webPageContent, etc.)
Data View ModeSelect either List view or Card view

The Base Types and Content Types fields are, as indicated, mutually exclusive.

From the Content Types Menu

You can create a Custom Content Tool corresponding to a single Content Type using the dotCMS user interface with just a few clicks. Simply browse to Types & Tags -> Content Type. There, click the “hamburger” button (three dots) to the right of the Content Type you'd like to represent as a tool.

Add to Menu option in Content Type hamburger menu.

The following modal dialog appears, allowing you to select which Tool Group will host the new tool.

Modal dialog for adding Content Type to menu.

Finally, the result will appear in the specified Tool Group in the left-hand menu on the next refresh.

New Custom Content Tool appears on menu.

Create a Custom Content Tool Headlessly

In this example, we'll use the same details as in the “traditional” example immediately above.

Creating a Custom Content Tool through the API requires, at minimum, a call to create the tool, and then a call to add it to the appropriate Tool Group. However, you may also first need to fetch the identifier for the menu:

curl -v -u -XGET ttps://

The GET call to api/v1/menu returns an array of objects representing all active Tool Groups. Each has an id data member containing the identifier you'll need to serve as the layoutId in the final step. In this case, we'll note the identifier corresponding to the “Site” Tool Group.

Next, use a POST call to /api/v1/portlet/custom to create the tool:

curl -v -u -XPOST -H "Content-Type: application/json" --data @toolCreate.json

The payload, in this case contained in the toolCreate.json file, would look like this:

    "portletName": "Blog",
    "contentTypes": "Blog",
    "baseTypes": "CONTENT",
    "dataViewMode": "list",
    "portletId": "Blog_list"

To add multiple Content Types to a Custom Content Tool, simply specify a comma-separated list of Content Type variables, e.g.:

    "contentTypes": "Blog,BlogComment",

Finally, apply the newly created tool to the appropriate Tool Group via PUT call to /api/v1/portlet/custom/{portletId}/_addtolayout/{layoutId}:

curl -v -u -XPUT

If you repeat the original api/v1/menu call, you will now see the new tool added to the correct Tool Group.

It is also possible to update a custom content tool — altering any aspect except its identifier — by making a PUT call to /api/v1/portlet/custom, providing a body payload:

    "portletId": "{{portletId}}",
    "portletName": "updated name",
    "baseTypes": "CONTENT",
    "contentTypes": "",
    "dataViewMode": "list"

Finally, fetching a custom content tool of which you already know the identifier is as simple as a GET call to /api/v1/portlet/{{portletId}}.

Custom Tools

You may also use plugins to create your own custom tools, which you can then add to any Tool Group. For more information on creating and using plugins, please see the Developing documentation section.

On this page


We Dig Feedback

Selected excerpt: