Alfresco Custom Action

Alfresco Custom Action UI Integration

Howto for creating a custom action

Howto for creating a task history

Also it's a good idea to have installed the Alfresco SDK project in your Eclipse and have unzipped some parts of the Alfresco sources and API docs to understand the functionality.

Alfresco SDK

This article describes the steps to go for creating a simple action. The action - Quick Checkout - will replace the standard checkout action. Instead of offering all the checkout options quick checkout of a document will be a straight forward process without user interaction. QuickCheckout should:

• checkout the document into a dedicated space inside the users home folder
• create this space if it doesn't exist
• after finishing the checkout open this space or the details view of the working copy

Additionall changes in the user interface:

• the check out action button is replaced by the quick checkout button
• the edit action button is removed from all documents which have the quick checkout action
• in the details view the edit action is available as a button

If that's possible, the quick checkout should be available as an aspect and/or a rule and/or mandatory for special custom content models.

This example is separated in two parts.

1. Part one is about creating the QuickCheckout as a custom action. This action will be available in the list of actions for a document.
2. Part two shows how to make this action available as a button in the web client UI.

For deployment it is assumed that there is an exploded alfresco.war in the deployment directory of the application server. The action is available as soon as the files are copied into the specified directories and the application server is restarted. The names of the files are given above the file contents. The directory the files have to be deployed to can be found at the bottom of the file contents.

To create the QuickCheckout action the following steps have to be done:

1. An action implementation must be created.
2. A file with message properties must be created for the action.
3. The action must be bound into the Spring context.

Basic Spring knowledge is presumed for the rest of this example.

The QuickCheckout class is the actual implementation of the QuickCheckout action. It extends ActionExecuterAbstractBase and overrides executeImpl(). This method will later be called to start the action.

QuickCheckout.java

package de.hmedia.alfresco.actions;

import java.io.Serializable;
import java.util.List;
import java.util.HashMap;
import java.util.Map;

import org.alfresco.model.ContentModel;
import org.alfresco.repo.action.executer.ActionExecuterAbstractBase;
import org.alfresco.service.cmr.action.Action;
import org.alfresco.service.cmr.repository.NodeRef;

import org.alfresco.service.cmr.repository.NodeService;
import org.alfresco.service.cmr.coci.CheckOutCheckInService;
import org.alfresco.service.cmr.security.PersonService;
import org.alfresco.service.namespace.NamespaceService;

import org.alfresco.service.namespace.QName;
import org.alfresco.repo.security.authentication.AuthenticationUtil;

import org.alfresco.service.cmr.action.ParameterDefinition;
import org.alfresco.web.bean.repository.Repository;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

/**
 * This is the implementation of the QuickCheckout action. It checks out a document into a given workspace.
 * 
 * @author Sebastian Lorenz
 * @author Andreas Hartmann
 *
 */

public class QuickCheckout extends ActionExecuterAbstractBase {
	/**
	 * the current user;
	 */
	private NodeRef person;
	/**
	 * the working copy
	 */
	private NodeRef workingCopy;
	/**
	 * the target folder name (sub part of home folder only)
	 */
	private String targetSubFolder;
	/**
	 * the target
	 */
	private NodeRef targetSpace;
	/**
	 * the node service
	 */
	private NodeService nodeService;
	/**
	 * the coci service
	 */
	private CheckOutCheckInService cociService;
	/**
	 * the person service
	 */
	private PersonService personService;
	
	private static Log logger = LogFactory.getLog(QuickCheckout.class);
	
	/**
	 * Set the target folder
	 * 
	 * @param targetSubFolder  the target subfolder below the home folder 
	 */
	public void setTargetSubFolder(String targetSubFolder) {
		this.targetSubFolder = targetSubFolder;
	}
	
	/**
	 * Set the node service
	 *
	 * @param nodeService  the node service
	 */
	public void setNodeService(NodeService nodeService)
	{
		this.nodeService = nodeService;
	}
	
	/**
	 * Set the coci service
	 *
	 * @param cociService  the coci service
	 */
	public void setCociService(CheckOutCheckInService cociService)
	{
		this.cociService = cociService;
	}
		
	/**
	 * Set the person service
	 *
	 * @param personService  the person service
	 */
	public void setPersonService(PersonService personService)
	{
		this.personService = personService;
	}
	
	/**
	 * Returns the destination for the checkout as a subfolder with a given name in the homespace of the current user
	 * The space is created automatically if it doesn't exist
	 * 
	 * @param user as NodeRef - the current user
	 * @param targetName as String - the subfolder of the homefolder
	 * @return target folder as NodeRef
	 */
	public NodeRef getTargetSpace(NodeRef user, String targetName) {
		NodeRef target = null;

		// 1.get home folder
		NodeRef homeFolder = (NodeRef) nodeService.getProperty(user, ContentModel.PROP_HOMEFOLDER);

		// 2. get target NodeRef from target folder name
		target = nodeService.getChildByName(homeFolder, ContentModel.ASSOC_CONTAINS, targetName);
		
		// 2.1. create the target if it doesn't exist
		if (target == null) {
		
			Map<QName, Serializable> contentProperties = new HashMap<QName,Serializable>();
			contentProperties.put(ContentModel.PROP_NAME, targetName);
//			contentProperties.put(ApplicationModel.PROP_ICON, this.icon);
//			contentProperties.put(ContentModel.PROP_TITLE, this.title);
//			contentProperties.put(ContentModel.PROP_DESCRIPTION, this.description);
			
	        nodeService.createNode(homeFolder,
	                  ContentModel.ASSOC_CONTAINS,
	                  Repository.resolveToQName(ContentModel.TYPE_FOLDER.toString()),
	                  ContentModel.TYPE_FOLDER,
	                  contentProperties);
	         
	         target = nodeService.getChildByName(homeFolder, ContentModel.ASSOC_CONTAINS, targetName);
	         
	         if (target == null)
	             logger.warn("Could not create folder node with name: " + targetName);
	         else
                 logger.debug("Created folder node with name: " + this.name);		
		}

		return target;
	}

	@Override
	protected void executeImpl(Action action, NodeRef actionedUponNodeRef) {
		
		person=personService.getPerson(AuthenticationUtil.getCurrentUserName());
		
		targetSpace = getTargetSpace(person, targetSubFolder);
		
		if(nodeService.exists(actionedUponNodeRef) 
				&& ! nodeService.hasAspect(actionedUponNodeRef, ContentModel.ASPECT_WORKING_COPY) 
				&& nodeService.exists(targetSpace) 
				&& nodeService.getType(targetSpace).equals(ContentModel.TYPE_FOLDER)) {
			
			String workingCopyName = nodeService.getProperty(actionedUponNodeRef, ContentModel.PROP_NAME).toString();

			//checkout the node
			workingCopy = cociService.checkout(actionedUponNodeRef,
					targetSpace,
					ContentModel.ASSOC_CONTAINS,
					QName.createQName(NamespaceService.CONTENT_MODEL_PREFIX, workingCopyName));

		}
			
	}

	@Override
	protected void addParameterDefinitions(List<ParameterDefinition> paramList) {
		//no parameters for this action
	}

    /**
     * @return the targetSubFolder
     */
    public String getTargetSubFolder() {
        return targetSubFolder;
    }


    /**
     * @return the workingCopy
     */
    public NodeRef getWorkingCopy() {
        return workingCopy;
    }

}

The class must be copied to deploy/Alfresco.war/WEB-INF/classes.

The messages file for an action must at least contain a title and a description for the action.

quick-checkout-messages.properties

*
*	Quick Checkout Action I18N File
*
quick-checkout.title=Quick Checkout
quick-checkout.description=This will check out matched content into a special individual work folder.

The file has to be saved in conf/alfresco/extension

To make the action class available for Alfresco it has to be added in the Spring context. While adding it to the context the QuickCheckout class can also be given references to other classes already available in the Alfresco Spring context. That is how the parameters needed be the class are set. A reference to the message properties file of the QuickCheckout action must also be given here. This is done in the bean with id extension.actionResourceBundles in the resourceBundles property.

quick-checkout-context.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>
 
<beans>
    <!-- QuickCheckout Action Bean -->
    <bean id="quick-checkout" class="de.hmedia.alfresco.actions.QuickCheckout" parent="action-executer">
        <property name="targetSubFolder">
            <value>In Arbeit</value>
        </property>
        <property name="nodeService">
            <ref bean="nodeService" />
        </property>
        <property name="cociService">
            <ref bean="checkOutCheckInService" />
        </property>
        <property name="personService">
            <ref bean="personService" />
        </property>
        <property name="applicableTypes">
            <list>
                <value>{http://www.alfresco.org/model/content/1.0}content</value>
            </list>
        </property>
    </bean>
 
    <bean id="extension.actionResourceBundles" parent="actionResourceBundles">
        <property name="resourceBundles">
            <list>
                <value>alfresco.extension.quick-checkout-messages</value>
            </list>
        </property>
    </bean>
 
</beans>

The file has to be saved in conf/alfresco/extension

To make the QuickCheckout available to the web client the following steps have to be done:

1. Create a backing bean for the action.
2. Make the backing bean managed.
3. Create an icon for the action.
4. Customize the web client configuration to include the action.

For the rest of this example some Java Server Faces (JSF) knowledge is presumed.

The backing bean has a doQuickCheckout method that will later be bound as a JSF action listener to the quick checkout button. This method will call the QuickCheckout class to actually do the quick checkout. If the checkout was successful the navigation will be set to the space where the checked out file can be found.

This is the code of the backing bean QuickCheckoutBean.java:

package de.hmedia.alfresco.web.actions;

import java.util.Map;

import javax.faces.event.ActionEvent;

import org.alfresco.repo.security.authentication.AuthenticationUtil;
import org.alfresco.service.cmr.coci.CheckOutCheckInService;
import org.alfresco.service.cmr.repository.NodeRef;
import org.alfresco.service.cmr.repository.NodeService;
import org.alfresco.service.cmr.security.PersonService;
import org.alfresco.web.bean.NavigationBean;
import org.alfresco.web.ui.common.component.UIActionLink;

/**
 * The backing bean needed to make the QuickCheckout action available in the web ui. 
 * 
 * @author Sebastian Lorenz
 * @author Andreas Hartmann
 *
 */

public class QuickCheckoutBean {    
    /**
     * the node service
     */
    private NodeService nodeService;
    /**
     * the coci service
     */
    private CheckOutCheckInService cociService;
    /**
     * the person service
     */
    private PersonService personService;
    /**
     * the navigation bean
     */
    protected NavigationBean navigator;
    /**
     * the QuickCheckout action
     */
    de.hmedia.alfresco.actions.QuickCheckout quickCheckout;
    
    /**
     * This method will be called as an action listener from within the jsf context.
     * It does the quick checkout and navigates to the checkout target folder.
     *  
     * @param e ActionEvent given by the jsf context.
     */
    public void doQuickCheckout(ActionEvent e) {
        UIActionLink link = (UIActionLink)e.getComponent();
        Map<String, String> params = link.getParameterMap();
        String ref = params.get("ref");
        NodeRef n = new NodeRef(ref);
        
        de.hmedia.alfresco.actions.QuickCheckout qco = getQuickCheckout();
        qco.setPersonService(personService);
        qco.setCociService(cociService);
        qco.setNodeService(nodeService);
        
        qco.setTargetSubFolder("In Arbeit");
        
        qco.execute(null, n);
        
        if (qco.getWorkingCopy() != null) {
            NodeRef person = personService.getPerson(AuthenticationUtil.getCurrentUserName());
            String targetSubFolder = qco.getTargetSubFolder();
            NodeRef targetSpace = qco.getTargetSpace(person, targetSubFolder);
            navigator.setCurrentNodeId(targetSpace.getId());
        }
    }

    /**
     * @return the nodeService
     */
    public NodeService getNodeService() {
        return nodeService;
    }

    /**
     * @param nodeService the nodeService to set
     */
    public void setNodeService(NodeService nodeService) {
        this.nodeService = nodeService;
    }

    /**
     * @return the cociService
     */
    public CheckOutCheckInService getCociService() {
        return cociService;
    }

    /**
     * @param cociService the cociService to set
     */
    public void setCociService(CheckOutCheckInService cociService) {
        this.cociService = cociService;
    }

    /**
     * @return the personService
     */
    public PersonService getPersonService() {
        return personService;
    }

    /**
     * @param personService the personService to set
     */
    public void setPersonService(PersonService personService) {
        this.personService = personService;
    }

    /**
     * @return the navigator
     */
    public NavigationBean getNavigator() {
        return navigator;
    }

    /**
     * @param navigator the navigator to set
     */
    public void setNavigator(NavigationBean navigator) {
        this.navigator = navigator;
    }
    
    /**
     * @return the QuickCheckout action.
     */
    public de.hmedia.alfresco.actions.QuickCheckout getQuickCheckout() {
        if (quickCheckout == null)
            quickCheckout = new de.hmedia.alfresco.actions.QuickCheckout();
        return quickCheckout;
    }

    /**
     * @param qco the QuickCheckout action to set.
     */
    public void setQuickCheckout(de.hmedia.alfresco.actions.QuickCheckout quickCheckout) {
        this.quickCheckout = quickCheckout;
    }
}

The class must be copied to deploy/Alfresco.war/WEB-INF/classes.

To make the backing bean a JSF managed bean the bean has to be listed in the faces-config-custom.xml file. This file can be found in deploy/alfresco.war/WEB-INF. The properties needed by the backing bean have to be set here too.

faces-config-custom.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
                              "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config>
 
   <!-- *************************************************************** -->
   <!-- Empty JSF config file to prevent errors being thrown during JSF -->
   <!-- initialisation. Overwrite this file with your custom version.   -->
   <!-- *************************************************************** -->
 
 
   <managed-bean>
      <description>
         The bean that checks out a document into a given workspace.
      </description>
      <managed-bean-name>QuickCheckout</managed-bean-name>
      <managed-bean-class>de.hmedia.alfresco.web.actions.QuickCheckoutBean</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
      <managed-property>
         <property-name>nodeService</property-name>
         <value>#{NodeService}</value>
      </managed-property>
      <managed-property>
         <property-name>personService</property-name>
         <value>#{PersonService}</value>
      </managed-property>
      <managed-property>
         <property-name>cociService</property-name>
         <value>#{CheckoutCheckinService}</value>
      </managed-property>
      <managed-property>
         <property-name>navigator</property-name>
         <value>#{NavigationBean}</value>
      </managed-property>
  </managed-bean>
 
</faces-config>

This file resides in the deploy/alfresco.war/WEB-INF directory

Action icons are available in the deploy/alfresco.war/images directory. A custom icon can be added there. See next section for how to attach the icon to the action.

To make the action available to Alfresco the web-client-config-custom.xml file has to be altered. This file resides in the conf/alfresco/extension/ directory. The following lines have to be added to web-client-config-custom.xml:

<config>
    <actions>
        <!-- Quick Checkout document -->
	<action id="quick_checkout_doc">
	    <evaluator>
		org.alfresco.web.action.evaluator.CheckoutDocEvaluator
	    </evaluator>
            <label-id>quickcheckout</label-id>
            <image>/images/extension/QuickCheckOut_icon.gif</image>
            <action-listener>
	        #{QuickCheckout.doQuickCheckout}
            </action-listener>
	    <action>browse</action>
            <params>
                <param name="ref">#{actionContext.nodeRef}</param>
            </params>
        </action>
        <!-- Actions for a document in the Browse screen -->
        <action-group id="document_browse">
            <action idref="quick_checkout_doc" />
        </action-group>
        <!-- Actions Menu for Document Details screen -->
        <action-group id="doc_details_actions">
            <action idref="quick_checkout_doc" />
        </action-group>
    </actions>
</config>

This file resides in the conf/alfresco/extension/ directory

• The bean classes shouldn't reside directly in the alfresco.war deploy dir. This can be achived by packaging the files into an Alfresco module (.amp) file.