WCM Deployment Features

Document created by resplin Employee on Jun 6, 2015Last modified by alfresco-archivist on Aug 31, 2016
Version 18Show Document
  • View in full screen mode

Obsolete Pages{{Obsolete}}

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

Back to WCM Developer Documentation


This page highlights the capabilities of the WCM Deployment functionality in the 3.2 releases.

Deployment features prior to 3.2.

WCM Deployment provides a framework for pushing content from an Alfresco WCM Authoring environment into another environment.   For example, you can push out content to a flat file-system to be served up by Apache or IIS, or you can push your content into another runtime instance of Alfresco.  

The WCM Authoring environment provides the facilities to produce an approved and consistent view of a web project called a snapshot.   WCM deployment takes those snapshots and pushes them out to either live or test servers. 

Deployments are pushed from an Alfresco WCM authoring environment to a WCM Deployment Engine which then delegates to the appropriate Deployment Receiver Target.

The deployment process may be automated so that it happens automatically when content is approved for publishing.

The deployment framework provides a flexible and highly configurable system to allow you to tailor the system to your requirements.    If the alfresco supplied components are not suitable you can plug in your own authenticators, transport implementations, content transformers and deployment targets.


The following diagram shows the default configuration of deployment in alfresco wcm.  It shows the two implementations of the deployment engine and four pre-defined deployment targets. 


Alfresco Deployment Engine

WCM Deployments are sent to an alfresco deployment engine which delegate the deployment to the registered deployment targets.

The Standalone Deployment Engine consists of a small server that receives updates from an alfresco repository and publishes them to its deployment targets.   It does not have the benefits of a full repository but is a small and tightly focused server.

Out of the box its configured with a single File System Deployment Target which places the contents of the deployment onto a flat file system which is then typically served up by a web or application server.  For performance reasons only differences between the old version and the new version are sent.

The destination file server receiver has to be running with its RMI registry port and service port (44100 and 44101 by default) accessible.  Unless you have configured it to run over another transport.

Deployment Target

A deployment target is a named destination for a WCM deployment.   WCM deployment will deploy through a deployment engine to a deployment target.

Out of the box there are four deployment targets defined.   And you can add your own as well.

Live/Test Server Deployment

Deployment servers are either live servers or test servers.   This is simply a flag to prevent accidents of deploying content to the wrong server.    Deployments from the staging sandbox go to live servers and from authoring and workflow sandboxes to test servers.

A contributor can  deploy the state of their sandbox to a test server and preview their site. Similarly, reviewers in a workflow can deploy and preview the change set they are approving (or rejecting).

Once a test server has been deployed to, it is allocated to the user or workflow that performed the deploy. Once the user or workflow has finished with the test server it is released and returned to the pool of test servers. This happens automatically in the case of a workflow sandbox and manually via a UI action for user sandboxes.

Further information on the preview options supported by Alfresco WCM is available at WCM Preview.

Deployment Receiver Configuration

Edit Web Project

The Web Project Manager can configure the deployment receivers by using the Create and Edit Web Project wizard in the Alfresco Explorer interface.   Once the web project manager has configured a deployment receiver then the other members of the web project can deploy to it.

The image below is a screenshot from the add deployment receiver page.
Add Deployment Receiver.GIF

Server Type

The server type specifies whether deployment is for a Live server or Test server.  This is to prevent accidental deployment of unapproved content to a live server.  Staging sandboxes are deployed to live servers. Author and workflow sandboxes deploy to test servers.


The transport to use to connect to your destination server.   By default a single transport is defined
with the name of default. Advanced system administrators can configure different transport
adapters to deploy content over different transports.


The host name of the destination server, which can be a name or IP address


The tcp port on the destination server to connect to.  

If using the default alfresco RMI based transport the RMI registry for a standalone deployment receiver
is on port 44100.   For a repository backed deployment engine, 50500.

Display Name

A descriptive label for the server, used by the UI. Free format.

Display Group

A descriptive label used by the UI to group servers together.  Free format.


To prevent unauthorised access, each target is secured by a username and password.

The username to use to connect to the destination target


The password to use to connect to the destination target


The runtime URL of the destination server, can be used to preview the deployment upon a successful

Source Path

Leave blank unless you only want to deploy part of your web project.

The path of the folder to deploy, for example /ROOT.  

You can choose to only deploy part of a web project by specifying a value in the source path.
By default the WCM User interface adds '/www/avm_webapps' to the beginning of the file paths.   The
source path does the same.    The next part of the file name is the WebApp.   Which, unless you have
defined multiple webapps for the web project, is ROOT.

So, if you create a folder (folderA) in your web project it will have a path
'/www/avm_webapps/ROOT/folderA'.   You can choose to deploy just this folder and its children by
specifying 'ROOT/folderA' in source.  

If you find the webapp concept unhelpful and you are not using multiple webapps you can just add 'ROOT'
as the source path and then your deployed content will not start with 'ROOT'.


A single regular expression (multiple rules can be defined within the expression) of items to exclude
from the deployment, for example .*\.jpg$|.*\.gif$ will exclude any file paths ending with
.jpg or .gif

During deployment each file name is compared to the Excludes pattern. If the file name matches the
pattern then the file is excluded from deployment. Regular expressions can be somewhat cryptic but are

The path given to the matcher is the Store Reference for example


where 'test20text' is the WCM project name and 'myapp/dir1/index.htm' is an file in the project.

Here are some examples

.*\.jpg$|.*\.gif$ :

exclude any files ending with .jpg OR .gif

[A-Za-z0-9:/_]*ROOT/myapp/dir1/*  :

exclude all files within the dir1 folder of my project

Target Name

The name of a target to deploy to.    If nothing is specified then the value 'default' is chosen which
corresponds to the 'default' target of the standalone deployment receiver.    Other out of the box
targets are 'avm', 'alfresco', and 'filesystem'.   You may have also defined your own targets.

Include In Auto Deployment

Determines whether the live server will be deployed to if the Auto Deploy option is selected during a submission.

As can be seen in the screenshot above the only required data is the Host and Port. All other fields can be left empty so that the defaults will then be used. The defaults can be seen in the

Configuration section below.

Real Time Monitoring

Once the destination servers have been specified a deployment can be initiated and monitored.

Deploying to a live server

To start a deployment to a live server, open the list of snapshots in the staging sandbox and click on the deploy action icon shown in the screenshot below.


This will open the Deploy Website window shown below. Each configured live server will be presented with a checkbox.


Click OK to start the deployment process. The Deploy Website window will close and open the Monitor Deployment window. This window shows the progress of each deployment currently executing in the server. An AJAX callback is used to poll the server for progress. The frequency of this polling request can be set in the web-client-config-wcm.xml configuration file. A deployment in progress is shown in the screenshot below.


Once the deployment completes the state is updated as shown below. When a URL has been configured this will appear under the Deployment Successful message to allow instant previewing of the deployed site. If an error occurs the reason for the error is shown under the Deployment Failed message.

The window can be closed at any time during the deployment, however, the window can not be returned to (this will be rectified in a future release). To monitor progress if the Monitor Deployment window is closed, open the snapshot list in the staging area and monitor the status column, an IN PROGRESS message will be shown if one or more deployment processes are executing.



Deploying to a test server

Deployments to test servers can be performed from two different places: a user sandbox and a review sandbox. However, in both cases the procedure and UI is exactly the same.

In a user sandbox open the More Actions menu and click the Deploy icon (shown in the screenshot in the previous section) and for the review sandbox click the Deploy icon in the Resources panel header.

Clicking the Deploy icon will open the Deploy Website window shown below in the screenshot. All the unallocated test servers will be displayed.


Choose a test server to use (currently only one test server can be allocated to a sandbox at a time) and click OK. This will allocate the test server to the current sandbox and deploy the contents of the sandbox. The Monitor Deployment window will open and proceed as explained in the previous section.

If there are no unallocated test servers available the window will show the following message:


Once a test server has been allocated to, click the Deploy icon to show the Deploy Changes window, as shown in the screenshot below. This confirms which server is allocated to the sandbox before deployment.


Deployment History

Wherever a deployment is executed, the result is a set of deployment reports. These can be accessed from the View Deployments icon, shown in the screenshot below. For the staging sandbox, the icon appears in the top right of the panel; for the user sandbox, the icon appears in the More Actions menu; and for review sandboxes, the icon appears in the header of the Resources panel.


Click the View Deployments icon to launch the Last Deployment Report window , as shown in the screenshot below.


A deployment report is shown for the servers deployed to in the last deployment attempt. The screenshot above shows one successful report and one failed report. The expandable Details area either shows what happened in the deployment when it was successful or error details in the case of a failed deployment.

There may be times when the expandable Details area does not appear on successful reports. This occurs when a deployment takes place and does not make any changes, that is, the destination server was up to date.

If the View Deployments icon is clicked before any deployment reports have been generated, the message in the screenshot below will be shown. As reports are generated they will appear here.


For the staging sandbox only a status column displays the deployment status for the last snapshot deployed.


There are four possible values:

  • IN PROGRESS: Deployment is occurring on one or more servers
  • LIVE: All servers were deployed to successfully
  • PARTIAL FAILURE: Deployment failed on one or more servers
  • FAILED: Deployment failed on all servers

Clicking the View Deployment link while the status is IN PROGRESS will result in the behaviour detailed above.

The More Deployment Reports panel, when expanded it shows all previous deployment attempts ordered by the date of the attempt. The results can be filtered by Today, Yesterday, Last 7 Days, Last 30 Days and All. Use the All filter with caution though, this could return a lot of results and therefore take a long time to render the page.

Click on an attempt date to launch the Deployment Report window, where you can view the deployment reports for the selected attempt, as shown in the screenshot below.


To return quickly to the last deployment report, click the View Last Deployment Report icon that appears in the header of the expanded panel.

Removing Deployment Reports

There are two ways to clean out old deployment reports:

  • selectively (based on age) by a scheduled job
  • total clean via the UI

Administrators and content managers have the Delete All Deployment Reports icon available to them in the Actions menu for a staging sandbox. Clicking the icon will display a confirmation page. If you click OK, ALL deployment reports for the whole web project will be deleted.

If a complete clean is too extravagant, a scheduled job can be setup to clean all reports over a configurable age. The job is provided as a sample file called deployment-attempt-cleaner-context.xml.sample. As with any sample extension remove the .sample suffix and place the file in the <tomcat>/shared/classes/alfresco/extension folder. For details on configuring the job refer to the Configuration section towards the end of this page.

Deployment Attempt Cleaner Job

A sample scheduled job is provided that, when enabled, will purge any old deploymentattempt nodes. By default, the job will purge any nodes older than 180 days at 4am every morning, as shown below.

<bean id='avmDeploymentAttemptCleaner' class='org.alfresco.repo.avm.AVMDeploymentAttemptCleaner'>
   <property name='maxAge'>

<bean id='avmDeploymentAttemptCleanup' class='org.alfresco.util.CronTriggerBean'>
   <property name='cronExpression'>
      <value>0 0 4 * * ?</value>

Test Servers

Author sandboxes may be deployed to 'test servers'.   The first part of the process is to lock one or more test servers for the use of a particular author.

Once a test server has been deployed to, it is allocated to the user or workflow that performed the deploy. Once the user or workflow has finished with the test server it is released and returned to the pool of test servers. This happens automatically in the case of a workflow sandbox and manually via a UI action for user sandboxes.

The administrator or content manager can see what test server is allocated to which sandbox by going to the edit website wizard and viewing the Allocated field. Hovering over the Yes label will reveal the actual store name as a tooltip.

Test servers allocated to user sandboxes can be released by the owner of the sandbox, the administrator or the content manager. The Release Server icon is available in the More Actions menu.

Test servers allocated to review sandboxes are automatically released by the system upon completion of the workflow.

Auto Deploy

A common requirement is to have the staging area automatically deploy when a set of changes is approved (using the Website Submission workflow).

If you are using the workflow to submit your changes, the Submit window has an Auto Deploy checkbox, as shown in the screenshot below.


Upon approval, if the auto deploy option is on, the workflow will perform a deployment to those live servers that have the Include In Auto Deploy option enabled.

As this all happens in the background on the server. There is no Deployment Monitor window in this scenario. However, as with any manual deployment from the staging sandbox the Last Deployment Report window and the status column can be used to monitor the progress and overall result.

NB. I'm not sure whether it's possible to use auto-deploy without using an approval-based workflow; perhaps another workflow that can be built which will activate the auto-deploy checkbox without needing approval for a submission - Dafydd James 2010-10-26


The following sections provide details on the implementation of the deployment functionality.


The WCM application model has been extended in the 2.2 release to support multiple deployment servers and to store historical deployment reports.

A graphical representation of the deployment model is shown in the diagram below.


As can be seen in the diagram above, the properties added to wca:webfolder in the 2.0.1 release have been deprecated, as has the wca:deploymentreport'child association. To see the full definition of the deployment model, take a look at the file named wcmAppModel.xml.

The other model updated for deployment is the WCM workflow model (wcmWorkflowModel.xml). A new property exists to indicate whether an automatic deployment should be performed once a change set has been approved according to the rules of the workflow. The property definition is shown below.

<property name='wcmwf:autoDeploy'>
   <title>Auto Deploy</title>
   <description>Determines whether the changes should be deployed upon submission</description>


The code for the WCM Deployment Engine is contained within the Deployment project within the Alfresco SVN repository.

Deploy Website Dialog

The Deploy Website window operates in several modes. It uses the UIDeployWebsite JSF component to display the list of live servers when a deploy operation is being performed in the staging sandbox, a list of test servers when deploying to a user or review sandbox for the first time and the allocated test server when changes from a user or review sandbox are being deployed.

Once the user makes and confirms their selection, the window implementation (DeployWebsiteDialog) creates a deploymentattempt node as a child of the webfolder node representing the web project.

The attempt node and a callback object (DeploymentMonitor) are then passed to an asynchronously executed AVMDeployWebsiteAction instance (one for each server selected).

The DeploymentMonitor object and UIDeployWebsite component is used to display the progress of each server being deployed to.


2.2 replaces the old AVMDeploySnapshotAction with the new AVMDeployWebsiteAction repository action.

The AVMDeployWebsiteAction takes two mandatory parameters and a couple of optional ones. The parameter definition is shown below:

public static final String PARAM_WEBPROJECT = 'webproject';
public static final String PARAM_SERVER = 'server';
public static final String PARAM_ATTEMPT = 'attempt';
public static final String PARAM_CALLBACK = 'callback';

paramList.add(new ParameterDefinitionImpl(PARAM_WEBPROJECT, DataTypeDefinition.NODE_REF, true,
paramList.add(new ParameterDefinitionImpl(PARAM_SERVER, DataTypeDefinition.NODE_REF, true,
paramList.add(new ParameterDefinitionImpl(PARAM_ATTEMPT, DataTypeDefinition.NODE_REF, false,
paramList.add(new ParameterDefinitionImpl(PARAM_CALLBACK, DataTypeDefinition.ANY, false,

The parameters are explained below:

webproject: NodeRef of the webproject the website being deployed is from.
server: NodeRef of the deploymentserver configuration being deployed.
attempt: NodeRef of the deploymentattempt node that represents the deployment attempts (parent of produced deploymentreport nodes).
callback: Instance of an object implementing the DeploymentCallback interface, if present all deployment events are sent to this listener object.

The default values for the remote username/password, port numbers, and so on, are Spring configured, for details see the configuration section. The default values are used unless the provided deploymentserver node has overridden them.

The AVMDeployWebsiteAction action marshals all the provided data into the parameters required to call the repository DeploymentService. When the deployment completes the action creates, populates and persists a deploymentreport node as a child of the provided deploymentattempt node.

Deployment Service

The DeploymentService is the key part of the deployment process. The JavaDoc for the service is shown below.

  * Deploys the differences between what is is the local source path
  * and a destination machine's path.
  * @param version The local version.
  * @param srcPath The local path.
  * @param hostName The remote hostname.
  * @param port The remote rmi registry port.
  * @param userName The username for authentication.
  * @param password The password for authentication.
  * @param dstPath The destination path corresponding to source path.
  * @param createDst Flag for whether a missing destination should be created.
  * @param dontDelete Don't delete assets at the destination.
  * @param dontDo If this is set then this is a dry run.
  * @param callbacks A list of callbacks.
public DeploymentReport deployDifference(int version, String srcPath,
                                          String hostName, int port,
                                          String userName, String password,
                                          String dstPath,
                                          NameMatcher matcher,
                                          boolean createDst,
                                          boolean dontDelete,
                                          boolean dontDo,
                                          List<DeploymentCallback> callbacks);

  * Deploy to a filesystem on another machine.
  * @param version The version to deploy from.
  * @param srcPath The path to deploy from.
  * @param hostName The hostname of the filesystem receiver.
  * @param port The port to connect to.
  * @param userName The username for authentication
  * @param password The password for authentication
  * @param dstTarget The target on the deployment receiver.
  * @param createDst Flag for whether a missing destination should be created.
  * @param dontDelete Don't delete deleted nodes from destination.
  * @param dontDo If this is set, this is a dry run.
  * @param callbacks A list of callbacks.
public DeploymentReport deployDifferenceFS(int version, String srcPath,
                                            String hostName, int port,
                                            String userName, String password,
                                            String dstTarget,
                                            NameMatcher matcher,
                                            boolean createDst,
                                            boolean dontDelete,
                                            boolean dontDo,
                                            List<DeploymentCallback> callbacks);

The DeploymentService uses the userName and password to connect to the RMI registry on the Alfresco server or deployment receiver represented by hostName and port. The connection is currently made using RMI, HTTPS connections have been tested but will not be supported until a later release.

Once connected the DeploymentService determines what differences there are between the srcPath and the dstTarget and applies those changes. Although the DeploymentService can leave deleted assets and perform a dry run these features are not currently exercised by the web client.

The matcher parameter, if supplied, allows a subset of srcPath to be omitted from the deployment. This takes the form of a regular expression.

The callbacks parameter allows a list of DeploymentCallback implementations to listen to the deployment. All events that occur during the deployment process, including errors, are sent to the callback objects.

If the deployment is successful a DeploymentReport is returned which contains a list of all the events that occurred as part of the deployment. A failure to deploy is currently indicated by an AlfrescoRuntimeException.

Deployment Callback

As mentioned above a callback object can be used to track progress of a deployment operation. The interface definition for  DeploymentCallback is shown below.

public interface DeploymentCallback
     * Called each time something happens during deployment.
     * This is called synchronously by the deployer and should
     * therefore be handled rapidly, if possible.
     * @param event The event that occurred.
    public void eventOccurred(DeploymentEvent event);

Six types of event can be received as shown by the following enum definition:

public static enum Type implements Serializable
   COPIED,    // Copied a source node that did not exist on the destination.
   UPDATED,   // Overwrote the destination.
   DELETED,   // Deleted the destination node.
   START,     // A Deployment has begun.
   END,       // A Deployment has ended.
   FAILED     // A Deployment failed.

Each event also provides the source path, destination path and an optional message. The message is currently only used by the FAILED event so send the error message that caused the failure.

In releases prior to 2.2 only one DeploymentCallback object could be passed to the DeploymentService and this was hard-coded to be the DeploymentMonitor object used by the UI. A list of callback objects can now be passed all of which will get called back appropriately. To see how to pass custom callback implementations to the DeploymentService see the configuration section.

Monitor Dialog

When the user clicks OK in the Deploy Snapshot window, several events occur to allow monitoring of the deployments. A DeploymentMonitor object gets instantiated and passed as the DeploymentCallback object to AVMDeploySnapshotAction. The DeploymentMonitor object itself creates a unique identifier and gets stored using that key in the HTTP session. This identifier is referred to hereinwith as a deployment monitor id. A list of deployment monitor ids is also constructed and stored in the AVMBrowseBean JSF managed bean.

When a deployment operation starts, the Monitor Deployment window is opened. This window uses the same JSF component as the 'Deploy Snapshot' window, UIDeployWebsite. This time however, it is passed the list of deployment monitor ids from AVMBrowseBean and its monitor attribute is set to true. This shows the same list of selected servers but displays an animated icon instead of a checkbox to provide user feedback on the deployment progress.

Every two seconds (this is configurable though) an AJAX call is made back to the server requesting the status of the executing deployments. This is done using the following request (where xxxx, yyyy and zzzz are deployment monitor ids):


As the URL suggests, this calls a JSF managed bean called DeploymentProgressBean. It is responsible for locating the DeploymentMonitor object associated with each supplied deployment monitor id and producing the XML to represent the state of the deployment.

The response is an XML file with the following format:

   <target-server id='xxx' name='host[:port] or display name' server='NodeRef of server node'
                  attempt='NodeRef of attempt node' finished='true|false'
                  [successful='true|false'] [url='server url'] [reason='error message'] />

There is a target-server element for each server selected by the user. The attributes are explained below:

id: Contains the deployment monitor id.
name: Host name/IP address and port or display name of the server the deployment is going to.
server: The NodeRef of the deploymentserver node the deployment is going to.
attempt: The NodeRef of the deploymentattempt the deployment is part of.
finished: Indicates whether the deployment has finished.
successful: Indicates whether the deployment was a success or not. The successful attribute is only present once finished is true.
url: An optional URL for the destination server.
reason: If the deployment failed this will hold the error message that caused the failure.

The client side of the UIDeployWebsite component takes the response and updates each server progress area as appropriate.

Deployment Report

Once a deployment operations completes, whether successful or not, the AVMDeployWebsiteAction implementation creates a deploymentreport object as a child association of the deploymentattempt node passed to the action as a parameter.

The deploymentreport node holds a copy of all the relevant data from the deploymentserver node passed to the action. Doing this keeps the report completely separate from the server configuration meaning the server configuration can be changed in isolation and the deployment audit trail remains intact.


To support the auto deployment at the end of a submission workflow, a new handler has been added to the node-enter event on the submitted task and to support the release of any allocated test server a new handler has been added to the process-end event. This is shown in the snippet from submit_processdefinition.xml below:

<task-node name='submitted'>
   <event type='node-enter'>
      <action class='org.alfresco.repo.avm.wf.AVMDeployHandler'/>
<event type='process-end'>
   <action class='org.alfresco.repo.avm.wf.AVMReleaseTestServerHandler'/>

AVMDeployHandler is called once the change set has been approved. If the autoDeploy process instance variable is set to true (the user selected the checkbox in the Submit window) the handler creates a deploymentattempt node and then an instance of AVMDeployWebsiteAction for each live server configured to be included in any automatic deployments.

It determines the list of servers by querying for live servers from the web project with their deployonapproval property set to true.


Being an action, AVMDeployWebsiteAction can still be called from a JavaScript, in fact it is now easier as there are a lot less mandatory parameters to satisfy. However, one of the new mandatory parameters is the deploymentattempt node used to store the deploymentreport nodes. An instance of a deploymentattempt needs to be created and populated before calling the action. Furthermore, if several servers are being deployed to as part of the same operation the same attempt instance should be passed to each action execution.



The only configurable aspect of the deployment UI is the polling frequency for the Progress window. This is done via the web client configuration mechanism and as such can be overridden using the extension mechanism. The file web-client-config-wcm.xml contains the default value as shown below:



Default values for calling the DeploymentService are configured in Spring meaning they can be overridden using the standard repository configuration mechanism or via an AMP.

<bean id='avm-deploy-website' class='org.alfresco.repo.avm.actions.AVMDeployWebsiteAction' parent='action-executer'>
   <property name='defaultRemoteUsername'>
   <property name='defaultRemotePassword'>
   <property name='defaultAlfrescoRmiPort'>
   <property name='defaultReceiverRmiPort'>
   <property name='defaultTargetName'>
   <property name='delay'>
   <property name='callbacks'>
         <ref bean='org.alfresco.sample.DeploymentCallback1' />
         <ref bean='org.alfresco.sample.DeploymentCallback2' />

The properties are explained as follows:

defaultRemoteUsername: Username passed to DeploymentService if one is not configured in the deploymentserver passed to AVMDeployWebsiteAction
defaultRemotePassword: Password passed to DeploymentService if one is not configured in the deploymentserver passed to AVMDeployWebsiteAction
defaultAlfrescoRmiPort: RMI port to connect to on the destination ASR if a port is not configured in the deploymentserver passed to AVMDeployWebsiteAction
defaultReceiverRmiPort: RMI port to connect to on the destination FSR if a port is not configured in the deploymentserver passed to AVMDeployWebsiteAction
defaultTargetName: Target name passed to DeploymentService if one is not configured in the deploymentserver passed to AVMDeployWebsiteAction
delay: Value specifies, in seconds, how much delay to add to the beginning of a deployment. This is only used if the alfresco.deployment.delay debug flag is set, see the Debugging section for details.
callbacks: List of DeploymentCallback implementations that need to be passed to the DeploymentService