Thursday, March 12, 2020

MSM Rollout Handbook


Rollout Handbook

Managing Blueprints and Live Copies

MSM enables you to create a site (called a live copy) based on another site (called a blueprint) and to actively manage the relationships between the blueprint and the live copy. The blueprint makes it possible to define structure and content centrally. The structure and content of the blueprint can then be used in the live copy.    

Creating a Live Copy Based on an Existing Branch or Page

To create a live copy based on an existing branch or page:
  1. Open the Websites console.
  2. Select the Websites folder.
  3. Expand the New... menu and select New Live Copy...
  4. In the Source selection tab, define the live copy:
    • Title, the page title, e.g. My Geometrixx Live Copy
    • Name, the page (node) name, e.g. mygeometrixx_livecopy
    • Live Copy From: browse to define the blueprint, e.g. /content/geometrixx
    • Exclude sub pages: check this box to exclude the sub pages from the live copy.
  5. In the Sync config tab, set the rollout configuration (it is possible to define several configurations). The following configurations are available in the out-of-the-box version of CQ:
    • Standard rollout config
    • Activate on Blueprint activation
    • Deactivate on Blueprint deactivation
    • Push on modify
    • Geometrixx mobile rollout config
  6. Click Create.

 Creating a Blueprint

Using a blueprint has the following advantages:
  1. It defines the source.
  2. It makes it possible to inherit properties like default rollout configurations.
  3. It allows for pushing of modifications.
To create a blueprint:
  1. Open the Tools console.
  2. Select Tools, then MSM Control Center. Click New... in the top-middle toolbar.
  3. In the Create Page dialog, define the blueprint:
    • Title, the page title, e.g. My Blueprint
    • Name, the page (node) name, e.g. myblueprint
    • Select the Blueprint Template
Click Create.
  1. Open the newly created page and click the Edit button beside Settings.
  2. In the Blueprint Settings dialog, define the blueprint:
    • Name, the blueprint name that was defined earlier can be changed.
    • Description, e.g. This is my blueprint
    • Source Path: set the path of the blueprint, e.g. /content/geometrixx
    • Thumbnail Image (optional): this thumbnail will appear in the live copy creation.

Creating a Live Copy Based on a Blueprint

To create a live copy based on a blueprint:
  1. Open the Websites console.
  2. Select the Websites folder.
  3. Expand the New... menu and select New Site...
  4. In the Create Site dialog, define:
    • Title, the page title, e.g. My Geometrixx Live Copy
    • Name, the page (node) name, e.g. mygeometrixx_livecopy
    • Select the blueprint template and click Next.
  5. Select the languages and click Next.
  6. Select the chapters and click Next.
  7. Define:
    • Site Owner: choose an existing user. Note: The Site Owner entry is a descriptive property.
    • Live Copy: uncheck to create a simple copy of the site.
    • Rollout Configs: set the rollout configuration (it is possible to define several configurations). The following configurations are available in the out-of-the-box version of CQ:
      • Standard rollout config
      • Activate on Blueprint activation
      • Deactivate on Blueprint deactivation
      • Push on modify
      • Geometrixx mobile rollout config
  8. Click Next.
  9. Click Create Site.

Changing the System Default Rollout Configuration

The system default rollout configuration is set to: /etc/msm/rolloutconfigs/default. To change it:
  1. Go to the Configuration tab of the Web Console:
    http://localhost:4502/system/console/configMgr
  2. Open the Day CQ WCM Live Relationship Manager configuration window.
  3. In Default rollout config, set the path of the default rollout configuration.
  4. Click Save.

Setting a Rollout Configuration on a Live Copy Page

To set a rollout configuration on a live copy page:
  1. Open the page properties dialog of the live copy page. To do so, you can either:
    • Select the page in the SiteAdmin, edit the context menu and click Properties...
    • or, on the page, in the Page tab of the SideKick, click Page Properties...
  2. In the Page Properties dialog, select the Live Copy tab.
  3. Set the rollout configuration. The following default configurations are available in CQ:
    • Standard rollout config
    • Activate on Blueprint activation
    • Deactivate on Blueprint deactivation
    • Push on modify
    • Geometrixx mobile rollout config
  4. Click OK.

Setting a Rollout Configuration on a Blueprint Page

To set a rollout configuration on a blueprint page:
  1. Open the page properties dialog of the live copy page. To do so, you can either:
    • Select the page in the SiteAdmin, edit the context menu and click Properties...
    • or, on the page, in the Page tab of the SideKick, click Page Properties...
  2. In the Page Properties dialog, select the Blueprint tab.
  3. Set the rollout configuration. The following default configurations are available in CQ:
    • Standard rollout config
    • Activate on Blueprint activation
    • Deactivate on Blueprint deactivation
    • Push on modify
    • Geometrixx mobile rollout config
  4. Click OK.

Rollout Configurations Available in CQ

The following rollout configurations are defined in the out-of-the-box version of CQ and can be applied:
Configuration Name
Triggered when the Blueprint Page is
Performed Actions on the Live Copy
Standard rollout config
rolled out
contentUpdate
contentCopy
contentDelete
referencesUpdate
orderChildren
Activate on Blueprint activation
activated
targetActivate
Deactivate on Blueprint deactivation
deactivated
targetDeactivate
Push on modify
modified
contentUpdate
contentCopy
contentDelete
referencesUpdate
orderChildren
Geometrixx mobile rollout config
rolled out
contentUpdate
contentCopy
contentDelete
editProperties
referencesUpdate
orderChildren

Creating a Rollout Configuration

  1. Go to the Tools console.
  2. In the tree navigation panel, expand the folders Tools > MSM and select the folder Rollout Configurations.
  3. In the top middle toolbar, click New...
  4. In the Create Page dialog, define the page:
    • Title, the page title, e.g. My Rollout Configuration
    • Name, the page name (node name), e.g. myrolloutconfig
    • Select the RolloutConfig Template.
Click Create.
  1. Open the newly created configuration page.
  2. Edit the settings: click the Edit button beside Settings.
  3. In the Rollout Config dialog, define:
    • Name, the formerly defined page title.
    • Description, an informative description.
    • Sync Trigger, the blueprint page event that triggers the synchronisation actions. It can be one of the following values:
      • On Rollout: the synchronisation actions are performed when the blueprint page is rolled out.
      • On Modification: the synchronisation actions are performed when the blueprint page is modified. Be careful when choosing this option as it might cause a lot of network traffic.
      • On Activation: the synchronisation actions are performed when the blueprint page is activated.
      • On Deactivation: the synchronisation actions are performed when the blueprint page is deactivated.
Click OK to save the changes.
  1. Add the synchronisation actions to the rollout configuration. A synchronisation action is defined by a Java class; the name of the action needs to be defined in the Java class and needs to match the node name in the repository.
    Synchronisation actions need to be added with CRXDE:
    1. In CRXDE, navigate to the jcr:content node below the new configuration node, in this example: /etc/msm/rolloutconfigs/myrolloutconfig/jcr:content.
    2. Create the node that defines the action:
      • Name, the node name of the action: refer to the column 'Node Name' in the table Synchronisation Actions, e.g. workflow
      • Type: cq:LiveSyncAction
Click OK.
3.                   Add the following property to the action node:
      • Name, the property name of the action: refer to the column 'Property Name' in the table Synchronisation Actions, e.g. enabled
      • Type: String
      • Value, the property value of the action: refer to the column 'Property Value' in the table Synchronisation Actions, e.g. true
Click Add.
4.                   Click Save All to save the changes.
    1. Repeat the former steps to add more actions.
The new rollout configuration will now be available when setting rollout configurations on a blueprint or on a live copy page.

Synchronisation Actions

The following synchronisation actions are available in CQ and can be applied:
Title
Description
Action Name
Property Name
Property Value
Copy content
On the live copy, it copies the nodes that exist on the blueprint and that do not exist on the live copy
contentCopy
Enabled
true
Delete content
 On the live copy, it deletes the nodes that once existed on the blueprint and that do not exist on the blueprint anymore
contentDelete
Enabled
true
Update content
Updates the live copy content with the changes from the blueprint.
contentUpdate
Enabled
true
Edit properties
 On the live copy, it edits properties of the live copy: the selection of the properties and their transformation is done by setting a value to the editMap property. editMap needs to have the following format:
[property 1]#[current value (regex)]#[new value (regex)],...,[property x]#[current value (regex)]#[new value (regex)]
Example: setting editMap to:
sling:resourceType#/(contentpage|homepage)#/mobilecontentpage,cq:template#/contentpage#/mobilecontentpage
transforms the properties of live copy nodes as follows:
- all the sling:resourceType that are either set to contentpage or to homepage are set to mobilecontentpage and
- all the cq:template that are set to contentpage are set to mobilecontentpage
editProperties
 enabled
editMap
 true
String expression
Send a notification
Sends a page event that the page has been rolled out. In order to be notified, one needs to first subscribe to rollout events.
notify
Enabled
true
Order children
On the live copy, it orders the children (nodes), based on the order on the blueprint
orderChildren
Enabled
true
Update references
On the live copy, it updates the references (like links).
It searches for the paths in the live copy pages that point to a resource within the blueprint and replaces them with the paths to the related resource inside the live copy.
referencesUpdate
Enabled
true
Create version of source page
Creates a version of the blueprint
sourceVersion
Enabled
true
Create version of target page
Creates a version of the live copy
targetVersion
Enabled
true
Activate target page
Activates the live copy
targetActivate
Enabled
true
Deactivate target page
Deactivates the live copy
targetDeactivate
Enabled
true
Start target workflow
Starts the workflow that is defined by the target property (for pages only) and takes the live copy as payload.
workflow
Target
<workflow-path>
Set readonly ACLs on page structure and content to target group
Set read-only to group defined in the action config of the relationship (for pages only). Denied ACL are:
 * ActionSet.ACTION_NAME_REMOVE
 * ActionSet.ACTION_NAME_SET_PROPERTY
 * ActionSet.ACTION_NAME_ACL_MODIFY
mandatory
Target
<group ID>
Set readonly ACLs on page content to target group
Set read-ony to group defined in the action config of the relationship (for pages only). Denied ACL are:
 * ActionSet.ACTION_NAME_SET_PROPERTY
 * ActionSet.ACTION_NAME_ACL_MODIFY
mandatoryContent
Target
<group ID>
Set readonly ACLs on page structure to target group
Set read-ony to group defined in the action config of the relationship (for pages only). Denied ACL are:
 * ActionSet.ACTION_NAME_REMOVE
mandatoryStructure
Target
<group ID>

Managing a Blueprint and its Live Copies: the Blueprint Control Center

The Blueprint Control Center enables you to efficiently manage a blueprint and its live copies. You can define the blueprint, navigate to any blueprint page and view the status of all the related live copies. You can also filter, based on a path, the live copies that are displayed. A context menu enables you to perform all necessary actions on a page (like rolling out or restoring a page) and also to access information about the current state of a page.
To open the Control Center:
  1. Go to the Tools console.
  2. Double-click the MSM Control Center folder below Tools.
  3. Specify the blueprint path in the top left path field and click the refresh button.
  4. In the left panel, navigate to a blueprint page. The related live copy pages are displayed in the middle panel with a status icon.
    Note: navigating through the blueprint tree does not update the top left blueprint field.
  5. In the pathfield in the middle panel, specify the live copy path to filter the live copies and click the refresh button.
  6. On the top right, click Legend to display the status icons and their meanings.
The Blueprint Control Center looks as follows:

Managing Blueprints with the Control Center

When right-clicking a blueprint page (either in the left panel or in the first column of the central panel), the following context menu is displayed:
Open page
Opens the selected blueprint page.
Edit blueprint config
Opens a dialog to define the rollout configurations on the blueprint page:
  1. Click to open the dialog.
  2. Set the rollout configuration.
  3. Click OK to save the changes.
Rollout

Opens a dialog to define and perform the rollout:
  1. Click to open the dialog.
  2. Define:
    • Rollout Scope:
      • Rollout entire page: check to only roll out the page.
      • Rollout page and all sub pages: check to roll out the page and all the sub pages.
    • Background rollout: check to execute the rollout as a background task.
      For more information about configuring and managing background tasks, refer to the section Managing Background Tasks.
Click Next.
  1. Select the live copies on which the rollout will be performed: the top left check button enables you to select/unselect all live copies.
    Click Rollout to perform the rollout: a status icon indicates if the rollout was successful (green icon) or not (red icon).
    Click Audit log to view the errors that happened during the rollout process if the rollout was not successful. Click OK to go back to the rollout dialog.
  2. Click Close.

 

Edit Properties at Rollout Trigger


We can edit Properties of live copy by two ways :
1.      Use editProperties Synchronization action.
Example: setting editMap to:
sling:resourceType#/(contentpage|homepage)#/mobilecontentpage,cq:template#/contentpage#/mobilecontentpage
transforms the properties of live copy nodes as follows:
- all the sling:resourceType that are either set to contentpage or to homepage are set to mobilecontentpage and
- all the cq:template that are set to contentpage are set to mobilecontentpage
2. Change the live copy node values as per the blueprint site node values.
To do so:
  1. In your browser, open the Apache Felix Web Management Console Configuration (for example: http://localhost:4502/system/console/configMgr).
  2. In Configuration, select CQ WCM Rollout Manager.
  1. Configure these two parameters:
    • Excluded Properties: java regexes that define the property names to not copy. If the property name matches one regex, it will not be copied.
    • ExcludedNodetypes: java regexes that define the node types to exclude from rollout. If the node type matches one regex, it will not be included by the rollout manager.

Custom Workflow

              1. Write a custom class e.g. LoggerProcess given below.
package com.day.cq.workflow.impl.process;

import com.day.cq.workflow.WorkflowException;
import com.day.cq.workflow.WorkflowSession;
import com.day.cq.workflow.exec.WorkItem;
import com.day.cq.workflow.exec.WorkflowData;
import com.day.cq.workflow.exec.WorkflowProcess;
import com.day.cq.workflow.metadata.MetaDataMap;
import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Properties;
import org.apache.felix.scr.annotations.Property;
import org.apache.felix.scr.annotations.Service;
import org.osgi.framework.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.jcr.Node;
import javax.jcr.RepositoryException;
import java.util.Arrays;


@Component
@Service
@Properties({
        @Property(name = Constants.SERVICE_DESCRIPTION, value = "Logger process implementation."),
        @Property(name = Constants.SERVICE_VENDOR, value = "Adobe"),
        @Property(name = "process.label", value = "My Logger Process Workflow")})
public class LoggerProcess implements WorkflowProcess {

   private static final Logger log = LoggerFactory.getLogger(LoggerProcess.class);

    public void execute(WorkItem item, WorkflowSession session, MetaDataMap args) throws WorkflowException {

        log.info("---> This is my Custom Workflow");
    }
}
2.       Build it as a OSGI bundle and deploy it in the apache Felix.
3.       Make this bundle active.

Creating a Workflow

First, you must create your workflow. You can then apply an instance of this (version dependent) when managing your website.

Creating a New Workflow Model

The actual creation is a small step - a skeleton workflow (with 3 default steps) will be created.
1.     Open the Workflow console.
2.     From the Models tab, select New from the top navigation bar. The New Workflow dialog opens.
3.     Specify the Title for your workflow.
4.     Click OK to save and close the dialog. You return to the Models tab, where you see your new workflow in the list.

Editing a Workflow

When you create a new workflow, a skeleton workflow is created with a minimum of steps. For the workflow to become meaningful, you must edit it.
1.     Open the Workflow console.
2.     From the Models tab, select your workflow.
3.     Either click Edit or double-click the name of the workflow. A new web browser tab (named after the workflow) opens for editing and configuring the workflow.
  
The window contains the graphical representation of your workflow. Here you can position the steps and splits, edit the workflow name or description and save changes. The Save button is located above the diagram in a Workflow toolbar.
A Participant step Step 1 has been automatically added to your new workflow model. It is an example and must be edited, or replaced if required. Further steps can be added.
The available users and groups are listed in the left pane, from where they can be dragged into the workflow model as Participant steps, while the Sidekick offers the various available processes, which can be dragged into the workflow model to add Process steps.
Drag the Process Step as a Step 2 and open it.It looks similiar to the following:
    : Select the newly created Logger Workflow from the drop down.
4.     Save your model, then close the tab.

Starting a workflow from the Workflow console

·       Open the Workflow console.
·       From the Models tab select the required workflow.
·       Click Start from the top navigation.
·       The Start Workflow dialog opens allowing you to enter the payload and an optional title and comment.
Specify the payload (includes pages, nodes, resources, and so on) to which the workflow is to be applied. You can use the drop down menu to browse the repository when selecting:
 
·       Click OK to start a workflow instance with the properties you configured. Now the workflow is running.
Once a page has been linked to a workflow it will be indicated in the Status column in the Websites console:
·        

 

Selecting a Participant Step to take action

Before you can take any action on a Participant step, you need to select it:
1.     Open the Inbox console to see when an action is assigned to you. This occurs when a workflow reaches a Participant step with your account, or group, specified:
 
2.     Select the entry.

Completing a Participant step

After you have taken the action indicated you can complete the workflow step, thus allowing the workflow to continue.
1.     Click the Complete button in the top navigation bar.
2.     In the resulting dialog, select the Next Step; that is, the step to execute next. A drop down list shows all appropriate destinations. A Comment can also be entered.
 
The number of steps listed depends on the design of the workflow model.
3.     Click OK to confirm the action.

 

 

 

 

 

 

 

 

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 to change jcr:title, sling:resourceType and cq:template in your own action.
·       Build the bundle of this package and deploy the bundle in apache Felix.
·       Add the newly created action name (e.g. myActionName) in your custom rollout configuration node.
·       Create a live copy of the blueprint site or existing site, live copy site will have its changed jcr:title, sling:resourceType and cq:template as per the respective changed values defined in the code.

 

 

 

 




Posted by at
Labels: , , , , ,

No comments:

Post a Comment

Please do not enter any spam link in the comment box.

Subscribe to: Post Comments (Atom)