Enhancement: Add find(identifier) method to FolderWebAPI viewtool

[Neehakethi]

Summary

Add a find(String folderIdOrInode) method to the FolderWebAPI viewtool ($folderAPI) to allow retrieving a Folder object by its identifier directly in Velocity templates.

Problem

Currently, when working with folders in VTL (Velocity Template Language), there is no way to retrieve a Folder object using just its identifier. The existing methods require either:

• A path (findCurrentFolder(path, host))
• Or return menu items instead of the folder itself (findMenuItems(folderInode))

This is a common use case, especially in workflow sub-action scripts where users have access to a folder's identifier but need to retrieve folder properties like path, name, or title.

Current State

The FolderWebAPI.java currently has these methods:

Method	Input	Returns
findMenuItems(path, request)	Path + Request	List<Inode> (menu items)
findMenuItems(folderInode)	Inode/Identifier	List<Inode> (menu items)
findCurrentFolder(path, host)	Path + Host	Folder ✅
find(identifier)	Identifier	❌ Not available

Interestingly, the internal FolderAPI.find() method is already being used inside findMenuItems() (line 35), but the Folder object is not exposed - only used to fetch menu items.

Proposed Solution

Add the following method to FolderWebAPI.java:

/**
 * Finds a folder by its identifier or inode.
 * 
 * @param folderIdOrInode The folder identifier or inode to search for
 * @return The Folder object if found, null otherwise
 * @throws DotDataException If there is a data access error
 * @throws DotSecurityException If there is a security/permission error
 */
public Folder find(String folderIdOrInode) throws DotDataException, DotSecurityException {
    return folderAPI.find(folderIdOrInode, APILocator.getUserAPI().getSystemUser(), true);
}

VTL Usage Example

After this enhancement, users will be able to:

#set($folderIdentifier = "0aac3c3a79b23374eac2f7ab90841bc7e")
#set($folder = $folderAPI.find($folderIdentifier))

#if($folder && $folder.identifier)
    <p>Folder Name: $folder.name</p>
    <p>Folder Path: $folder.path</p>
    <p>Folder Title: $folder.title</p>
    <p>Folder Identifier: $folder.identifier</p>
    <p>Host ID: $folder.hostId</p>
#else
    <p>Folder not found</p>
#end

Use Case

A customer reported needing this functionality in a workflow sub-action script to track changed page URLs. They have access to the folder identifier from the saved content but need to retrieve the folder's path property. Currently, there's no clean way to do this in VTL without using the SQL viewtool to query the database directly.

Files to Modify

• dotCMS/src/main/java/com/dotcms/rendering/velocity/viewtools/FolderWebAPI.java

Impact

• Low risk: Simple addition that exposes existing internal functionality
• No breaking changes: Adds new method without modifying existing ones
• Consistent API: Follows the same pattern as other viewtools that expose find() methods

Labels

• Enhancement
• Velocity
• API

https://dotcms.freshdesk.com/a/tickets/34380

[github-actions[bot]]

PRs linked to this issue

• add find(identifier) method to FolderWebAPI viewtool (#34033) by @Neehakethi

[gortiz-dotcms]

Passed QA