Returning Values From 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:

Return to Developer Guide

Why return a value from an action

In most cases a repository action simply does a job of work and is complete.  However, in some situations it is desirable to receive a return result from the action.

Often this will be a value calculated during the action's execution and be specific to that instance and action execution.

As action provide an easy point of extension to the repository, actions that return values can be used as a simple and non-disruptive way of adding additional features and functionality that provide feedback directly to the calling client.

How to return a value from a custom action

In order to make a return value available to the API calling an action the action implementation should modify the parameters of the action being called to include the desired value.

For example in the following code of a custom action the child count of the actioned upon node is added to the action's parameter list and thus made available to the calling code.

   public void executeImpl(Action ruleAction, NodeRef actionedUponNodeRef) {     
       if (this.nodeService.exists(actionedUponNodeRef))
           // Get the parent node                
           int count = this.nodeService.getChildAssocs(actionedUponNodeRef).size();
           ruleAction.setParameterValue(PARAM_RESULT, Integer.valueOf(count));

The parameter name PARAM_RESULT (defined in the ActionExecuter interface) is the default name of a return value. 

   /** Standard action result parameter name */
   public static String PARAM_RESULT = 'result';

Calling the return value added to the action this well known name ensures that the general implementations that call the action API (for example web services) correctly look for a return value and forward it on correctly.

If executing the action directly from the action service, after execute has been called the action object can be inspected for the result value.

For an example of a custom action that returns a value, see org.alfresco.repo.action.executer.CountChildrenActionExecuter.

Returning a value from a JavaScript action

When an action executes a JavaScript file (or any other supported script language) the result of the script is added to the action so that the value is returned in the manner descried above.

Hint:  the value returned from a JavaScript is the last value present.  Calling 'return 'myvalue';' at the end of the file will not work, rather simple placing ''myvalue';' at the end of the file will return the required value.

Calling an action that returns a value from the WebService API

If you are using the Alfresco Java web service client library to access the repository there is a helper class that provides methods to make calling actions, and reading any return values, easy.

Look for org.alfresco.webservice.util.ActionUtils.  This class contains two methods:

   * Executes an action with the provided parameters, returning the result if appropriate.  Return nulls in the case
   * where no return result for the action has been set.
   * @param actionedUpon    the node that the action will action upon
   * @param actionName      the action name (eg: 'ExecuteScript')
   * @param parameters       the parameter values of the action
   * @return String                the result result of the action, null if none provided or action a   
   public static String executeAction(Reference actionedUpon, String actionName, Map<String, String> parameters)

... and ...

   * Executes a script against the actioned upon node.
   * @param actionedUpon    the actioned upon node
   * @param script        the script node
   * @return String        the result of the script (null if none)
  public static String executeScript(Reference actionedUpon, Reference script)

See below for example usage:

  // Execute 'count children' action
  Reference folder = <my folder reference>;
  String childCount = ActionUtils.executeAction(folder, 'count-children', null);

ActionsCustomizing and ExtendingContent Modeling