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.
Table of Contents
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 ort/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...
We use cookies on this site to enhance your user experience
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.