FileSys.Org Wiki - User contributions [en]

How to build and deploy the fileServersNG subsystem

2026-07-09T15:24:40Z

Tommygonk:

fileServersNG is a replacement for the Alfresco file servers subsystem that uses the JFileServer code, and optionally JFileServer Enterprise add-on, to provide the file server capabilities for Alfresco (currently SMB and FTP/FTPS protocols). The fileServersNG subsystem is built as an AMP (Alfresco Module Package) that can then be deployed into an Alfresco Content Management Server setup.

The fileServersNG subsystem contains the JFileServer Enterprise add-on but requires a licence key to enable the additional functionality. With no valid licence key the file server subsystem will use the standard JFileServer protocols and functionality.

There are Docker images available with Alfresco 5.x and 6.0 servers configures with the fileServersNG file server subsystem, for more details see [[Using the fileServersNG Docker Image|here]].

== The fileServersNG v5 Subsystem ==
For Alfresco version v5.x, and v4.x, use the fileServersNG-v5 project to build the AMP.

=== Building the fileServersNG v5 AMP ===
To build the fileServersNG-v5 AMP for use with Alfresco v5.x and v4.x.

* Clone, or download the project zip file and unpack it, from the GitHub project at https://github.com/FileSysOrg/fileServersNG-v5.
* Get your Alfresco version number
One way to get the Alfresco version is to login using Share, click on the Alfresco logo at the bottom of the page, in the popup window you should see the Alfresco version, for example '5.2.f'.
* Edit the pom.xml
In the fileServersNG-v5 project folder edit the pom.xml file, set the <alfresco.platform.version> to match your Alfresco version.
* Build the AMP file
Using the command :-

mvn clean package

This should generate the AMP file in the target/ folder with the name ''fileServersNG-v5-1.x.x.amp''.

=== Deploying the fileServersNG v5 Subsystem ===
* Copy the fileServersNG-v5.1.x.x.amp file to the alfresco/amps folder of your Alfresco server setup
* Register the AMP using the following command

java -jar /alfresco/bin/alfresco-mmt.jar install <path-to-fileServersNG-amp-file> <path-to-alfresco-war-file> [-nobackup] [-force]

Where <path-to-fileServersNG-amp-file> is the path to the fileServersNG-v5-1.x.x.amp file in the alfresco/amps folder, and <path-to-alfresco-war-file> is the path to the original Alfresco WAR file that was deployed to the web server. If you used the Alfresco installer this would usually be the tomcat/webapps/alfresco.war file.

* Update your Alfresco configuration
Usually done via the alfresco-global.properties file.
Disable the original file servers subsystem using :-

cifs.enabled=false
ftp.enabled=false

Enable and configure the fileServersNG subsystem, for example :-

smb.enabled=true
ftpng.enabled=true

smb.tcpipSMB.port=1445
smb.dialects=SMB1
smb.sessionDebug=Negotiate,Socket

ftp.port=1121
ftp.sessionDebug=State,PktType

==== Additional Setup For The JFileServer Enterprise Add-On ====
The JFileServer Enterprise add-on requires a valid licence key to enable it. Create the folder for the licence file at ''tomcat/shared/classes/license''. Copy your JFileServer licence file, named jfileserver.lic, into the ''tomcat/shared/classes/license'' folder.

With the JFileServer Enterprise add-on the ''smb.dialects'' setting can also include ''SMB2 and ''SMB3 to enable the SMB2 protocol and SMB3 encryption. Use a comma delimited list of the SMB dialects to enable.

== The fileServersNG v6 Subsystem ==
For Alfresco version v6.0 use the fileServersNG-v6 project to build the AMP.

=== Building the fileServersNG v6 AMP ===
To build the fileServersNG-v6 AMP for use with Alfresco v6.0.

* Clone, or download the project zip file and unpack it, from the GitHub project at https://github.com/FileSysOrg/fileServersNG-v6.
* Build the AMP file
Using the command :-

mvn clean package

This should generate the AMP file in the target/ folder with the name ''fileServersNG-v6-1.x.x.amp''.

=== Deploying the fileServersNG v6 Subsystem ===
* Copy the fileServersNG-v6.1.x.x.amp file to the alfresco/amps folder of your Alfresco server setup
* Register the AMP using the following command

java -jar /alfresco/bin/alfresco-mmt-6.0.jar install <path-to-fileServersNG-amp-file> <path-to-alfresco-webapp> [-nobackup] [-force]

Where <path-to-fileServersNG-amp-file> is the path to the fileServersNG-v6-1.x.x.amp file in the alfresco/amps folder, and <path-to-alfresco-webapp> is the path to the Alfresco webapp folder on the web server.

Alfresco v6.x uses a containerised setup where a number of Docker images run the Alfresco repository, database server, indexing service and Share UI. See the wiki page about running the fileServersNG-v6 Docker image for details on how to run and configure the fileServersNG-v6 file servers subsystem [[Using the fileServersNG Docker Images#fileServersNG v6|here]].

== The fileServersNG v6.1 Subsystem ==
For Alfresco version v6.1 use the fileServersNG-v61 project to build the AMP.

=== Building the fileServersNG v6.1 AMP ===
To build the fileServersNG-v61 AMP for use with Alfresco v6.1.

* Clone, or download the project zip file and unpack it, from the GitHub project at https://github.com/FileSysOrg/fileServersNG-v61.
* Build the AMP file
Using the command :-

mvn clean package

This should generate the AMP file in the target/ folder with the name ''fileserversng-v61-1.x.x.amp''.

=== Deploying the fileServersNG v6.1 Subsystem ===
* Copy the fileserversng-v6.1.x.x.amp file to the alfresco/amps folder of your Alfresco server setup
* Register the AMP using the following command

java -jar /alfresco/bin/alfresco-mmt-6.0.jar install <path-to-fileServersNG-amp-file> <path-to-alfresco-webapp> [-nobackup] [-force]

Where <path-to-fileServersNG-amp-file> is the path to the fileserversng-v6-1.x.x.amp file in the alfresco/amps folder, and <path-to-alfresco-webapp> is the path to the Alfresco webapp folder on the web server.

Alfresco v6.x uses a containerised setup where a number of Docker images run the Alfresco repository, database server, indexing service and Share UI. See the wiki page about running the fileServersNG-v61 Docker image for details on how to run and configure the fileServersNG-v61 file servers subsystem [[Using the fileServersNG Docker Images#fileServersNG v61|here]].

Configuring JFileServer

2026-06-26T08:13:14Z

Tommygonk: /* SMB Server Configuration */

JFileServer file server is configured using a simple XML file, the same configuration format is used by the Enterprise version of the file server.

The configuration is contained within the <fileserver> main section with various sub-sections to configure which file server protocols are enabled, configuration for each protocol, security and debug logging. Here's an overview of the XML configuration file :-

<fileserver>
<servers>...</servers>
<SMB>...</SMB>
<FTP>...</FTP>
<NFS>...</NFS>
<shares>...</shares>
<debug>...</debug>
<security>...</security>
<licence>...</licence>
<server-core...</server-core>
</fileserver>

Environment variables may be used in attributes and values within the XML configuration using the syntax ''${env-var-name}''.

Some configuration settings allow an optional ''platforms="..."'' attribute, this allows a configuration to be used on multiple platforms. If the current platform that the JFileServer is running on is not listed in the ''platforms="..."'' list then the setting will be ignored.

The available platform values are Windows, Linux, MacOSX and Solaris. The platforms value is a comma delimited list of valid platforms for the current setting.

The <server> configuration section is used to enable or disable which file server protocols are available. The syntax has changed from the JLAN configuration as each protocol now has an ''enable="true|false"'' attribute, this makes it easier to use an environment variable to control whether a particular file server protocol is enabled.

The <servers> configuration section has the following syntax :-

<servers>
<SMB enable="true|false">
<FTP enable="true|false">
<NFS enable="true|false">
</servers>

== SMB Server Configuration ==

The <SMB> configuration section is used to configure the SMB protocol server that allows a drive or mount to be mapped to the JFileServer file server which can then be accessed as if it were a local drive on the client system.

The <SMB> configuration section has the following syntax :-

<SMB>
<host>
<broadcast>...</broadcast>
<smbdialects>...</smbdialects>
<comment>...</comment>
<netBIOSSMB .../>
<tcpipSMB .../>
<hostAnnounce .../>
<idleCheckOpenFiles/>
</host>

<requireSigning/>
<disableEncryption/>

<authenticator ...>
...
</authenticator>
<sessionDebug .../>
</SMB>

'''Note:''' The JLAN XML configuration has <Win32NetBIOS/> and <Win32Announce/> configuration options, these are currently ignored by JFileServer as the Win32 NetBIOS legacy code has been moved out into a seperate add-on project. With most clients using native SMB connections on port 445, and SMB2/SMB3 connections requiring native SMB connections, there are only a small number of special cases where the Win32 NetBIOS interface is of use.

The <requireSigning/> configuration setting indicates that the server will only accept SMB2 connections that have signing enabled. It is only currently relevant when the SMB2 dialect is enabled.

=== The <host> Configuration Section ===

The <host> sub-section contains the main networking and protocol configuration settings.

The <broadcast> setting specifies the network broadcast mask that is required to send broadcast datagrams, used by the NetBIOS protocol and host announcement. JFileServer now accepts the setting of 'AUTO' where the broadcast mask will be determined automatically. In some cases this may not work, you will then need to specify the broadcast mask. For eample if your network addresses are in the 192.168.1.x/8 range the broadcast mask would be 192.168.1.255.

The <smbdialects> setting configures which SMB dialects the file server will negotiate with a client. The value should be a comma delimited list of dialect names. The high level dialect names available are SMB1 for the standard server, plus SMB2 and SMB3 for the Enterprise server.

The <comment> setting provides a comment that is visible to clients when displaying the server properties.

The <netBIOSSMB .../> setting configures the SMB file server to use the TCPIP socket based NetBIOS protocol. The default setting of <netBIOSSMB/> will enable the TCPIP NetBIOS interface using TCP port 139 and UDP ports 137 and 138. These settings can be overridden using the sessionPort="...", namingPort="..." and datagramPort="..." attributes. For example, if running JFileServer on a linux or Mac system as a normal user the server will not be able to bind the privileged ports 137/138/139, so we may use the following configuration and use firewall rules to forward the network traffic to the unprivileged ports :-

<netBIOSSMB sessionPort="1139" namingPort="1137" datagramPort="1138"/>

An optional platforms="..." attribute may be used for the NetBIOS SMB setting.

The <tcpipSMB> setting configures the SMB file server to use the native SMB socket based protocol. The default setting of <tcpipSMB/> will enable the native SMB interface using TCP port 445. This setting can be overridden using the port="..." attribute. For example, if running JFileServer on a linux or Mac system as a normal user the server will not be able to bind the privileged port 445, so we may use the following configuration and use firewall rules to forward the network traffic to the unprivileged port :-

<tcpipSMB port="1445"/>

An optional platforms="..." attribute may be used for the TCPIP SMB setting.

The <hostAnnounce .../> setting is used to enable the TCPIP NetBIOS host announcer that periodically broadcasts the server details to the local network. This allows the server to show up in the local network list or workgroup.

The default host announcement is broadcast every minute, the announcement interval can be set using the optional interval="..." attribute.

The <idleCheckOpenFiles/> setting is used to prevent sessions with open files from being removed when the idle session check is run to remove sessions that have not had any I/O within the session timeout interval (default 15 minutes).

=== The <authenticator> Configuration Section ===

The <authenticator type="..."> section configures how the SMB server handles user authentication. The optional type="..." attribute can have the values "enterprise" or "local", or it is possible to specify your own authenticator class. The enterprise authenticator setting provides the latest authentication methods such as NTLMv2 and Kerberos via the NTLMSSP and SPNEGO mechanisms. The local authenticator setting provides support for older LanMan and NTLMv1 authentication, these are considered to be insecure these days so it is recommended to use the "enterprise" setting.

For the "enterprise" setting the authenticator configuration has the following syntax :-

<authenticator type="enterprise">
<disableNTLM/>
<useSPNEGO/>
<disallowNTLMv1>

<-- Kerberos related settings -->
<Realm>...</Realm>
<Password>...</Password>
<LoginEntry>...</LoginEntry>
<kerberosDebug/>
<KerberosConfig>...</KerberosConfig>
<LoginConfig>...</LoginConfig>
</authenticator>

By default the Enterprise authenticator enables NTLM logons, either NTLMv1 or NTLMv2. To only allow the more secure NTLMv2 logons use the <disallowNTLMv1> configuration setting.

To enable Kerberos logons to the SMB file server the <Realm>, <Password> and <LoginEntry> values are required. The <Realm> setting should contain the Kerberos realm, usually the domain name in uppercase. The <Password> setting is used to access the server Kerberos setup. The <LoginEntry> setting specifies the Java JAAS login entry name to use for the SMB server service logon, the default value is ''FileServerSMB''.

The <kerberosDebug/> setting is a convenience setting that enables various Java debug output levels by setting the required properties.

The <KerberosConfig> setting allows a JFileServer specific Kerberos configuration file to be used. The setting takes the full path to the Kerberos configuration file. This is the equivalent of using the Java property ''java.security.krb5.conf''.

The <LoginConfig> setting allows a JFileServer specific Java login configuration file to be used without editing the global Java security settings file. The setting takes the full path to the login configuration file. This is the equivalent of using the Java property ''java.security.auth.login.config''.

The <useSPNEGO/> setting enables the use of SPNEGO (Simple Protected NEGOtiation) as well as the default NTLMSSP. If you have enabled Kerberos logons then SPNEGO will be enabled automatically.

=== The <sessionDebug> Configuration Setting ===

The <sessionDebug flags="..."/> setting is used to enable SMB server debug output. The flags="..." value is a comma delimited list of debug output level names from the following list :-

{| class="wikitable"
! style="text-align:left;"| Flag
! Description
|-
| PKTTYPE
| Received packet type
|-
| STATE
| Session state changes
|-
| RXDATA
| Dump received data packet
|-
| TXDATA
| Dump sent packet data
|-
| DUMPDATA
| Dump data packets
|-
| NEGOTIATE
| Protocol negotiate phase
|-
| TREE
| Tree connection/disconnection
|-
| SEARCH
| File/directory searches
|-
| INFO
| File/directory information requests
|-
| FILE
| File open/close/information requests
|-
| FILEIO
| File read/write
|-
| TRAN
| SMB transactions
|-
| ECHO
| Echo requests
|-
| ERROR
| Errors returned to the client
|-
| IPC
| IPC$ named pipe requests
|-
| LOCK
| Lock/unlock requests
|-
| DCERPC
| DCE/RPC request processing
|-
| STATECACHE
| File state cache
|-
| TIMING
| Time packet processing
|-
| NOTIFY
| Asynchronous change notifications
|-
| STREAMS
| NTFS streams handling
|-
| SOCKET
| Socket connections
|-
| PKTPOOL
| Memory pool allocate/release
|-
| PKTSTATS
| Memory pool statistics
|-
| THREADPOOL
| Thread pool handling
|-
| BENCHMARK
| Benchmarking requests
|-
| OPLOCK
| Opportunistic lock handling
|-
| PKTALLOC
| Memory pool handling
|-
| COMPOUND
| Compound request handling (Enterprise only)
|-
| CANCEL
| Cancel request handling (Enterprise only)
|-
| SIGNING
| Packet signing (Enterprise only)
|-
| ENCRYPTION
| Encryption handling (Enterprise only)
|-
|}

For example, to enable SMB server debug output to help with logon and connection issues you could use the following setting :-

<sessionDebug flags="Negotiate,Socket,State,Error"/>

=== SMB2/SMB3 Configuration ===

There are SMB2 and SMB3 specific configuration values within the <server-core> configuration section, which is separate to the <SMB> configuration section. SMB2 and SMB3 are only available when using the JFileServer Enterprise file server.

The <server-core> configuration section has the following syntax, all settings are optional :-

<server-core>
<SMB2>
<maxPacketSize>2M</maxPacketSize>
<requireSigning/>
</SMB2>
<SMB3>
<encryptionTypes>CCM,GCM</encryptionTypes>
<disableEncryption/>
<useAESProvider>SunJCE</useAESProvider>
</SMB3>
</server-core>

The <SMB2> <maxPacketSize> setting sets the maximum packet size that the server will negotiate with the client. The value can be specified as 'nM' for megabytes, or 'nK' for kilobytes or as the number of bytes. Most clients will use a value between 2 to 8 megabytes.

The <SMB2> <requireSigning/> setting forces clients to use SMB2 signing. If the client does not support SMB2 signing the session connection will be rejected.

The <SMB3> <encryptionTypes> value specifies which SMB3 encryption types are enabled, and the preferred order as a comma delimited list. The valid values are 'GCM' for AES/GCM/128 bit and 'CCM' for AES/CCM/128 bit.

The <SMB3> <disableEncryption/> setting will allow an SMB3 connection without encryption to be established with the server.

The <SMB3> <useAESProvider> setting is used to specify the name of the JCE provider that will be used by the AES/GCM/128 bit encryption mode. Using a value of 'SunJCE' will use the Sun/Oracle/OpenJDK hardware accelerated implementation. The default setting will use the BouncyCastle JCE provider which only provides a software based implementation of the AES/GCM cipher.

== FTP Server Configuration ==

The <FTP> configuration section is used to configure the FTP protocol server that allows a client to connect using any FTP client application. A standard FTP connection sends plaintext commands, and details including username and password, so it is recommended to use FTPS so that the commands are sent over an encrypted SSL connection.

The <FTP> configuration section has the following syntax :-

<FTP>
<port>...</port>
<allowAnonymous/>
<debug .../>


<keyStore>...</keyStore>
<keyStoreType>...</keyStoreType>
<keyStorePassphrase>...</keyStorePassphrase>

<requireSecureSession>
<sslEngineDebug/>
</FTP>

The <port> setting defines the port that the FTP server will listen for connections on, if not specified the default FTP port of 21 will be used. If running JFileServer file server as a normal user on a linux or Mac system you will need to use a non-privileged port, 1024 or above.

The <allowAnonymous/> setting specifies that anonymous guest logons are allowed to the FTP server.

The <debug flags="..."/> setting is used to enable FTP server debug output. The flags="..." value is a comma delimited list of debug output level names from the following list :-

{| class="wikitable"
! style="text-align:left;"| Flag
! Description
|-
| STATE
| Session state changes
|-
| RXDATA
| Dump received data packet
|-
| TXDATA
| Dump sent packet data
|-
| DUMPDATA
| Dump data packets
|-
| SEARCH
| File/directory searches
|-
| INFO
| Information requests
|-
| FILE
| File open/close/information requests
|-
| FILEIO
| File read/write requests
|-
| ERROR
| Errors sent back to the client
|-
| PKTTYPE
| Received packet type
|-
| TIMING
| Time packet processing
|-
| DATAPORT
| Data port handling
|-
| DIRECTORY
| Directory commands
|-
| SSL
| Secure sessions
|-
|}

=== FTPS Server Configuration ===

The FTP server allows connections to switch into secure SSL mode after connecting to the configured FTP server port.

To enable FTPS we need to create a keystore for the SSL connections. To create a keystore using the JKS format keystore type use the following commands, filling in the required details when prompted :-

$ keytool -genkeypair -alias jfsftp -keyalg RSA -keystore FTPSKeyStore

Enter keystore password:
Re-enter new password:
What is your first and last name?
[Unknown]: Your Name
What is the name of your organizational unit?
[Unknown]: OrgUnit
What is the name of your organization?
[Unknown]: Company
What is the name of your City or Locality?
[Unknown]: City
What is the name of your State or Province?
[Unknown]: Province
What is the two-letter country code for this unit?
[Unknown]: CC
Is CN=You Name, OU=OrgUnit, O=Company, L=City, ST=Province, C=CC correct?
[no]:yes

Enter key password for <client>
(RETURN if same as keystore password):
Re-enter new password:

You can now fill in the JFileServer configuration to enable FTPS :-


<keyStore>/path/to/FTPSKeyStore</keyStore>
<keyStoreType>JKS</keyStoreType>
<keyStorePassphrase>keystore-password</keyStorePassphrase>

The <requireSecureSession/> configuration setting will only allow connections that use the FTP SSL mode to logon.

The <sslEngineDebug/> setting is used to enable additional debug output from the Java JSSE SSL session processing.

== NFS Server Configuration ==

The <NFS> configuration section is used to configure the NFS protocol server that allows a client to mount a JFileServer filesystem which can then be accessed as if it were on a local drive on the client system.

The <NFS> configuration section has the following syntax :-

<NFS>
<enablePortMapper/>
<disablePortMapperRegistration/>
<PortMapperPort>...</PortMapperPort>
<MountServerPort>...</MountServerPort>
<NFSServerPort>...</NFSServerPort>
<RPCRegisterPort>...</RPCRegisterPort>
<rpcAuthenticator>
...
</rpcAuthenticator>
<debug .../>
<mountServerDebug/>
<portMapperDebug/>
<FileCache>...</FileCache>
<fileCacheDebug/>
</NFS>

'''TODO:''' NFS configuration settings

== Shares Configuration ==

The <shares> configuration section is used to define the virtual filesystems that are available to the various protocol servers.

A virtual filesystem requires a ''driver'' class that implements the core filesystem interface, plus optional interfaces for advanced features.

The <shares> configuration section has the following syntax :-

<shares>
<diskshare name="..." comment="...">
<driver>
<class>...</class>
...
</driver>
</diskshare>

<diskshare name-"..." comment="...">
...
</diskshare>
...
</shares>

Multiple virtual filesystems can be defined each using a seperate <diskshare> configuration section. The virtual filesystems can use different driver classes. Each driver class can have its own set of configuration items. Each <diskshare> definition must have a unique name, and can have an optional comment.

There are a number of virtual filesystems included in the JFileServer jar file. The ''org.filesys.smb.server.disk.JavaNIODiskDriver'' virtual filesystem uses the Java I/O classes to create a network filesystem that is mapped to a folder on the local filesystem.

=== JavaNIODiskDriver Configuration ===

The <driver> configuration section for the ''org.filesys.smb.server.disk.JavaNIODiskDriver'' virtual filesystem has the following syntax :-

<driver>

<class>org.filesys.smb.server.disk.JavaNIODiskDriver</class>
<LocalPath>...</LocalPath>


<LargeFileSize>...</LargeFileSize>
<TrashcanPath>...</TrashcanPath>
<Debug/>
</driver>

The <LocalPath> setting specifies the local path of the folder to be shared, the folder must exist. The path may be an absolute path or a relative path, for example a path of ''./''.

The <LargeFileSize> setting specifies the file size where file delete and truncate operations are performed using a background thread to help with server response. The file size can be specified as bytes, or ''nK'' for kilobytes, ''nM'' for megabytes, ''nG'' for gigabytes.

The <TrashCanPath> setting specifies the folder to be used for background delete of large files. The path must be on the same physical volume as the folder specified by <LocalPath> as files are renamed into the trashcan folder where they will then be deleted via a background thread.

The <Debug/> setting enables debug output for this instance of the virtual filesystem driver.

== Debug Configuration ==

The <debug> configuration section is used to define how debug output is handled and where it is sent to. The <debug> configuration section has the following syntax :-

<debug>
<output type="Console|File|JDK">
<class>...</class>
...
</output>
</debug>

The following pre-defined debug output types are available for the ''type="..."'' value :-
* Console Output to the console
* File Output to the file defined by the <logfile>...</logfile> parameter. An optional <append/> parameter can be specified to append to an existing log file.
* JDK Use Java JDK logging, use the <Properties>...</Properties> parameter to specify the location of the logging properties file.

It is also possible to provide your own custom debug output class by implementing the ''org.filesys.debug.DebugInterface'' interface. You would then use the <class>...</class> setting to specify the debug class, and not use the ''type="..."'' setting. Any parameters defined within the <output> section will be passed to the debug interface implementation ''initialize()'' method.

== Security Configuration ==

The <security> configuration section is used to define the JCE provider for the file server and to define server users when using local authentication.

The <security> configuration section has the following syntax :-

<security>
<JCEProvider>...</JCEProvider>

<users>
<user name="...">
<password>...</password>

<md4>...</md4>


<administrator/>
<comment>...</comment>
<realname>...</realname>
<home>...</home>
</user>
</users>
</security>

The <JCEProvider> setting specifies the class that provides standard encryption support that the file server requires. The default setting is to use the BouncyCastle JCE provider library via the class ''org.bouncycastle.jce.provider.BouncyCastleProvider''.

The <users> section defines local user accounts on the file server when local authentication is being used. If you are using Kerberos authentication the list of users will be ignored.

The <user> section defines a local user, the ''name="..."'' value is required and must be unique within the list of user names. The <password>...<password> setting species the user password in plaintext or you can specify the password using the MD4 value via a hex-ASCII value.

The optional <home>...</home> setting specifies the local path of the users home folder.

== Licence Configuration ==

To use the JFileServer Enterprise features a licence is required, this is configured via the <licence> configuration section.

The <licence> configuration section has the following syntax :-

<licence>

<licenceKey>...</licenceKey>


<licencePath>...</licencePath>
</licence>

To specify a licence key that is embedded within the server configuration file use the <licenceKey>...</licenceKey> configuration section, the licence key text can be split onto multiple lines.

To specify a licence key that is in an external file use the <licencePath>.../<licencePath> configuration section with the full path to the licence file.

Configuring Kerberos/AD Authentication For The SMB Server

2024-11-02T14:07:29Z

Tommygonk:

By default the JFileServer SMB server uses NTLM authentication, for more secure and single signon authentication you can configure the SMB server to use Kerberos logons.

This document details how to configure the JFileServer, and JFileServer Enterprise, SMB server to use Kerberos authentication using a Windows Active Directory (AD) server setup.

== Setting Up The File Server User Account ==
The JFileServer SMB server requires an AD user account to map a service principal name to that the client will request when accessing the SMB server.

Create a user account on the AD server, fill in the user logon name eg. ''jfileserver'', disable the 'User must change password at next logon' option, and enable the 'Password never expires' option. Set a password for the new account.

The user account can be configured with the 'Do not require Kerberos pre-authentication' option, or you can use pre-authentication. If pre-authentication is required you will need to specify the AD account password in the JFileServer ''<authenticator>'' configuration section using the ''<Password>...</Password>'' setting.

If there are options for AES 128 bit and AES 256 bit encryption then enable both options.

[[File:KerberosADOptions.jpg|border]]

The file server host also requires a DNS entry with the AD server.

'''Note:''' If you are using an older Java VM that does not have the high strength encryption policy enabled then do not enable AES 256 bit encryption for the account. This may be earlier versions of Java 8 or pre Java 8 versions. If in doubt then do not enable AES 256 bit encryption. Only Windows 11 and the latest macOS clients support AES 256 encryption, and JFileServer does not currently support or negotiate AES 256, it will negotiate to use AES 128 only.

== Generate The Keytab and Service Principal Name ==
Generate a key table for the file server using the ''ktpass'' command.

ktpass -princ cifs/<file-server-host-name>.<domain>@<REALM>
-pass <file-server-account-password>
-mapuser <domain>\<file-server-account-name>
-crypto ALL
-ptype KRB5_NT_PRINCIPAL
-out <output-file-name>
-kvno 0

If you only want to use a particular encryption type then use ''-crypto AES128-SHA1'' or ''-crypto AES256-SHA1''. The older encryption setting of ''-crypto RC4-HMAC-NT'' can be used but may not allow some newer clients to access the file server.

The generated key table will be used by the SMB server to authenticate the server so it will then be able to authenticate the client logons.

Copy the key table to the file server host system.

Create the service principal name mapping, that clients will use to connect to the SMB file server service, using the ''setspn'' utility. Newer versions of the ''ktpass'' command will set the SPN when generating the key table.

To check if the SPN is set use

setspn -Q cifs/<file-server-host-name>.<domain>

If the SPN has not been set then use the following commands to set the SPNs

setspn cifs/<file-server-host-name> <file-server-account-name>
setspn cifs/<file-server-host-name>.<domain> <file-server-account-name>

== Configure Kerberos On The File Server ==
The Java authentication APIs require a Kerberos configuration file, this can either be in the default location such as ''/etc/krb5.conf'' on linux and macOS, ''C:\winnt\krb5.ini'' on Windows, the location can be specified on the Java command line using the ''java.security.krb5.conf'' property, or using the JFileServer configuration value <KerberosConfig> to specify the configuration file path and name.

A sample Kerberos configuration file is shown below, the Kerberos realm is always specified in uppercase.

[libdefaults]
default_realm = FILESYS.ORG

[realms]
FILESYS.ORG = {
kdc = adsrv.filesys.org
admin_server = adsrv.filesys.org
}

[domain-realm]
adsrv.filesys.org = FILESYS.ORG
.adsrv.filesys.org = FILESYS.ORG

== Setup The Java Login Configuration ==
The Java login configuration is used by the file server application to logon the server application using Kerberos by using the details in the key table that was generated on the Windows AD server.

The Java login configuration file can be stored in your user home folder or a system folder such as ''/etc''. Create a new file called ''jfileserver.login.conf''. The default Java login configuration section name is ''FileServerSMB''. A sample Java login configuration file is shown below :-

FileServerSMB {
com.sun.security.auth.module.Krb5LoginModule required
debug=false
storeKey=true
useKeyTab=true
keyTab="<path-to-the-key-table-file>"
principal="cifs/<file-server-host-name>.<domain>";
};

Note: Use spaces in the Java login configuration file, tab characters cause problems.

To enable the Java login configuration use the JFileServer configuration value <LoginConfig> to specify the path to the login configuration file.

You can also set the login configuration file by updating the main Java security configuration file. This is usually located in the ''<JRE-folder>/lib/security/java.security'' file.

Look for the example configuration line that starts with ''#java.login.config.url.1=...''. Uncomment the line, or add a new line, similar to the value shown:-

java.login.config.url.1=<path-to-the-java-login-configuration-file>

== Configure The JFileServer SMB Authentication ==
In the JFileServer XML configuration file enable the SMB server Kerberos authentication via the <authenticator> configuration section within the <fileserver> <SMB> section of the configuration. A minimal sample configuration section is shown below:-

<fileserver>
...
<SMB>
...

<authenticator type="enterprise">

<Realm>FILESYS.ORG</Realm>
</authenticator>
</SMB>
...
</fileserver>

The following configuration tags are available for the SMB authenticator:-

{| class="wikitable"
! style="text-align:left;"| Configuration Value
! Description
|-
| <useSPNEGO/>
| Force Simple Protected Negotiation to be used for the authentication, this will be selected automatically if Kerberos authentication is enabled. If only NTLM authentication is enabled the default is to use NTLMSSP in the authentication exchanges.
|-
| <mode>...</mode>
| Server mode, should always be 'USER'
|-
| <Realm>...</Realm>
| Kerberos realm, always uppercase
|-
| <LoginEntry>...</LoginEntry>
| Specifies the Java login configuration entry name if the default name of 'FileServerSMB' is not used
|-
| <Password>...</Password>
| Kerberos file server account password. Not required
|-
| <disallowNTLMv1/>
| Do not allow the weaker NTLM v1 logons, only NTLM v2 logons will be accepted
|-
| <disableNTLM/>
| Only allow Kerberos authentication. NTLM authentication will not be advertised by the server or accepted
|-
| <Debug/>
| Enable authentication debug output
|-
| <kerberosDebug/>
| Enables the Java authentication API debug output. Equivalent of setting the Java system properties 'sun.security.jgss.debug' and 'sun.security.krb5.debug'
|-
| <KerberosConfig>...</KerberosConfig>
| Specifies the location and name of the Kerberos configuration file
|-
| <LoginConfig>...</LoginConfig>
| Specifies the location and name of the Java login configuration file
|-
|}

Adding Client API Support To A Filesystem

2024-10-02T14:41:57Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

The ''RunActionResponse'' class has many convenience methods to set the various sections of the response :-

{| class="wikitable"
! style="text-align:left; width: 40%;"| Method
! Description
|-
| setSuccess()
| If the server action only needs to indicate it ran successfully then this method will set the status to indicate success and the client action to ''NoAction''.
|-
| setError(String)
| Return an error to the client with the specified error message to be displayed on the client. There is also the ''RunActionResponse.createErrorResponse(String) method that will create a ''RunActionResponse'' object with the specified error message.
|-
| setRefreshOriginal(boolean)
| Indicates if the client should refresh the original path(s) file details in File Explorer views.
|-
| setClientAction(ServerAction.ClientAction,List<String>) setClientAction(ServerAction.ClientAction,String)
| Set a client action with the specified parameter string(s).
|-
| setOpenURL(String)
| Set a client action to open the specified URL on the client.
|-
| setMessage(String msg) setMessage(String title,String msg) setMessage(String title, String msg, ServerAction.MessageLevel)
| Set a client message to be displayed in a message box dialog on the client. If the ''ServerAction.MessageLevel'' is not specified the message will be shown with an informational level.
|-
| setWarningMessage(String msg) setWarningMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with a warning level.
|-
| setErrorMessage(String msg) setErrorMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with an error level.
|-
| setExecute(String operation, String app) setExecute(String operation, String app, String param)
| Set an application to be run on the client, using the Windows ShellExecute() API call.
|-
| setUpdatePaths(List<String>) setCreatedPaths(List<String>) setDeletedPaths(List<String>)
| Set a list of paths that were updated, created or deleted by the server action.
|-
| setNotification(String msg) setNotification(String title, String msg)
| Set the notification to be displayed on the client. If the notification title is not specified the client application name will be used.
|-
|}

=== Client API Implementation ===
For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:41:30Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

The ''RunActionResponse'' class has many convenience methods to set the various sections of the response :-

{| class="wikitable"
! style="text-align:left; width: 40%;"| Method
! Description
|-
| setSuccess()
| If the server action only needs to indicate it ran successfully then this method will set the status to indicate success and the client action to ''NoAction''.
|-
| setError(String)
| Return an error to the client with the specified error message to be displayed on the client. There is also the ''RunActionResponse.createErrorResponse(String) method that will create a ''RunActionResponse'' object with the specified error message.
|-
| setRefreshOriginal(boolean)
| Indicates if the client should refresh the original path(s) file details in File Explorer views.
|-
| setClientAction(ServerAction.ClientAction,List<String>) setClientAction(ServerAction.ClientAction,String)
| Set a client action with the specified parameter string(s).
|-
| setOpenURL(String)
| Set a client action to open the specified URL on the client.
|-
| setMessage(String msg) setMessage(String title,String msg) setMessage(String title, String msg, ServerAction.MessageLevel)
| Set a client message to be displayed in a message box dialog on the client. If the ''ServerAction.MessageLevel'' is not specified the message will be shown with an informational level.
|-
| setWarningMessage(String msg) setWarningMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with a warning level.
|-
| setErrorMessage(String msg) setErrorMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with an error level.
|-
| setExecute(String operation, String app) setExecute(String operation, String app, String param)
| Set an application to be run on the client, using the Windows ShellExecute() API call.
|-
| setUpdatePaths(List<String>) setCreatedPaths(List<String>) setDeletedPaths(List<String>)
| Set a list of paths that were updated, created or deleted by the server action.
|-
| setNotification(String msg) setNotification(String title, String msg)
| Set the notification to be displayed on the client. If the notification title is not specified the client application name will be used.
|-
|}

==== Client API Implementation ====
For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:37:05Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

The ''RunActionResponse'' class has many convenience methods to set the various sections of the response :-

{| class="wikitable"
! style="text-align:left; width: 40%;"| Method
! Description
|-
| setSuccess()
| If the server action only needs to indicate it ran successfully then this method will set the status to indicate success and the client action to ''NoAction''.
|-
| setError(String)
| Return an error to the client with the specified error message to be displayed on the client. There is also the ''RunActionResponse.createErrorResponse(String) method that will create a ''RunActionResponse'' object with the specified error message.
|-
| setRefreshOriginal(boolean)
| Indicates if the client should refresh the original path(s) file details in File Explorer views.
|-
| setClientAction(ServerAction.ClientAction,List<String>) setClientAction(ServerAction.ClientAction,String)
| Set a client action with the specified parameter string(s).
|-
| setOpenURL(String)
| Set a client action to open the specified URL on the client.
|-
| setMessage(String msg) setMessage(String title,String msg) setMessage(String title, String msg, ServerAction.MessageLevel)
| Set a client message to be displayed in a message box dialog on the client. If the ''ServerAction.MessageLevel'' is not specified the message will be shown with an informational level.
|-
| setWarningMessage(String msg) setWarningMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with a warning level.
|-
| setErrorMessage(String msg) setErrorMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with an error level.
|-
| setExecute(String operation, String app) setExecute(String operation, String app, String param)
| Set an application to be run on the client, using the Windows ShellExecute() API call.
|-
| setUpdatePaths(List<String>) setCreatedPaths(List<String>) setDeletedPaths(List<String>)
| Set a list of paths that were updated, created or deleted by the server action.
|-
| setNotification(String msg) setNotification(String title, String msg)
| Set the notification to be displayed on the client. If the notification title is not specified the client application name will be used.
|-
|}

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:36:37Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

The ''RunActionResponse'' class has many convenience methods to set the various sections of the response :-

{| class="wikitable"
! style="text-align:left; width: 40%;"| Method
! Description
|-
| setSuccess()
| If the server action only needs to indicate it ran successfully then this method will set the status to indicate success and the client action to ''NoAction''.
|-
| setError(String)
| Return an error to the client with the specified error message to be displayed on the client. There is also the ''RunActionResponse.createErrorResponse(String) method that will create a ''RunActionResponse'' object with the specified error message.
|-
| setRefreshOriginal(boolean)
| Indicates if the client should refresh the original path(s) file details in File Explorer views.
|-
| setClientAction(ServerAction.ClientAction,List<String>) setClientAction(ServerAction.ClientAction,String)
| Set a client action with the specified parameter string(s).
|-
| setOpenURL(String)
| Set a client action to open the specified URL on the client.
|-
| setMessage(String msg) setMessage(String title,String msg) setMessage(String title, String msg, ServerAction.MessageLevel)
| Set a client message to be displayed in a message box dialog on the client. If the ''ServerAction.MessageLevel'' is not specified the message will be shown with an informational level.
|-
| setWarningMessage(String msg) setWarningMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with a warning level.
|-
| setErrorMessage(String msg) setErrorMessage(String title,String msg)
| Set a client message to be displayed in a message box dialog on the client with an error level.
|-
| setExecute(String operation, String app) setExecute(String operation, String app, String param)
| Set an application to be run on the client, using the Windows ShellExecute() API call.
|-
| setUpdatePaths(List<String) setCreatedPaths(List<String>) setDeletedPaths(List<String>)
| Set a list of paths that were updated, created or deleted by the server action.
|-
| setNotification(String msg) setNotification(String title, String msg)
| Set the notification to be displayed on the client. If the notification title is not specified the client application name will be used.
|-
|}

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:30:38Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

The ''RunActionResponse'' class has many convenience methods to set the various sections of the response :-

{| class="wikitable"
! style="text-align:left; width: 40%;"| Method
! Description
|-
| setSuccess()
| If the server action only needs to indicate it ran successfully then this method will set the status to indicate success and the client action to ''NoAction''.
|-
| setError(String)
| Return an error to the client with the specified error message to be displayed on the client. There is also the ''RunActionResponse.createErrorResponse(String) method that will create a ''RunActionResponse'' object with the specified error message.
|-
| setRefreshOriginal(boolean)
| Indicates if the client should refresh the original path(s) file details in File Explorer views.
|-
| setClientAction(ServerAction.ClientAction,List<String>) setClientAction(ServerAction.ClientAction,String)
| Set a client action with the specified parameter string(s).
|-
| setOpenURL(String)
| Set a client action to open the specified URL on the client.
|-
| setMessage(String msg) setMessage(String title,String msg) setMessage(String title, String msg, ServerAction.MessageLevel)
| Set a client message to be displayed in a message box dialog on the client. If the ''ServerAction.MessageLevel'' is not specified the message will be shown with an informational level.
|-
|
|
|-
|
|
|-
|
|
|-
|
|
|-
|
|
|-
|
|
|-
|
|
|-
|
|
|-
|}

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:16:45Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

<div id="ClientUIAction"></div>
A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action uses the same ''ClientUIAction'' class that is used when defining a ''ServerAction'', as documented [[#ClientUIAction|here]]
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T14:02:13Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

=== Implementing ServerAction runAction() ===
When the user selects an action on the client API sub-menu, the client will show the user interface item if the action has the optional ''UIAction'' configured, then if the action is not cancelled by the user or there is no user interface item to be displayed the request to run the action is sent to the server.

To run the action on the server the client will write a ''RunActionRequest'' object, in JSON format, to the client API file. The ''RunActionRequest'' contains the action name, the list of the selected files/folder paths and an optional list of parameter values. The ''JSONClientAPI.processRequest()'' method will be triggered that will pass the ''RunActionRequest'' object to the ''processRunAction()'' method which must be implemented in your own client API implementation. The default implementation of ''processRunAction()'' in the ''JSONClientAPI'' class will return a ''Not Implemented'' error to the client.

In your ''processRunAction()'' method you need to map the action name to the corresponding ''ServerAction'' object, then call the ''runAction()'' method with the ''RunActionRequest'' object and the ''ClientAPINetworkFile'' object. The ''runAction()'' method should either return a ''RunActionResponse'' object, or other object that extends the ''ClientAPIResponse'' class, or throw a ''ClientAPIException''.

==== RunActionResponse ====
The ''RunActionResponse'' object holds the response details that are sent back to the client that indicate if the server action was successful and has various optional actions that the client can be instructed to do with a list of associated parameters, an optional user interface action such as displaying a message box dialog on the client, an optional notification to be displayed on the client, and a flag to indicate if the original selected files/folder details should be refreshed on the client.

The available client actions are listed below, from the ServerAction.ClientAction enum class :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Action
! Description
|-
| NoAction
| No action required on the client.
|-
| OpenURL
| Open a URL on the client, the URL value is the first parameter value.
|-
| OpenApplication
| Open an application on the client. The parameter values contain the operation name, application name and an optional parameter for the application. The application will be launched using the Windows ShellExceute() API call.
|-
| UIAction
| Indicates a user interface action on the client. The details of the user interface action are in the
|-
| UpdatedPaths
| The parameter list contains a list of paths that have been updated by the server action, the client will refresh File Explorer views for the updated paths.
|-
| NewPaths
| The parameter list contains a list of the paths that have been created by the server action, the client will refresh File Explorer views for the updated paths.
|-
| DeletePaths
| The parameter list contains a list of the paths that have been deleted by the server action, the client will refresh File Explorer views for the updated paths.
|-
|}

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T13:28:20Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

For a more complete client API implementation see the fileServersNG source code :-
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/AlfrescoClientApi.java AlfrescoClientAPI] Extends the JSONClientAPI base class, adds check in/out and open in Share server actions plus ability to run scripted actions written in Javascript.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckOutServerAction.java Check Out Server Action] Check out files from an Alfresco repository, refresh the original file details, refresh the File Explorer via to show newly created working copy files, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/CheckInServerAction.java Check In Server Action] Check working copy files in to an Alfresco repository, or cancel the check out of the files, remove the working copies from File Explorer views, update the original file details, display a notification on the client.
* [https://github.com/FileSysOrg/fileServersNG/blob/main/src/main/java/org/filesys/alfresco/repo/clientapi/OpenInShareServerAction.java Open In Share Server Action] Returns a URL for the selected file/folder for the client to open a web browser showing the file/folder in the Share web application.

Adding Client API Support To A Filesystem

2024-10-02T11:03:14Z

Tommygonk:

The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface allows a client to send requests to the file server over existing protocols, currently SMB2 and SMB3 protocols are supported. A filesystem must implement the core ''DiskInterface'', and can then add other functionality using optional interfaces such as to implement file locking, or in this case the client API interface.

The client API uses a special path on the server that the client can write a request into, and receives the response from the server. The special path is not visible in folder listings. The main implementation uses JSON format to send a request and for the response, but you can implement your own format of request and response by implementing the lower level ''ClientAPIInterface'', rather than extending the ''JSONClientAPI'' implementation.

The JSON client API has a client side application, currently for Windows 10 and 11, that provides a right click context menu into the Windows File Explorer application, with a configurable set of sub-menus that trigger server side actions. The client side application is also able to display message boxes and other user interface items before and after an action has run, show notifications, run applications and open URLs all under control of the server side actions.

The fileServersNG Alfresco add-on module contains a reference implementation of a client API, extending the ''JSONClientAPI''. There is a Wiki document that describes the fileServersNG client API implementation [[File Explorer Menu for Alfresco|here]], and the source code for the fileServersNG implementation is [https://github.com/FileSysOrg/fileServersNG/tree/main/src/main/java/org/filesys/alfresco/repo/clientapi here].

This document describes how to implement a client API by extending the ''JSONClientAPI'' implementation.

== Filesystem Requirements ==
To enable client API support a filesystem must implement the optional ''org.filesys.server.filesys.clientapi.ClientAPI'' interface, with a client API implementation class that either implements the base ''org.filesys.server.filesys.clientapi.ClientAPIInterface'' interface or extends the ''org.filesys.server.filesys.clientapi.json.JSONClientAPI'' abstract class.

The source code for the client API interfaces and classes is available [https://github.com/FileSysOrg/jfileserver/tree/master/src/main/java/org/filesys/server/filesys/clientapi here].

The ''ClientAPI'' interface has two methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public boolean isClientAPIEnabled()
| Returns ''true'' is the client API is enabled for this filesystem, else ''false''
|-
| public ClientAPIInterface getClientAPI(SrvSession<?> sess, TreeConnection tree)
| Returns the ''ClientAPI'' implementation that handles the requests from the client
|-
|}

The base ''ClientAPIInterface'' interface has the following methods :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left;"|Description
|-
| public String getClientAPIPath()
| Returns the special path that the client will write requests and receive responses via. The path should be a path that is relative to the root of the filesystem, for the ''JSONClientAPI'' implementation the special path is ''\__JSONAPI__''
|-
| public ClientAPINetworkFile openClientAPIFile(SrvSession<?> sess, TreeConnection tree, FileOpenParams params)
| Returns a special in-memory file that represents a file open to the special client API path. The in-memory file is created per file open, it is not shared between users or sessions
|-
| public void processRequest( ClientAPINetworkFile netFile)
| Process a client request received via the specified client API file. The request data can be retrieved using the ''byte[] netFile.getRequestData()'' method. The response is written to the client API file using the ''setResponseData( byte[])'' method.
|-
|}

The ''JSONClientAPI'' implementation handles all of the ''ClientAPIInterface'' methods, and adds the following methods that must be implemented or can be overridden :-

{| class="wikitable"
! style="text-align:left; vertical-align:top; width:40%;"|Method
! style="text-align:left; vertical-align:top;"|Description
|-
| public EnumSet<ApiRequest> getSupportedRequests()
| Returns the set of API requests that this implementation supports. The APIRequest enum has the values ''GetAPIInfo'', ''GetURLForPath'', ''GetPathStatus'' and ''RunAction''. This method must be implemented.
|-
| public String getClientAPIVersion()
| Return the client API version in ''n.n.n.n'' format. This method must be implemented.
|-
| public ContextMenu getContextMenu()
| Return the context menu details with the top level menu title and icon, plus the list of server actions that will be displayed on a sub-menu of the client context menu. This method must be implemented.
|-
| protected void preProcessRequest( ClientAPINetworkFile netFile, ClientAPIRequest req)
| Optional method that can be overridden to handle a client request before the main request handler processes the request.
|-
| public ClientAPIResponse processGetURLForPath( GetURLForPathRequest req)
| Optional method that should be overridden if the client API ''GetURLForPath'' API request is supported. The ''GetURLForPathRequest'' object contains the relative path of the file or folder that was selected on the client.
|-
| public ClientAPIResponse processGetPathStatus( GetPathStatusRequest req)
| Optional method that should be overridden if the client API ''GetPathStatus'' API request is supported. The ''GetPathStatusRequest'' object contains a list of the relative paths that were selected on the client and a check type value for the path status to be checked.
|-
| public ClientAPIResponse processRunAction( RunActionRequest req, ClientAPINetworkFile netFile)
| This method handles processes running a server side action associated with a context menu. The ''RunActionRequest'' object contains the action name, a list of one or more relative paths that were selected on the client and an optional list of parameter values.
|-
|
|
|-
|}

=== Implementing getSupportedRequests() ===

The ''JSONClientAPI'' implements a ''GetAPIInfo'' request that is used by the client to probe that the network drive supports the client API, and returns information about the API including the context menu title, description and icon details plus the sub-menu details that includes details of each server action.

Here is a sample context menu from the fileServersNG client API implementation :-

[[File:ContextMenu.png|400px|border]]

In the fileServersNG context menu example the context menu title is ''Alfresco Drive'' with a custom icon. The sub-menu contains the list of server actions such as ''Check In'' and ''Check Out''.

Each server action on the sub-menu has an action name, description, details about the file and/or folder selections the action accepts, an optional user interface action to be run before the action request is sent to the server and an optional icon definition.

As the ''JSONClientAPI'' implements the ''GetAPIInfo'' request, that must be included in the supported requests list. The ''RunAction'' API request should be included if you want to handle custom actions in your API implementation. A sample implementation of the getSupportedRequests() method :-

<pre style="font-size:80%;">
public EnumSet<ApiRequest> getSupportedRequests() {
return EnumSet.of ( ApiRequest.GetApiInfo, ApiRequest.RunAction);
}
</pre>

=== Implementing getClientAPIVersion() ===

The ''getClientAPIVersion()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method should return a version string with the format ''<major>.<minor>.<patch>''.

A sample implementation of the ''getClientAPIVersion()'' method :-

<pre style="font-size:80%;">
public String getClientAPIVersion() {
return "1.0.0";
}
</pre>

=== Implementing getContextMenu() ===

The ''getContextMenu()'' method is called by the ''GetAPIInfo'' request processing when collecting details about the client API implementation. The method returns a ''ContextMenu'' object that defines the top level context menu and the server actions used for the sub-menu.

A ''ContextMenu'' object is created using the constructor ''ContextMenu(String title, String description, ActionIcon icon)'' where ''title'' is the menu title that will be shown on the File Explorer right click context menu, ''description'' may be used as a tooltip, and ''icon'' defines the icon to be displayed for the context menu.

The ''ContextMenu'' needs a list of ''ServerAction'' objects to be attached using the ''setActions( List<ServerAction>)'' method, this defines the items that will be shown on the sub-menu of the context menu.

==== ActionIcon ====
The ''ActionIcon'' class defines an icon on the client. The icon may be included in the client API context menu DLL, in the Windows shell32.dll system file or you can define a custom icon from another Windows system DLL.

There are convenience methods on the ''ActionIcon'' class for creating the different types of icon. To define an icon that is contained in the client API context menu DLL use the ''ActionIcon.createAppIcon(int)'' method, to define an icon that is contained in the Windows shell32.dll system file use the ''ActionIcon.createShellIcon(int)'' method, and to create a custom icon use the ''ActionIcon.createCustomIcon(int, String)''. For a custom icon the values are the index of the icon (should be a negative number) and the name of the Windows system file that contains the icon (without any path).

An ''ActionIcon'' can also be created using a name, using the ''ActionIcon.createByName(String)'' method, this is useful if the context menu is defined a configuration file.

The table below lists the available ActionIcon types, ids and names. Id types are ''ActionIcon.IconType'' enum values :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Type
! Id
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Shell
| ActionIcon.SHELLICON_SCRIPT
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Shell
| ActionIcon.SHELLICON_WEBBROWSER
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Shell
| ActionIcon.SHELLICON_FOLDER
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Shell
| ActionIcon.SHELLICON_PRINTER
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Shell
| ActionIcon.SHELLICON_MAGNIFY
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Shell
| ActionIcon.SHELLICON_STAR
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Shell
| ActionIcon.SHELLICON_LOCK
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Shell
| ActionIcon.SHELLICON_MOVIE
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Shell
| ActionIcon.SHELLICON_AUDIO
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Shell
| ActionIcon.SHELLICON_CAMERA
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Shell
| ActionIcon.SHELLICON_INFORMATION
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Shell
| ActionIcon.SHELLICON_HOME
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Shell
| ActionIcon.SHELLICON_GEAR
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| App
| ActionIcon.APPICON_FILESYSORG_ALFRESCO
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| App
| ActionIcon.APPICON_FILESYSORG
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| App
| ActionIcon.APPICON_ALFRESCO_CHECKIN
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| App
| ActionIcon.APPICON_ALFRESCO_CHECKOUT
| Alfresco check out icon
|-
|}

==== ServerAction ====

The ''ServerAction'' class defines a server-side action that will be displayed on the client context menu sub-menu, this includes details of the menu name, description and icon plus details of what type of file/folder selections the action accepts, and an optional user interface action for the client to run before sending the action request to the server, such as displaying an acknowledgement message dialog with Ok/Cancel buttons.

To create a server-side action you must extend the ''ServerAction'' class. The ''ServerAction'' class requires an action name, that will be used as the menu title, a description and a set of flags that define what combination of file/folder selections the action accepts. The ''ServerAction.Flags'' enum class defines the available flags, which are also defined below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| Flag
! Description
|-
| Files
| Action accepts file selections
|-
| Folders
| Action accepts folder selections
|-
| MultiSelect
| Action accepts multiple file and/or folder selections
|-
|}

For example, a flags value of ''EnumSet.of( Flags.Files)'' would indicate the action only accepts a single file selection. If multiple files are selected on the client, or a folder is selected, the server action sub-menu will be greyed out and not selectable by the user. A flags value of ''EnumSet.of( Flags.Files, Flags.MultiSelect)'' would indicate the action accepts file selections with one or more files selected.

A ''ServerAction'' can have an optional icon defined, using the same ''ActionIcon'' class that the top level context menu uses. Set the icon using the appropriate ''ServerAction'' constructor, or using the ''setIcon(ActionIcon)'' method. If no icon is defined for a server action the sub-menu item will be shown with no icon.

A ''ServerAction'' can have an optional user interface action that will instruct the client application to display a user interface item such as a message box. If the user interface item has an option to cancel such as Ok/Cancel buttons then the action will not be triggered on the server if the cancel option is selected by the user.

A user interface action is configured for a server action using the ''setUIAction(ClientUIAction)'' method. The ''ClientUIAction'' has the type of user interface item to be displayed with an optional title, message text and the message severity for message box dialogs. The available ''ClientUIAction.UIAction'' types are shown below :-

{| class="wikitable"
! style="text-align:left; width: 10%;"| UIAction
! Description
|-
| MessageDialog
| Display a message box dialog with an ''Ok'' button.
|-
| YesNoDialog
| Display a message box dialog with ''Yes'' and ''No'' buttons. If the ''No'' button is selected by the user the action will not be run.
|-
| OkCancelDialog
| Display a message box dialog with ''Ok'' and ''Cancel'' buttons. If the ''Cancel'' button is selected by the user the action will not be run.
|-
| CheckInDialog
| Displays a custom dialog that lists the selected file(s) with a comment input field and buttons ''Check In'', ''Undo Checkout'' and ''Cancel''.
 An example of the check in dialog :-
 [[File:CheckInDialog.png|250px|border]]
 If the ''Check In'' button is selected the action is run with the request parameters containing a value of ''checkin'', if the ''Undo Checkout'' button is selected the action is run with the request parameters containing a value of ''cancel''. Selecting the ''Cancel'' button will not run the server action.
|}

If the title is not set for a ''ClientUIAction'' the client application name will be used.

For the message box dialog user interface actions a message level can be specified to indicate whether the message is an informational, warning or error message. The message box dialog will show a different icon depending on the message level. The available values are defined in the ''ServerAction.MessageLevel'' enum class, with values of ''Info'', ''Warn'' and ''Error''.

Here is example source code of how to create a simple ''ContextMenu'' :-

<pre style="font-size:80%;">
public class MyServerAction extends ServerAction {
public MyServerAction() {
super("Server Action", "A sample server action", EnumSet.of( Flags.Files));

setIcon( ActionIcon.createShellIcon( ActionIcon.SHELLICON_INFORMATION);
setUIAction( new ClientUIAction( UIAction.YesNoDialog, "Run MyServerAction",
"Run the example server action ?");
}

public ClientAPIResponse runAction(RunActionRequest req, ClientAPINetworkFile netFile)
throws ClientAPIException {
..
..
}
}

public ContextMenu getContextMenu() {
ContextMenu ctxMenu = new ContextMenu( "JFileServer Actions", "Sample API context menu",
ActionIcon.createAppIcon( ActionIcon.APPICON_FILESYSORG));

List<ServerAction> actions = new ArrayList<ServerAction>();
actions.add( new MyServerAction());

ctxMenu.addActions( actions);

return ctxMenu;
}
</pre>

Adding Client API Support To A Filesystem

2024-10-02T10:41:39Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-02T10:36:49Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-02T10:32:36Z

Tommygonk:

File:CheckInDialog.png

2024-10-02T10:30:39Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-02T10:30:12Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-02T09:35:02Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-02T08:04:27Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:27:01Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:23:28Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:20:21Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:18:02Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:12:22Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T16:07:22Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T15:55:39Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T15:04:28Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:48:32Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:35:29Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:31:58Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:29:38Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:24:35Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:18:50Z

Tommygonk:

Adding Client API Support To A Filesystem

2024-10-01T14:17:06Z

Tommygonk: Created page with "The client API feature was added in the JFileServer 1.4.0/JFileServer Enterprise 1.3.0 release, as an optional interface a filesystem can implement. The client API interface a..."

Welcome to the Filesys.org Wiki

2024-10-01T13:42:52Z

Tommygonk: /* JFileServer */

Here you will find articles, how-to's and other documentation for the JFileServer file server, JFileServer Enterprise add-on and fileServersNG replacement Alfresco file servers subsystem.

== JFileServer ==
* [[How to convert a JLAN filesystem]]
* [[Configuring JFileServer]]
* [[Using JFileServer From The Command Line]]
* [[Using the JFileServer Docker Images]]
* [[Configuring Kerberos/AD Authentication For The SMB Server]]
* [[Using filesystem access controls]]
* [[Adding Client API Support To A Filesystem]]

== JFileServer Enterprise ==
* [[Using JFileServer Enterprise From The Command Line]]
* [[Using the JFileServer Enterprise Docker Image]]

== fileServersNG ==
* [[How to build and deploy the fileServersNG subsystem]]
* [[Using the fileServersNG Docker Images]]
* [[Configuring Kerberos/AD Authentication For The fileServersNG SMB Server]]
* [[File Explorer Menu for Alfresco]]

File Explorer Menu for Alfresco

2024-10-01T13:24:22Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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 [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix here], and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/fileserversng-24.3.amp 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| 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 :-

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T13:21:40Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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 [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix here], and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/fileserversng-24.3.amp 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| 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 :-

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T13:16:38Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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 [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix here], and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/fileserversng-24.3.amp 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T13:16:14Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

On the Alfresco Drive context menu are a number of actions, some of the actions are built in to 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 [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix here], and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/fileserversng-24.3.amp 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T10:44:11Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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, available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix here], and requires fileServersNG 24.3 or newer to be installed on the Alfresco server (fileServersNG 24.3 AMP available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/fileserversng-24.3.amp 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T10:41:13Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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, available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-10-01T10:37:44Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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, available [https://www.filesys.org/kits/fileserversng/alfresco-6.2-to-latest/FileExplorerMenu_x64_1.0.0.msix 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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 scripts that are made available on the File Explorer context menu.

The ''scripts.toml'' file has the following format :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-09-25T11:24:10Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 scripts that are made available on the File Explorer context menu.

The ''scripts.toml'' file has the following format :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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).
|-
|}

File Explorer Menu for Alfresco

2024-09-25T11:21:47Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 scripts that are made available on the File Explorer context menu.

The ''scripts.toml'' file has the following format :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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.
|-
| 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.
|-
| 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).
|-
|}

File Explorer Menu for Alfresco

2024-09-25T10:17:17Z

Tommygonk:

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.

[[File:ContextMenu.png|400px|border]]

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.

[[File:TrayIconMenu.png|200px|border]]

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.

[[File:AboutDialog.png|400px|border]]

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 :-

{| class="wikitable"
! style="text-align:left;"| 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 scripts that are made available on the File Explorer context menu.

The ''scripts.toml'' file has the following format :-

<pre>
[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]]
..
..
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 5%;"| Icon
! Name
! Description
|-
|[[File:ShellScript.png|20px]]
| ShellScript
| Script icon
|-
|[[File:ShellWebBrowser.png|20px]]
| ShellWebBrowser
| Web browser icon
|-
|[[File:ShellFolder.png|20px]]
| ShellFolder
| Folder icon
|-
|[[File:ShellPrinter.png|20px]]
| ShellPrinter
| Printer icon
|-
|[[File:ShellMagnify.png|20px]]
| ShellMagnify
| Magnifying glass icon
|-
|[[File:ShellStar.png|20px]]
| ShellStar
| Star icon
|-
|[[File:ShellLock.png|20px]]
| ShellLock
| Lock icon
|-
|[[File:ShellMovie.png|20px]]
| ShellMovie
| Movie icon
|-
|[[File:ShellAudio.png|20px]]
| ShellAudio
| Audio icon
|-
|[[File:ShellCamera.png|20px]]
| ShellCamera
| Camera icon
|-
|[[File:ShellInformation.png|20px]]
| ShellInformation
| Information icon
|-
|[[File:ShellHome.png|20px]]
| ShellHome
| Home icon
|-
|[[File:ShellGear.png|20px]]
| ShellGear
| Gear icon
|-
|[[File:FileSysOrgAlfresco.png|20px]]
| FileSysOrgAlfresco
| Filesys.org Alfresco application icon
|-
|[[File:FileSysOrg.png|20px]]
| FileSysOrg
| Filesys.org application icon
|-
|[[File:AlfrescoCheckIn.png|20px]]
| AlfrescoCheckIn
| Alfresco check in icon
|-
|[[File:AlfrescoCheckOut.png|20px]]
| AlfrescoCheckOut
| Alfresco check out icon
|-
|}

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

<pre>
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;
</pre>

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 :-

{| class="wikitable"
! style="text-align:left; width: 15%;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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 :-

{| class="wikitable"
! style="text-align:left;"| 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.
|-
|}

File:AlfrescoCheckOut.png

2024-09-25T10:08:27Z

Tommygonk:

File:AlfrescoCheckIn.png

2024-09-25T10:08:10Z

Tommygonk:

File:FileSysOrg.png

2024-09-25T10:07:59Z

Tommygonk:

File:FileSysOrgAlfresco.png

2024-09-25T10:07:45Z

Tommygonk:

File:ShellGear.png

2024-09-25T10:07:31Z

Tommygonk: