File Explorer Menu for Alfresco

The File Explorer Menu for Alfresco is a Windows 10/11 client side extension for the fileServersNG module. The extension provides a right click context menu for Alfresco mounted drives within the File Explorer application.

On the Alfresco Drive context menu are a number of actions, some of the actions are built in to the fileServersNG module, such as the ability to check a file out of Alfresco, create a working copy of the file and lock the original file on the server so that others cannot alter it. Other actions can be provided using server-side scripts.

The current list of built-in actions is :-

• Check file(s) out of Alfresco
  Creates a working copy for each file, and locks the original file(s) on the server.
• Check file(s) in to Alfresco
  Check working copy files back into Alfresco, updating the original document, removing the working copy file(s) and lock(s) on the original file(s).
  Also has an option to cancel the check out so that any changes to the working copy file(s) are lost, working copy file(s) and lock(s) are removed.
• Open file in Alfresco
  Opens the selected file in a web browser using the Alfresco Share interface.

The context menu actions work on the files and/or folders that are selected within File Explorer when an item is right clicked. Actions may work on files only, folders only, files and folders, and may work on single selected files or folders, or multiple selections. If an action does not support the list of items selected within File Explorer then the action menu will be shown disabled to indicate that the action is not available.

Installation

The File Explorer Menu for Alfresco application is installed using a standard Windows installer file, available here, and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available here).

After installation, on Windows 10 you will need to reboot the system, on Windows 11 you can either close all File Explorer windows or reboot the system.

Client Application

The File Explorer Menu for Alfresco application consists of a shell extension that provides the right click context menu within the File Explorer application, and a system tray menu application that processes the actions, and can display any dialogs, or other user interface items, before or after the action has been run by the server.

The About menu will display version information about the application, and if an Alfresco drive is currently mapped, it will display details about the client application interface, such as the version, supported actions and configured server-side actions.

The Copy and Close option will copy the application version information, and client application interface details if an Alfresco drive is mapped, to the clipboard. This can be pasted into an email for support if requested.

Server Configuration

There are a number of server configuration values that control the setup of the File Explorer Menu for Alfresco application. The current list of server configuration values :-

Configuration Property	Description
smb.clientAPI.enabled	Enable the client API interface, set to either true or false, defaults to true
smb.clientAPI.shareBaseURL	URL of the top level of the Share interface, in http://host:port/share or https://host:port/share format.
smb.clientAPI.scriptsDir	The path of the scripts folder where the scripts configuration file, scripts.toml, and the server-side scripts files are located.
smb.clientAPI.debug	Enable debug output from the server-side client API processing, set the value to true
smb.clientAPI.menu_title	The context menu title, defaults to Alfresco Drive
smb.clientAPI.menu_description	The context menu description, defaults to Alfresco Drive File Explorer menu
smb.clientAPI.menu_icon	The context menu icon, defaults to the Filesys.org Alfresco icon (value FileSysOrgAlfresco)

The smb.clientAPI.shareBaseURL value is used by the Open in Alfresco action to open the selected file/folder in a Share browser view. The value is also available for server-side scripts to use to build URLs.

The built-in actions and server-side scripted actions are configured using a TOML format file called scripts.toml in the smb.clientAPI.scriptsDir folder. The server-side script files are placed in the same folder as the scripts.toml file.

scripts.toml

The scripts.toml file configures which built-in actions (such as check in/out) are available to the File Explorer Menu for Alfresco client application, and also defines server-side actions that are made available on the File Explorer context menu.

The scripts.toml file has the following format :-

 [BuiltInActions]
   CheckInOut = true|false
   OpenInBrowser = true|false
 
 [[Action]]
 name = "<Action name that appears on the context menu>"
 description = "<description>"
 script = "<script-file-name>"
 attributes = ["Files", "Folders", "MultiSelect"]
 icon = "<icon-name>"

 [[Action]]
 ..
 ..

If the [BuiltInActions] section is not specified then all built-in actions are enabled by default.

If the scripts.toml file is modified whilst the Alfresco server is running the configuration will be reloaded without needing to restart the server.

The attributes setting of a scripted action defines what types of selections the action context menu will be enabled for. Files indicates the action works on a file, Folders indicates the action works on folders, MultiSelect indicates the action works on multiple selections of files and/or folders.

If the selected item(s) in File Explorer do not match the action attributes the action menu will be disabled.

The possible attributes settings :-

• attributes = ["Files"]
  Action only accepts a single selected file item
• attributes = ["Folders"]
  Action only accepts a single selected folder item
• attributes = ["Files", "Folders"]
  Action accepts either a single selected file or folder item
• attributes = ["Files", "MultiSelect"]
  Action accepts one or more selected file items
• attributes = ["Folders", "MultiSelect"]
  Action accepts one or more selected folder items
• attributes = ["Files", "Folders", "MultiSelect"]
  Action accepts one or more selected file and/or folder items, the selection may be a mixture of files and folders

The icon setting is optional, it is used to specify the context menu icon to be used for the action. There are a number of preset icon names available or a custom icon can be specified using the syntax Custom:<dll-name>,<icon-index>, where <dll-name> is the name of a Windows system DLL that contains the icon, and <icon-index> is the index of the icon resource within the DLL.

The Windows shell32.dll has many icons available.

The following preset icon names are available to configure actions :-

Icon	Name	Description
	ShellScript	Script icon
	ShellWebBrowser	Web browser icon
	ShellFolder	Folder icon
	ShellPrinter	Printer icon
	ShellMagnify	Magnifying glass icon
	ShellStar	Star icon
	ShellLock	Lock icon
	ShellMovie	Movie icon
	ShellAudio	Audio icon
	ShellCamera	Camera icon
	ShellInformation	Information icon
	ShellHome	Home icon
	ShellGear	Gear icon
	FileSysOrgAlfresco	Filesys.org Alfresco application icon
	FileSysOrg	Filesys.org application icon
	AlfrescoCheckIn	Alfresco check in icon
	AlfrescoCheckOut	Alfresco check out icon

Server-side Scripts

The server-side scripted actions are written using JavaScript. A simple server-side script that generates a URL to the Share details page for the selected file/folder, which the client application then opens in a web browser on the client :-

function runAction()
{
  var urlStr = shareURL + "page/document-details?nodeRef=" + params.getTarget(0).getNode().getStoreRef()
    + params.getTarget(0).getNode().getId();

  result.setSuccess();
  result.setClientOpenURL( urlStr);

  return result;
}

var result = runAction();

result;

A number of Java objects are made available to the server-side script, to pass in details of the selected item(s) and to return a result to the client application.

The following Java objects are passed to the server-side script environment :-

Java Object Name	Description
params	A DesktopParams object containing details of the folder node that the script is running in, plus the list of selected target nodes from the client side selection. See below for a list of the useful methods on the DesktopParams object.
result	A RunScriptResponse object that contains the server-side script response to be sent to the client application. The response indicates if the script was successful, and actions the client application may take, such as opening the returned URL in a web browser on the client in the example script above. See below for a list of useful methods on the RunScriptResponse object.
out	The Java System.out stream value, allowing the script to output to the Alfresco log file.
shareURL	Value of the smb.clientAPI.shareBaseURL value, if configured.
registry	The ServiceRegistry object, useful to get hold of Alfresco service objects
nodes	A convenience object to get node information using the NodeRef

The DesktopParams object has the following useful methods that a server-side script can call :-

Method Name	Description
NodeRef getFolderNode()	Returns the parent folder NodeRef that the script is running in.
int numberOfTargetNodes()	The number of nodes selected on the client.
DesktopTarget getTarget(int idx)	Get the details of the specified selected node, as a DesktopTarget object. See below for a list of useful methods on the DesktopTarget object.
String getPathAt(int idx)	Return the relative path of the specified selected node.

The DesktopTarget object has the following useful methods that a server-side script can call :-

Method Name	Description
boolean isFile()	Returns true if the node is a file.
boolean isFolder()	Returns true if the node is a folder.
String getPath()	Return the relative path of the target node.
String getExtension()	Return the file extension of the file node, ie. the part after the last dot in the file path.
String getParentPath()	Return the relative parent path of this node.
NodeRef getNode()	Return the node for the selected file/folder.

The Nodes object has the following useful methods that a server-side script can call :-

Method Name	Description
isVersionable( NodeRef)	Check if the node has the Versionable aspect
isWorkingCopy( NodeRef)	Check if the node is a working copy
isWorkingCopyOriginal( NodeRef)	Check if the node is the original document of a working copy, the document will be locked
isLockable( NodeRef)	Check if the node can be locked
isLocked( NodeRef)	Check if the node is locked

The RunScriptResponse object has the following useful methods a server-side script can call :-

Method Name	Description
void setSuccess()	Return a success status to the client application.
void setError(String errMsg)	Return an error status to the client application with the specified error message that will be displayed on the client.
void setOpenURL(String url)	Return a success to the client application with a URL to be opened in a web browser on the client.
void setMessage(String msg)	Return an informational message to the client application to be displayed using the standard client message dialog.
void setMessage(String msg, String msgLevel)	Return a message to the client application to be displayed using the standard client message dialog, with a message level of either Info, Warn or Error. The client message dialog will display a different icon depending on the msgLevel value.
void setWarningMessage(String msg)	Return a warning message to the client application to be displayed using the standard client warning message dialog.
void setWarningMessage(String title, String msg)	Return a warning message to the client application to be displayed using the standard client warning message dialog, with the specified title for the dialog.
setErrorMessage(String msg)	Return an error message to the client application to be displayed using the standard client error message dialog.
setErrorMessage(String title, String msg)	Return an error message to the client application to be displayed using the standard client error message dialog, with the specified title for the dialog.
void setExecute(String operation, String app)	Return details of an application to be opened on the client with the specified operation. On Windows clients the application will be started using the ShellExecute() API call.
void setExecute(String operation, String app, String param)	Return details of an application to be opened on the client with the specified operation and parameter. On Windows clients the application will be started using the ShellExecute() API call.
setRefreshOriginal(boolean)	Refresh the details of the files/folders on the client for files/folders that were selected for the server action.
setNotification(String msg)	Show a notification on the client with the specified message. The message text may be up to 4 lines. A notification can be returned with other actions (messages, open URL, execute, set paths).
setNotification(String title, String msg)	Show a notification on the client with the specified title and message. The message text may be up to 4 lines. A notification can be returned with other actions (messages, open URL, execute, set paths).
setCreatedPaths(List<String>)	Notifies the client of a list of new files/folders that have been created on the server so the client can refresh view(s).
setUpdatedPaths(List<String>)	Notifies the client of a list of files/folders that have been updated by the server-side action so the client can refresh view(s).
setRemovedPaths(List<String>)	Notifies the client of a list of files/folders that have been removed by the server-side action so the client can refresh view(s).