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 client application, 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.

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 scripted 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.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

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 scripts 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"]
 
 [[Action]]
 ..
 ..

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

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

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

Server-side Scripts

The server-side scripted actions are written using JavaScript. A simple server-side script :-

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.

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 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 setClientOpenURL(String url)	Return a success to the client application with a URL to be opened in a web browser on the client.
void setClientMessage(String msg)	Return an informational message to the client application to be displayed using the standard client message dialog.
void setClientMessage(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 setClientExecute(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 setClientExecute(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.