CMSUser Viewtool

The CMSUsersWebAPI, or $cmsuser, is a Velocity Viewtool that allows velocity access to user properties. A bridge between Velocity templates and dotCMS's user management system, it enables template developers to retrieve user information such as roles and permissions, and easily work with the current logged-in user object.

Methods Summary #

Method	Return Type	Parameters	Description
`getUserByEmail(String email)`	`User`	`email` - User's email address	Retrieves a user by their email address
`getUserByUserId(String userId)`	`User`	`userId` - User's unique identifier	Retrieves a user by their user ID
`getLoggedInUser(HttpServletRequest request)`	`User`	`request` - HTTP servlet request	Retrieves the currently logged-in user from the session
`getAllUsersInGroup(String groupId)`	`List<User>`	`groupId` - Role identifier	Returns all users belonging to a specific role
`getUserRoles(User user)`	`List<Role>`	`user` - User object	Returns all roles assigned to the user
`isUserRole(User user, String roleName)`	`boolean`	`user` - User object `roleName` - Name of the role	Checks if a user has a specific role by name
`hasRole(String roleKey)`	`boolean`	`roleKey` - Role key identifier	Checks if the currently logged-in user has a specific role by key
`isCMSAdmin(User user)`	`boolean`	`user` - User object	Checks if a user has CMS Admin privileges

Usage Examples #

Display Logged-In User Information #

#set($currentUser = $cmsuser.getLoggedInUser($request))

#if($currentUser)
    <div class="user-welcome">
        <h2>Welcome, ${currentUser.firstName} ${currentUser.lastName}!</h2>
        <p>Email: ${currentUser.emailAddress}</p>
    </div>
#else
    <div class="user-welcome">
        <p>Please log in to continue.</p>
    </div>
#end

Check User Roles and Display Conditional Content #

#set($currentUser = $cmsuser.getLoggedInUser($request))

#if($currentUser)
    #if($cmsuser.isCMSAdmin($currentUser))
        <div class="admin-panel">
            <h3>Administrator Dashboard</h3>
            <a href="/admin">Access Admin Tools</a>
        </div>
    #elseif($cmsuser.isUserRole($currentUser, "Editor"))
        <div class="editor-panel">
            <h3>Editor Tools</h3>
            <a href="/edit-content">Edit Content</a>
        </div>
    #else
        <div class="user-panel">
            <h3>User Dashboard</h3>
            <p>Standard user access</p>
        </div>
    #end
#end

Retrieve User by Email #

#set($authorEmail = "john.doe@example.com")
#set($author = $cmsuser.getUserByEmail($authorEmail))

#if($author)
    <div class="author-bio">
        <h3>About the Author</h3>
        <p><strong>${author.firstName} ${author.lastName}</strong></p>
        <p>Contact: ${author.emailAddress}</p>
    </div>
#else
    <p>Author information not available.</p>
#end

Display All User Roles #

#set($currentUser = $cmsuser.getLoggedInUser($request))

#if($currentUser)
    #set($userRoles = $cmsuser.getUserRoles($currentUser))
    
    <div class="user-roles">
        <h3>Your Roles:</h3>
        <ul>
        #foreach($role in $userRoles)
            <li>${role.name}</li>
        #end
        </ul>
    </div>
#end

Check Role by Key #

#if($cmsuser.hasRole("DOTCMS_BACK_END_USER"))
    <div class="contributor-tools">
        <a href="/submit-content" class="btn">Submit New Content</a>
    </div>
#end

List All Users in a Role #

#set($devRole = "Scripting Developer")
#set($scriptDevs = $cmsuser.getAllUsersInGroup($devRole))

<div class="team-directory">
    <h3>Scripting Team</h3>
    <ul>
    #foreach($dev in $scriptDevs)
        <li>
            ${dev.firstName} ${dev.lastName} - ${dev.emailAddress}
        </li>
    #end
    </ul>
</div>

Retrieve User by ID and Display Their Profile #

#set($userId = "user-12345")
#set($profileUser = $cmsuser.getUserByUserId($userId))

#if($profileUser)
    <div class="user-profile">
        <h2>${profileUser.firstName} ${profileUser.lastName}</h2>
        <p>User ID: ${profileUser.userId}</p>
        <p>Email: ${profileUser.emailAddress}</p>
        
        #if($cmsuser.isCMSAdmin($profileUser))
            <span class="badge admin">Administrator</span>
        #end
    </div>
#end

Important Notes #

The getAllUsersInGroup() method is named for a deprecated group function; now returns users belonging to a role rather than a traditional group.
- Similarly, getUserGroups() performs the same operation as getUserRoles(), and has therefore been omitted from the table for simplicity.
The hasRole() method operates on the currently logged-in user initialized during ViewTool instantiation.
Best practice: Check if a user object is not null before attempting to access its properties.
The tool uses the system user context for most API operations to ensure proper permission handling.
Role checking is case-sensitive; ensure role names match exactly.

Error Handling #

The ViewTool includes built-in error handling that logs errors and returns null or empty collections when operations fail. Always verify return values before using them in templates to avoid null pointer exceptions.

Toolbox Mapping #

The following example shows how the CMSUsersWebAPI Viewtool is mapped in the toolbox.xml file:

    <tool>
        <key>cmsuser</key>
        <scope>request</scope>
        <class>com.dotcms.rendering.velocity.viewtools.CMSUsersWebAPI</class>
    </tool>