Extending the Multi Site Manager

You are reading the Adobe Experience Manager 5.6.1 version of Extending the Multi Site Manager.
This documentation is also available for the following versions: AEM 5.6 CQ 5.5 CQ 5.4 CQ 5.3

This page helps you extend the functionalities of the Multi Site Manager. It describes:

the main objects that can be accessed through the Java API of the Multi Site Manager.
how to create a new synchronisation action that can be used in a rollout configuration.
how to exclude properties and node types from the synchronisation process between a blueprint and a live copy.
how to remove the "Chapters" step in the Create Site wizard.

This page should be read in conjunction with Managing Blueprints and Live Copies.

Overview of the Java API

To decouple the MSM from the WCM core the interfaces that were used until CQ 5.3 are declared deprecated:

com.day.cq.wcm.api.msm

They have been replaced by the ones defined in:

com.day.cq.wcm.msm.api

The main MSM API objects interact as follows: a Blueprint defines the pages from which a live copy can inherit content. After a live copy has been created based on a blueprint, a dynamic relationship called LiveRelationship is established between each live copy and blueprint resource. The LiveRelationship gets effective with the process called rollout. This process is defined by the rollout configurations - called RolloutConfig - on the blueprint and on the live copy. The RolloutConfig can be set on the blueprint and/or on the live copy. A RolloutConfig consists of a set of actions that are applied upon rollout.

Blueprint

A Blueprint defines the pages from which a live copy can inherit content. The use of a blueprint is optional but is required to push modifications to live copies that are inheriting from this blueprint or to define the default rollout configuration for the live copy that is in relation with the blueprint.

LiveCopy

A LiveCopy is the configuration of the relationship (LiveRelationship) that the current page wants to establish with its blueprint page.

LiveRelationship

The LiveRelationship models the relationship that a resource has with a related resource in the blueprint. It contains the configuration - as defined by LiveCopy - and the LiveStatus. Each resource that is part of a live copy has its own LiveRelationship with the blueprint resource.

For example, if a site (blueprint) /content/geometrixx has a live copy in /content/copy, then the resources /content/geometrixx/en/jcr:content and /content/copy/en/jcr:content form a relationship. It also extends to components within a page, as for example, the resources /content/geometrixx/en/jcr:content/par/title and /content/copy/en/jcr:content/par/title can form a relationship.

LiveStatus

Status at runtime of the live relationship of a synced resource between the blueprint and the live copy.

LiveAction

A LiveAction is an action that is executed upon rollout for each resource contained in the LiveRelationship.

Creating a New Synchronisation Action

In certain cases, it might be needed to create a custom synchronisation action to meet specific customer requirements for the rollout process. To do so, create an OSGI component that:

Implements com.day.cq.wcm.msm.api.LiveAction
Has the following properties that can be set through the Web Console:
- action title
- action rank
- action properties
Has the following properties that can be hard-coded, as they have to be unique within the Instance and must not change during runtime:
- action name: the name of the action needs to be unique.
- action parameter: the name of the parameter needs to be unique.
Implements all the methods defined by the com.day.cq.wcm.msm.api.LiveAction interface.

The following code snippet is a sample that you can use as a base to build your own action:

...

/**
 * MyLiveAction ...
 * 
 * @scr.component metatype="true" name="mypackage.MyLiveAction"
 * @scr.service interface="com.day.cq.wcm.msm.api.LiveAction"
 * @scr.property name="cq.wcm.msm.action.title"
 *               label="%cq.wcm.msm.action.title.label"
 *               description="%cq.wcm.msm.action.title.description"
 *               value="My Live Action"
 * @scr.property name="cq.wcm.msm.action.rank"
 *               label="%cq.wcm.msm.action.rank.label"
 *               description="%cq.wcm.msm.action.rank.description"
 *               type="Integer"
 *               value="<action rank>"
 * @scr.property name="cq.wcm.msm.action.properties"
 *               label="%cq.wcm.msm.action.properties.label"
 *               description="%cq.wcm.msm.action.properties.description"
 *               values.0="enabled"
 *               values.1="myProperty"
 */

public class MyLiveAction implements LiveAction {
	
    /**
     * default logger
     */
    private final Logger log = LoggerFactory.getLogger(MyLiveAction.class);
    
    private final static ACTION_NAME = "myActionName";

    private final static ACTION_PARAMETER = "actionParameter";
    
    private Dictionary<String, Object> prop;

    protected void activate(ComponentContext context) {
    	prop = context.getProperties();
    }

    protected void deactivate(ComponentContext context) {
    }

    private Dictionary<String, Object> getProperties() {
        if( prop == null ) return new Hashtable<String, Object>();
        return prop;
    }

    /**
     * {@inheritDoc}
     */
    public String getTitle() {
        return (String) getProperties().get("cq.wcm.msm.action.title");
    }

    /**
     * {@inheritDoc}
     */
    public String getName() {
        return ACTION_NAME;
    }

    /**
     *
     */
    public String getParameter() {
        return ACTION_PARAMETER;
    }

    /**
     * {@inheritDoc}
     */
    public int getRank() {
        Object p = getProperties().get("cq.wcm.msm.action.rank");
        if( p == null) return Integer.MAX_VALUE;

        if( p instanceof String) {
            return Integer.parseInt((String) p);
        }

        if( p instanceof Integer) {
            return (Integer) p;
        }

        return Integer.MAX_VALUE;
    }

    /**
     * {@inheritDoc}
     */
    public String[] getPropertiesNames() {
        Object p = getProperties().get("cq.wcm.msm.action.properties");
        if( p == null) return new String[0];
        if( p instanceof String) {
            return new String[] { (String) p };
        }

        if( p instanceof String[] ) {
            return (String[]) p;
        }

        return new String[0];
    }

    /**
     * {@inheritDoc}
     */
    public String getParameterName() {
        return ACTION_PARAMETER;
    }
    
    /**
     * {@inheritDoc}
     */
    public void execute(final ResourceResolver resolver,
                        final LiveRelationship relation,
                        final ActionConfig config,
                        boolean autoSave)
            throws WCMException {
        execute(resolver, relation, config, autoSave, false);
    }

    /**
     * {@inheritDoc}
     */
    public void execute(final ResourceResolver resolver,
                        final LiveRelationship relation,
                        final ActionConfig config,
                        boolean autoSave,
                        boolean isResetRollout)
            throws WCMException {
    	// your code...
    }

    public void write(JSONWriter jsonWriter) throws JSONException {
        jsonWriter.object();
        jsonWriter.key("name").value(getName());
        jsonWriter.key("parameter").value(getParameter());
        jsonWriter.key("title").value(getTitle());
        jsonWriter.key("rank").value(getRank());
        jsonWriter.key("properites");
        jsonWriter.array();
        for(String prop: getPropertiesNames()) {
            jsonWriter.value(prop);
        }
        jsonWriter.endArray();
        jsonWriter.endObject();
    }
}

Note

The ActionConfig config parameter of the execute() method is retrieved from the repository by reading the properties of the cq:LiveSyncAction node.

See for example the editProperties action at /etc/msm/rolloutconfigs/mobile/jcr:content/editProperties.

Excluding Properties and Node Types from Synchronisation

By default certain properties and node types are excluded from the synchronisation between blueprints and live copies. The list of excluded properties and node types can be further extended.

When working with AEM there are several methods of managing the configuration settings for such services; see Configuring OSGi for more details and the recommended practices. For example:

In your browser, open the Web Console:
http://localhost:4502/system/console/configMgr
In the Configuration tab, select Day CQ WCM Rollout Manager.
You can configure the following parameters:
- Excluded Page Properties: java regex that defines the page property names that are excluded from the synchronisation.
- Excluded Nodetypes: java regex that defines the node types that are excluded from the synchronisation.
Click Save.

Note

Setting the Excluded Paragraph Properties has no effect in AEM as the exclusion of paragraph properties from the synchronisation has not yet been implemented.

The configuration window looks as follows:

Removing the "Chapters" Step in the "Create Site" Wizard

In some cases, the Chapters selection is not required in the Create Site wizard but only the Languages selection. To remove this step in the default Geometrixx blueprint:

In CRX Explorer, remove the node /etc/blueprints/geometrixx/jcr:content/dialog/items/tabs/items/tab_chap.
Navigate to /libs/wcm/msm/templates/blueprint/defaults/livecopy_tab/items and create a new node. Name = chapters, Type = cq:Widget.
Add following properties to the new node:
- Name = name, Type = String, Value = msm:chapterPages
- Name = value, Type = String, Value = all
- Name = xtype, Type = String, Value = hidden

Your comments are welcome!

Did you notice a way we could improve the documentation on this page? Is something unclear or insufficiently explained? Please leave your comments below and we will make the appropriate changes. Comments that have been addressed, by improving the documentation accordingly, will then be removed.

COMMENTS

By Raghu Sengar - 5:47 PM on Mar 06, 2013 Reply
This information about excluding properties is obsolete. It creates confusion and may lead to issues. Please update this information from the page: http://dev.day.com/docs/en/cq/current/developing/multi_site_manager_dev.html#Excluding%20Properties%20and%20Node%20Types%20from%20Synchronisation
By Raghu Sengar - 5:49 PM on Mar 06, 2013 Reply
Can you confirm if instructions to create custom rollout action is still valid or obsolete?

CREATING A NEW SYNCHRONISATION ACTION
By Anonymous - 9:52 PM on Mar 07, 2013 Reply
Hello,
I would appreciate it if you could let us know how the rank property is used in evaluation of the live actions in the rollout config. Is the order of the nodes used in assessing which live action gets executed first or does it use the rank property?

Thanks,
Banu
By Luc Feys - 10:53 PM on Mar 18, 2013 Reply
Hello,

I could not find any information about the possibility of a liveaction to terminate the rollout for a certain resource. I have a blueprint website of which certain parts of the content should be copied to several distinct livecopies based on certain conditions. If the conditions are not met, the content should not be copied to that specific livecopy. On the other hand, if the conditions are met, I would just want the default roll-out configuration to kick in.

I was wondering if it was possible to shortcircuit the whole roll-out configuration from a new custom liveaction in order to stop the default rollout (to copy the resource), based on the evaluation of my criteria.
Or is there another (better/recommended) way to achieve this kind of behaviour?

Thanks for any suggestions on this,

Luc
By balaji - 8:48 AM on Apr 15, 2013 Reply
Hi, I have created a blueprint on the en locale of Geometrix site, and then tried to create a live copy on the blueprint, however when selected the rollout config option, only the en page, which is the root is seen visible in the live copy site, all the other pages are visible, if I remove the rollout config option, then i can see the remaining pages. However we need the rollout config option. Could you all please guide me in creating a live copy with rollout config properly
Thanks,
Balaji

ADD A COMMENT

In order to post a comment, you need to sign-in.

Note: Customers with DayCare user accounts need to create a new account for use on day.com.