Desktop Actions

Document created by resplin Employee on Jun 6, 2015
Version 1Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com



ActionsCIFS
Please Note: This article describes configuration methods now outdated in the Alfresco version 3.2 release. For a more up to date description, refer to File Server Subsystem.

Desktop actions allow a client-side application on the Alfresco CIFS server to trigger a server-side action. The action is run in the context of the folder the application is running in. Files and/or folders may be dragged onto the client-side application, these are then passed as parameters to the server-side action.

The desktop action applications are added to a folder using pseudo files. The same application executable appears as different files that are then mapped to different actions on the server.

In order to run a desktop action you must have connected to an Alfresco CIFS server, this creates an authenticated session to the server. The desktop action is called by passing the request over the CIFS session so it is executed as the connected user.


Pre Processing


The clients-side application performs various pre-processing tasks for the action. The action indicates whether it accepts files and/or folders to be dragged onto the application. The files/folders may be in the same folder as the application, in a seperate folder on the Alfresco network drive or on a drive that is local to the client. The action indicates which combinations of files/folders are acceptable via a set of attributes.

If the action accepts files/folders that are on a drive local to the client then the files/folders will be copied to the Alfresco folder in order to be accessible to the server-side action. There is an option to only allow copying of files that match a working copy in the destination folder.

Files/folders are copied to the Alfresco folder using the Windows shell, larger transfers will display the standard progress dialog and file overwrites will display a dialog allowing the user to continue or cancel.

The client-side application can display a message to confirm if the action should be run or not.


File/Folder Parameters


Once the client-side pre-processing is completed any target files/folders that were dropped onto the application will now be on the Alfresco file server. A list of the files/folders is passed to the server-side action indicating if the file is a copy or already existed on the Alfresco server. Before calling the server-side action code the file/folder paths are converted to their NodeRef.


Server-side Action


The server-side action runs in the context of the authenticated CIFS user. The action returns a status and optional message to the client.

The action response can return a URL for the client-side application to launch a web browser, or a commandline for the client-side application to run.


Configuration


Desktop actions are configured on a per filesystem basis using the file-servers.xml (or file-servers-custom.xml) configuration file. The default file-servers.xml file contains a commented out section with a sample desktop actions configuration.

The following configuration enables the sample desktop actions (Echo, URL, CmdLine, CheckInOut, Javascript) :-

 <config evaluator='string-compare' condition='Filesystems'>
   <filesystems>
     <filesystem name='Alfresco'>
       <store>workspace://SpacesStore</store>
       <rootPath>/app:company_home</rootPath>
       <urlFile>
         <filename>__AlfrescoClient.url</filename>
         <webpath>http://${localname}:8080/alfresco/</webpath>
       </urlFile>
       <offlineFiles/>
       <desktopActions>
         <global>
           <path>alfresco/desktop/Alfresco.exe</path>
           <webpath>http://${localname}:8080/alfresco/</webpath>
         </global>
         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.EchoDesktopAction</class>
           <name>Echo</name>
           <filename>__AlfrescoEcho.exe</filename>
         </action>
         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.URLDesktopAction</class>
           <name>URL</name>
           <filename>__AlfrescoURL.exe</filename>
         </action>
         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.CmdLineDesktopAction</class>
           <name>CmdLine</name>
           <filename>__AlfrescoCmd.exe</filename>
         </action>
         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.CheckInOutDesktopAction</class>
           <name>CheckInOut</name>
           <filename>__AlfrescoCheckInOut.exe</filename>
         </action>
         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.JavaScriptDesktopAction</class>
           <name>JavaScript</name>
           <filename>__AlfrescoScript.exe</filename>
           <script>alfresco/desktop/dumpRequest.js</script>
           <attributes>anyFiles, multiplePaths , allowNoParams</attributes>
           <preprocess>confirm, copyToTarget</preprocess>
         </action>
       </desktopActions>
     </filesystem>
   </filesystems>
</config>

The <DesktopActions> section contains the global and per action configuration sections.

The <global> section contains settings and overrides that apply to all the defined actions. The <path> setting specifies the location of the executable that is used by the action pseduo files. The file should be on the classpath. The default <path> value is 'alfresco/desktop/Alfresco.exe'. The <webpath> setting specifies the URL of the Alfresco web application. The ${localname} token in the web application URL is replaced with the local host DNS name or TCP/IP address.

To switch off action confirmations the <noConfirm/> configuration option can be specified in the <global> section to switch off confirmations for all actions, or within the per action configuration to switch off for a particular action.

The <action> section defines a desktop action. The <class> tag specifies the server-side desktop action class, that must be derived from the org.alfresco.filesys.smb.server.repo.DesktopAction class.

The default desktop action initialization code will look for <name>, <filename> and <debug> settings. The <name> tag specifies the action name. The <filename> tag specifies the name of the file that will appear in the folder listing. The <debug/> setting will enable debug output for the action.


Writing A Java Desktop Action


A desktop action only requires the server-side code to be implemented, the same client-side application is used for all actions. The client-side application uses information from the server-side action to determine how to validate parameters, display confirmations, launch the web browser etc.

A desktop action must be derived from the org.alfresco.filesys.alfresco.DesktopAction abstract class. The action constructor will usually call the DesktopAction(int attr, int preAction) constructor to set the action attributes and pre-processing actions.


Action Attributes


Action attributes specify the types of parameters that the action accepts, if the parameters are optional and the parameters should be passed to the action. An action may specify multiple attributes. The following attributes are available :-




















  Action Attributes
AttrTargetFolders Accepts sub-folders from the same folder as the application
AttrClientFiles Accepts files from a client local drive. Files will be copied to the target folder on the Alfresco filesystem.
AttrClientFolders Accepts folders from a client local drive. Folders will be copied to the target folder on the Alfresco filesystem.
AttrAlfrescoFiles Accepts files from another folder on the same Alfresco filesystem
AttrAlfrescoFolders Accepts folders from another folder on the same Alfresco filesystem
AttrMultiplePaths Indicates that the action accepts all parameter paths in one call to the server-side action. If not set the action will be called multiple times with one path per call.
AttrAllowNoParams Indicates that file/folder parameters are optional. Used in combination with the AttrTarget/AttrClient/AttrAlfresco attributes.

The following convenience values can be used to specify the file/folder types that the action accepts, they are combinations of the above flags :-











  Convenience Attributes
AttrAnyFiles AttrTargetFiles   AttrClientFiles   AttrAlfrescoFiles
AttrAnyFolders AttrTargetFolders   AttrClientFolders   AttrAlfrescoFolders
AttrAnyFilesFolders AttrAnyFiles   AttrAnyFolders

Pre-processing Actions


Pre-processing actions specify processing that the client-side application performs before calling the server-side action. The following pre-processing actions are available :-











  Pre-processing Actions
PreCopyToTarget Copy files/folders from another Alfresco folder to the target folder
PreConfirmAction Display a dialog box allowing the user to abort the action. The confirmation message is supplied by the server-side action.
PreLocalToWorkingCopy Files copied from a local drive must have a matching file in the target folder that is a working copy.

Action Class Methods


When the desktop action class is instantiated by the file server configuration object during startup the initializeAction() method is called. The default initializeAction() method will parse the <name>, <filename>, <debug/> and <noConfirm/> tags. If you need to add additional configuration values for your desktop action you can override this method.

The main action method that must be provided is the runAction(DesktopParams) method. The DesktopParams class contains the details of the parameters passed from the client-side application plus details of the target folder node and folder file.

The details of each file/folder parameter is contained within a DesktopTarget object. The DesktopParams class holds a list of DesktopTarget objects. If the AttrMultiplePaths attribute was not specified the parameter list will only contain one value.

Each DesktopTarget object contains the path to the file/folder, the NodeRef of the file/folder and a type value. the type value indicates if the file/folder was copied during the client-side pre-processing.

The runAction() method should return a DesktopResponse object, this contains the status and optional status message. The following status codes may be returned :-























  Action Status Codes
StsSuccess Action completed normally. Optional message will cause an information dialog to be displayed on the client.
StsError Action error. Error message will be displayed in a dialog on the client.
StsFileNotFound File not found error. Optional message can give more details of the problem path.
StsAccessDenied Access denied.
StsBadParameter Bad parameter.
StsNotWorkingCopy File is not a working copy.
StsNoSuchAction Action not found.
StsLaunchURL Launch a web browser using the URL specified in the status message.
StsCommandLine Launch an application using the command line specified in the status message.

If the PreConfirmAction pre-processing action has been enabled for the action then the String getConfirmationString() method should be used to provide the message displayed in the confirmation dialog. If no string is provided the default message of 'Run Action ?' is used. The dialog diaplayed has Ok and Cancel buttons.

If the desktop action returns the StsLaunchURL status the URL can be built using the DesktopParams.getWebPath() method to get the base URL of the Alfresco web application. To bypass the user having to login when the web browser is launched on the client an authentication ticket can be appended to the URL in the format ?ticket=<authticket>. The authentication ticket string for the user can be retrieved from the DesktopParams object using the getTicket() method.

The command line may contain environment variable tokens that are expanded by the client-side application. The tokens are in the format %<env-var-name>%, eg. %SystemRoot%\Notepad.exe would launch the Notepad application from the Windows system folder.

A special token of %AlfrescoDir% is expanded to the working directory that the client-side application is running from.


Sample Desktop Action


The following code is a very simple desktop action that echoes a message with the current date/time, the message is then displayed by the client-side application.

/**
* Echo Desktop Action Class
*
* Simple desktop action that echoes back a test message with the current date/time.
*
* @author gkspencer
*/
public class EchoDesktopAction extends DesktopAction {

  /**
   * Class constructor
   *
   * Action does not take any parameters (attributes = 0) and requires confirmation
   * before running.
   */
   public EchoDesktopAction()
   {
     super( 0, PreConfirmAction);
   }

   /**
    * Return the confirmation string displayed by the client
    *
    * @return String
    */
   public String getConfirmationString() {
     return 'Run echo action';
   }

   /**
    * Run the action, return a message to be displayed by the client application
    *
    * @param params DesktopParams
    * @return DesktopResponse
    */
   public DesktopResponse runAction(DesktopParams params) {
     // Return a text message
     return new DesktopResponse(StsSuccess, 'Test message from echo action at '   new Date());
   }
}

Writing A Javascript Desktop Action


The JavascriptDesktopAction allows a desktop action to be scripted without needing to compile, and install, a Java class. The Javascript desktop actions have the same capabilities as the Java based actions.

For a JavaScript desktop action the attributes and pre-processing flags are specified in the configuration file, along with the path to the script file. The script file must exist on the classpath, this should be a normal file on the local filesystem as the Javascript desktop action will open the script file as a file stream, i.e. the script cannot be stored in a Jar file. The JavaScript action will also check if the script file has been updated and automatically reload the updated script.

To configure a JavaScript desktop action the following section is added to the <desktopActions> section of the file-servers.xml or file-servers-custom.xml configuration file :-

         <action>
           <class>org.alfresco.filesys.smb.server.repo.desk.JavaScriptDesktopAction</class>
           <name>JavaScript</name>
           <filename>__AlfrescoScript.exe</filename>
           <script>alfresco/desktop/dumpRequest.js</script>
           <attributes>anyFiles, multiplePaths , allowNoParams</attributes>
           <preprocess>confirm, copyToTarget</preprocess>
         </action>

In this example the script file, dumpRequest.js, will be located in the WEB-INF/classes/alfresco/desktop folder.

The <attributes> setting may contain a combination of the following flags, as a comma separated list :-



























  Action Attributes
targetFiles Accepts files from the same folder as the application
targetFolders Accepts sub-folders from the same folder as the application
clientFiles Accepts files from a client local drive. Files will be copied to the target folder on the Alfresco filesystem.
clientFolders Accepts folders from a client local drive. Folders will be copied to the target folder on the Alfresco filesystem.
alfrescoFiles Accepts files from another folder on the same Alfresco filesystem
alfrescoFolders Accepts folders from another folder on the same Alfresco filesystem
multiplePaths Indicates that the action accepts all parameter paths in one call to the server-side action. If not set the action will be called multiple times with one path per call.
allowNoParams Indicates that file/folder parameters are optional. Used in combination with the target/client/alfresco attributes.
anyFiles targetFiles   clientFiles   alfrescoFiles
anyFolders targetFolders   clientFolders   alfrescoFolders
anyFilesFolders anyFiles   anyFolders



The <preprocess> setting may contain a combination of the following flags, as a comma separated list :-









  Pre-processing Actions copyToTarget Copy files/folders from another Alfresco folder to the target folder
confirmAction Display a dialog box allowing the user to abort the action. The confirmation message is supplied by the server-side action.
localToWorkingCopy Files copied from a local drive must have a matching file in the target folder that is a working copy.

The script is called by the JavascriptDesktopAction with the target parameters from the client available as script objects. The following objects are available :-













  Javascript Action Objects
deskParams The desktop action parameters
webURL URL of the Alfresco web application, in the format http://server:port/webapp/
actions Allows access to the public services
logger Script debug logging

Desktop Parameters


The deskParams object contains the details of the folder the action is running from and the target files/folders for the action. The target list may be empty if the action has the allowNoParams attribute. The list will only contain a single target if the multiplePaths attribute is not set, although the client-side application will accept multiple paths it will call the action with a single target at a time.

The following methods are available on the deskParams object :-















  Desktop Parameters Methods
getFolderNode() Returns the NodeRef of the folder the action is running from
getFolder() Returns the NetworkFile of the folder. Use getFullName() to return the share relative path of the folder.
numberOfTargetNodes() Return the count of desktop targets for this request
getTarget(int) Return the specified desktop target object
getTicket() Return the authentication ticket string that can be used in URLs by appending ?ticket=<authticket>

The desktop target object returned by the deskParams.getTarget(n) method has the following methods :-













  Desktop Target Methods
getType() Returns the target type
getTypeAsString() Returns the target type as a string. The value is 'File', 'Folder', 'File Copy', 'Folder Copy' or 'NodeRef'
getTarget() Returns the share relative path to the target file/folder
getNode() Return the NodeRef of the target file/folder

Desktop Response


The script may return a status string if an error occurs or one of the special status codes is being used, such as to pass a URL to the client or a commandline. A null return indicates that the script was successful.

The following status strings are available, they are encoded in the format <status-code>,<message text> :-






















  Script Action Status Strings 0,message Success status with an informational message for the client to display
1,error General error status
2,message File not found status
3,message Access denied status
4,message Bad parameter status
5,message Not a working copy status
6,message No such action status
7,URL Launch a URL on the client via the Windows shell
8,cmdline Launch an application on the client using the specified command line

Troubleshooting


'The application has failed to start because the application configuration is incorrect. Reinstalling the application may fix the problem.'


Try installing http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID...

Attachments

    Outcomes