Working with Workflows

You are reading the CQ 5.3 version of Working with Workflows.
This version has reached End of core support. For further details see our technical support periods.
This documentation is also available for the following versions: Adobe Experience Manager 5.6.1  AEM 5.6  CQ 5.5  CQ 5.4 

CQ5 encompasses several applications that are designed to interact and complement each other. In particular, the Workflow Engine can be used in tight conjunction with several of the other applications.

For example, within CQ5, Web Content Management (CQ WCM) is key. This enables you to generate and publish pages to your website. This functionality is often subject to organizational processes, including steps such as approval and sign-off by various participants. These processes can be represented as workflows, which in turn can be defined within CQ, then applied to the appropriate content pages.

This section covers using Workflows to:

  • create and edit a new workflow

  • start an instance of the workflow by applying it to a page of content

  • complete a step requiring user action

  • take additional actions on a workflow; for example, suspend, resume, terminate

  • monitor workflow instances

  • investigate the history of archived workflows (which have finished, or been terminated)

  • automatically launch workflows when nodes within the repository are modifed (for example, to load digital assets)

Authorization needed for working with Workflows

Actions on workflows can only be undertaken if:

  • you are working with the admin account

  • the account has been assigned to the default group workflow-users, which holds all the privileges necessary for your users to perform workflow actions.

The Workflow Console

The Workflow console is the centralized location for workflow management in CQ. It can be accessed via the main tab icon:

Note

Workflows can also be started from the Workflow... menu item, the drop-down menu on a page item, and from the sidekick when editing a page)

file

Within the console there are 5 tabs:

Poweruser_Console_Models
Inbox
  • Lists workflows awaiting action in your inbox. You can then take action as required.

  • Models
  • Lists the workflow models currently available. Here you can create, edit or delete workflow models.

  • Instances
  • Shows you details of workflow instances which are currently active. These instances are also version dependent.

  • Archive
  • Enables you to access details of workflow instances which have terminated, for whatever reason.

  • Launcher
  • Allows you to define a workflow to be launched if a specific node has been updated.

  • The types of Workflow Steps available

    To build your workflow CQ provides various step types which can be combined, and extended with scripts to provide the functionality and control you require.

    Participant Step

    A participant step enables you to assign ownership for a particular action. The workflow will only proceed when the user has manually acknowledged the step. This is used when you want someone to take an action on the workflow; for example, a review step.

    Although not directly related, user authorization must be considered when assigning an action; the user must have access to the page.

    file

    The following properties are available:

    Description

    A description of the step.

    Email notification

    You can notify participant(s) by sending them an email when the workflow reaches the step.

    If set to On, an email will be sent to the user defined by the property User/Group or to each member of the group if a group is defined.

    Pre-requisites:

    • The user(s) needs to have a valid email address defined in his profile.
    • The Mail Service needs to be properly configured: to configure the Mail Service, refer to the OSGI Configuration section.

    The default mail template is located in the repository at /etc/workflow/notification/email/default/en.txt. A mail template can be defined for another language by creating a file named <language>.txt at /etc/workflow/notification/email/default. The mail template used for the notification is the one that corresponds to the user language settings. The mail template is a properties file with 4 properties: subject, header, message and footer. The substitution keywords ${name} are filled in by the workflow notification service.

    Note: The workflow initiator is always notified when:

    • The workflow is completed (finished).
    • The workflow is aborted (terminated).

    Form path

    The path of the form that is associated with the step. It enables you to build processes in which visitors will input information based on multiple forms; for example, an online registration process. For more information refer to the Workflows and Forms section.

    Timeout

    The period after which the step will be "timed out". You can select between Off, Immediate, 1h, 6h, 12h, 24h.

    Timeout Handler

    The handler which will control the workflow when the step times out; for example com.day.cq.workflow.timeout.autoadvance.AutoAdvancer.

    Title

    You can enter your own title for the step.

    Type

    Defines the step type. You can change this if required, though only parameters which exist for the new type will retain the values you have already defined.

    User/Group

    A drop down selection box will allow you to navigate and select a user or group.

    If you assign the step to a specific user, then only this user can take action on the step.

    If you assign the step to an entire group, then when the workflow reaches this step all users in this group will have the action in their Workflow Inbox.

    See Delegating a Participant Step for more information on how this can affect your workflow.

    Process Step

    A process step allows you to specify scripts to be executed.

    This is used when you want automated processing to occur; for example to trigger an external application.

    The following properties are available:

    Description
  • A description of the step.

  • Handler Advance
  • If true a handler will automatically advance the workflow to the next step after execution. If false, the implementation script must handle this.

  • Implementation
  • You can select the script to be executed from a drop down list.

  • Process Arguments
  • You can define arguments to be passed to the process.

  • Timeout
  • The period after which the step will be "timed out". You can select between Off, Immediate, 1h, 6h, 12h, 24h.

  • Timeout Handler
  • The handler which will control the workflow when the step times out; for example com.day.cq.workflow.timeout.autoadvance.AutoAdvancer.

  • Title
  • You can enter your own title for the step.

  • Type
  • Defines the step type. You can change this if required, though only parameters which exist for the new type will retain the values you have already defined.

  • Built-in Process Steps

    CQ provides a number of predefined workflow process steps that you can use to build your own workflow models. See Workflow Processes.

    Container Step

    A container step enables you to connect workflows, by referencing a child workflow.

    This can allow you to reuse a workflow (or sub-workflow); for example a translation process which is used in multiple editing workflows.

    The following properties are available:

    Description
  • You can enter a description of the step.

  • Sub Workflow
  • This references a sub workflow.

  • Timeout
  • The period after which the step will be "timed out". You can select between Off, Immediate, 1h, 6h, 12h, 24h.

  • Timeout Handler
  • The handler which will control the workflow when the step times out; for example com.day.cq.workflow.timeout.autoadvance.AutoAdvancer.

  • Title
  • You can enter your own title for the step.

  • Type
  • Defines the step type. You can change this if required, though only parameters which exist for the new type will retain the values you have already defined.

  • AND Split

    An AND Split creates a split in the workflow; both branches will be active. This enables you to introduce multiple processing paths into the workflow; for example allowing certain review steps to occur in parallel, thus saving time.

    Selecting this will add two branches to the workflow, each with a Participant step:

    After creating such an instance you must edit both of the New Step instances. You can then add extra process, participant or container steps to either branch as required.

    To delete an AND Split, click the delete icon that appears when you position your mouse over the branch split (or join):

    OR Split

    Create a split in the workflow, whereby only one branch is active. This allows you to introduce conditional processing paths into your workflow.

    Selecting this adds two branches to the workflow, with a New Step in each branch:

    The edit icons on each branch allow you to define when this branch is used:

    You can define:

    Default Route
  • You can define which branch is followed if no rules have been defined on either branch, or neither are fulfilled. You cannot set both branches to the same value.

  • Rule
  • Here you can define the path to a script that contains the logic controlling whether a particular branch will be activated.

    For example, if you reference the sample script /etc/workflow/scripts/rule-false.ecma then false will always be returned:

    function check() { return false; }
  • After creating such an instance you must edit both of the New Step instances. You can then add extra process, participant or container steps to either branch as required.:

    As with AND Split, to delete an OR Split click the delete icon that appears when you position your mouse over the branch split (or join).

    Creating a Workflow

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

    Note

    Actions on workflows can only be undertaken if you are either working with the admin account or an account that has been assigned to the workflow-users default group, which holds all the privileges necessary for your users to perform workflow actions.

    For simplicity, the following examples have all been made using the admin account.

    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 tab (named after the workflow) opens for editing and configuring the workflow. This shows 3 panes:

      • Toolbox

        Lists the Step and Split types. Click to display the appropriate list, then use drag the element you want into the appropriate position to build your workflow.

        A complete explanation of all types of workflow steps and splits, together with their related properties, can be found in The types of Workflow Steps available.

      • Workflow Model

        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 also located here, as is the Model Version. The Model Version is incremented every time the workflow model is updated. This is reflected in the monitoring displays. As multiple versions of a workflow can be in use at any one time, this helps you track the version being used in each instance.

      • Properties

        Allows you to edit properties of the individual steps and splits.

        A complete explanation of all types of workflow steps and splits, together with their related properties, can be found in The types of Workflow Steps available.

      Three steps have already been created:

      Start
      • A mandatory step to start the workflow. This cannot be edited, nor deleted.
      Step1
      • A Participant step which is an example. This must be edited, or replaced if required. Further steps can be added.
      End
      • A mandatory step for every workflow. The End step is used to cleanly terminate the workflow, or to pass control back to the parent workflow in the case of a child (sub-) workflow.

      You can either define a full workflow, or a sub-section of a workflow. Sub-workflows can then be referenced by other workflows to form part of a complete workflow. This simplifies the construction of complex workflows, and also allows you to reuse sub-workflows which occur repeatedly.

    4. Enter a Model Description for the workflow (you can also edit the Model Title) from the center pane. Click on the field to enter edit mode.

    5. You can now design your workflow by dragging steps onto the Workflow Model, then configuring the properties.

    6. When finished, Save your model, then close the tab.


    Example

    To illustrate some of the possibilities for creating a workflow, the following example emulates a variation of the Publish Example workflow.

    1. Edit Step 1 using on the step itself.

      1. Enter Validate Content for the Title and Description.

      2. Set the User/Group to admin.

      3. Set the Timeout to Off and Timeout Handler empty.

    2. Click Splits to display the list of split types.

    3. Drag an Or Split onto the workflow and position it between Validate Content and End.

      An Or Split is added to your workflow.

    4. Edit the left-hand branch:

      1. Click the icon on the actual branch.

      2. Set Default Route to true.

      3. Click the icon on New Step in the left-hand branch. This will be a Participant step.

      4. Enter Cancel Publish for the Title and Description.

      5. Set the User/Group to admin.

    5. Edit the right-hand branch:

      1. Click the icon on the actual branch.

      2. Set Default Route to false.

      3. Leave the Rule empty. This is for demonstration purposes.

      4. Click the icon on New Step in the right-hand branch. Change this from a Participant to a Process step; the properties available will be updated.

      5. Enter Publish Page for the Title and Description.

      6. Set the Handler Advance to false.

      7. Select com.day.cq.wcm.workflow.process.ActivatePageProcess as the Implementation script. This implementation will publish the selected page to the publisher instances.

    6. Now you have specified all steps in your workflow, click Save.

    7. Finally close the tab and return to the main console.

    Using the Workflow

    After you have defined your workflow you will want it to be used when managing your website. The following sections detail the different tasks when using workflows.

    Starting the workflow for an individual page

    There are two methods of starting a workflow; from the Workflow Console or the Websites tab:

    In either case you need to link a workflow to its payload. The payload (including pages, nodes, resources) will then be subject to this instance of the workflow.

    The current version of the workflow model is assigned; if the main copy of the workflow is updated later then the changes will have no impact on the instance assigned.

     

     

      Starting a workflow from the workflow console
    1. Open the Workflow console.

    2. From the Models tab select the required workflow.

    3. Click Start from the top navigation.

    4. The Start Workflow dialog opens allowing you to enter the payload and a 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:

    5. Click OK to save your selection and start the workflow. Now the workflow is running.

      Starting a workflow from the sidekick
    1. Open the Websites tab.

    2. Open the required page.

    3. Select the Workflow tab from the sidekick.

    4. Expand the Workflow dialog, allowing you to select the Workflow and a enter a Comment.

    5. Click Start Workflow to save your selection and start the workflow. Now the workflow is running.

    Once a page has been linked to a workflow it will be indicated in the Websites tab:

    Taking actions on a participant step

    Any participant steps that you have created will be assigned to the specific user or group, who will need to take action:

    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 Workflow console.

    2. Select the Inbox tab to see when an action is assigned to you. This occurs when a workflow reaches a Participant step with your account, or group, specified:

    3. 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.

    3. Click OK to confirm the action.

    Delegating a Participant Step

    If a step has been assigned to you, but for any reason you are unable to take action, you can delegate the step to another user or group.

    1. Click the Delegate button in the top navigation bar.

    2. In the resulting dialog, select the User you want to pass the action to.

      A drop down list shows all appropriate users.

      If the step has been defined with one user, then only this user will be available - the step cannot be delegated to anyone else.

      If a group has been defined, then the list shows the group itself and all individual users within the group. You can delegate to either the entire group, or an individual user within that group.

      A Comment can also be entered.

    3. Click OK to confirm the action.

    Performing Step Back on a Participant step

    If you discover that a step, or series of steps, needs to be repeated you can step back. This allows you to select a step that occurred earlier in the workflow for reprocessing. The workflow returns to the step you specify, then proceed from there.

    1. Click the Step Back button in the top navigation bar.

    2. In the resulting dialog, select the Previous Step; that is, the step to execute next - even though it is a step that occurs earlier in the workflow. A drop down list shows all appropriate destinations.

      The number of previous steps available in the list depends on the design of the workflow.

    3. Click OK to confirm the action.

    Suspending, Resuming, and Terminating a Workflow Instance

    Aside from workflow instances that require your immediate action and show up in your Workflow Inbox, you can perform certain other actions on running workflow instances.

    1. Open the Workflow console.

    2. Select the Instances tab. You will see a list of active (neither finished, nor terminated) workflow instances.

    3. Select an entry.

    4. To suspend the workflow, click the Suspend button in the navigation bar. The State changes to Suspended. This can be helpful in exceptional cases when you do not want the workflow to proceed; for instance for maintenance.

    5. While a workflow is suspended, you can then click Resume. This restarts the workflow from where it was suspended, with the same configuration. Again the State is updated.

    6. To finally terminate the workflow, click Terminate. This immediately ends the workflow execution - the state changes to ABORTED. A terminated workflow instance cannot be restarted.

    The Instances tab is not only useful for taking action on running workflows, you can also use it to monitor workflow instances, without necessarily modifying them.

    Monitoring the Status of Workflow Instances

    A workflow can have one of the following status:

    • RUNNING: the workflow instance is running.
    • COMPLETED: the workflow instance has been successfully ended.
    • SUSPENDED: the workflow instance has been suspended.
    • ABORTED: the workflow instance has been terminated.
    • STALE: no workitem is currently attached to the workflow instance.

    To monitor the status of workflow instances, you can use the Instances or Archive tabs.

    Instances tab
  • Shows all running instances.

  • Archive tab
  • Shows terminated workflow instances.

  • Monitoring Workflows in progress

    From the Instances tab you can see the status of a Workflow in progress. A list of the active Models is shown; in this case RUNNING:

    With the Instances tab you can take various actions (see Suspending, Resuming, and Terminating a Workflow instance) and also Open History to show the actions executed to date on the workflow instance:

    Archived Workflows

    After a Workflow instance has finished, for whatever reason (terminated, as below, or after successful completion), it can (only) be seen in the Archive tab:

    As the workflow has already completed, no further action can be taken on these instances.

    However, if you need further details of a completed workflow you can use Open History.

    Using the Workflow Launcher for Node Modifications

    The Workflow Launcher, provides one component to monitor all changes in the content repository and launch workflows dependent on the location and resource type of the changed node.

    Using the Launcher tab you can:

    • see the workflows already launched for specific nodes.

    • select a workflow to be launched when a certain node/node-type has been modified.

    • remove an existing workflow-to-node relationship.

    Various definitions are included with the standard installation. These are used for digital asset management and social collaboration tasks:

    Workflow_Launcher_tab

    Adding a Launcher relationship

    1. Open the Workflow tab.

    2. Select the Launcher tab.

    3. Click Add... and configure the new workflow-to-node relationship as required:

      Event Type
    4. Define the event type that will launch the workflow:

      • Created

      • Modified

      • Removed

    5. Nodetype
    6. Select the nodetype from the drop down list.

    7. Path
    8. Define the path for which the launch entry is to be applied.

    9. Condition
    10. Define any conditions which may apply on node property values.

      For example, to check whether a node has a property name holding the value User specify name==User.

    11. Workflow
    12. The workflow to be launched when the Event Type occurs on the Nodetype and/or Path under the defined Condition.

    13. Description
    14. A description for the relationship.

    Removing a Launcher relationship

    1. Open the Workflow tab.

    2. Select the Launcher tab.

    3. Click on the entry you want to remove.

    4. Click Remove.

     

    Workflows and Forms

    With CQ you can associate a workflow with forms. It enables you to build processes in which visitors will input information based on multiple forms; for example, an online registration process.

    In this section you will create a two step process to display two characteristics of the "Product of the Day". In the first step, the author will fill out the first form to define the name of the product. In the second step, the author will fill out the second form and specify the designer of the product. The result will be displayed in the Product of the Day page.

    Create the Product of the Day page

    To create the Product of the Day page:

    1. Go to the Websites console.
    2. Create the Product of the Day page below /content/geometrixx/en/products with the following characteristics:
      Title: Product of the Day
      Template: Geometrixx Content Page
    3. Open the new page and create the following paragraphs by using the Text component from the General tab of the Sidekick:
      • the first paragraph displays: Name
      • leave the second paragraph empty
      • the third paragraph displays: Designed by
      • leave the last paragraph empty
      The page looks as follow:


    Create the first form (form1)

    To create the first form (form1):

    1. Go to the Websites console.
    2. Create the page form1 below /content/geometrixx/en/products with the following characteristics:
      • Title: form1
      • Template: Geometrixx Content Page
      Note: the form pages can be created anywhere.
    3. Open form1 and drag the Form component from the Form tab in the Sidekick.
    4. Edit the Form component and set the following parameters to link the form to a workflow:
      • set the Action Type to Edit Workflow Controlled Resource(s)
      • set the Form Identifier to form1.
      Click OK.
      Note: the Form Identifier can be set to any name except form.
    5. Drag the Text Field component from the Form tab in the Sidekick to between the Start and the End bars of the Form component.
    6. Edit the Text Field component:
      • set the Element Name to ./jcr:content/par/text_0/text
      • set the Title to Product Name:
      Click OK.
      Note: through the previous setting, the property <payload-path>/jcr:content/par/text_0/text will be overwritten with the value entered through the form when the form is submitted.
    7. Drag the Workflow Submit Button(s) component from the Form tab in the Sidekick to immediately after the Text Field component.
      Note: this component features the submit button of the form.
      The form1 page looks as follows:

    Create the second form (form2)

    To create the second form (form2):

    1. Go to the Websites console.
    2. Create the page form2 below /content/geometrixx/en/products with the following characteristics:
      • Title: form2
      • Template: Geometrixx Content Page
      Note: the form pages can be created anywhere.
    3. Open form2 and drag the Form component from the Form tab in the Sidekick.
    4. Edit the Form component and set the following parameters to link the form to a workflow:
      • set the Action Type to Edit Workflow Controlled Resource(s)
      • set the Form Identifier to form2.
      • in the Action Configuration tab, set the Redirect Page to {payload}.html to redirect to the payload page when this form is submitted.
      Click OK.
      Note: the Form Identifier can be set to any name except form.
    5. Drag the Text Field component from the Form tab in the Sidekick to between the Start and the End bars of the Form component.
    6. Edit the Text Field component:
      • set the Element Name to ./jcr:content/par/text_2/text
      • set the Title to Developer Name:
      Click OK.
      Note: through this setting, the property <payload-path>/jcr:content/par/text_2/text will be overwritten with the value entered through the form when the form is submitted.
    7. Drag the Workflow Submit Button(s) component from the Form tab in the Sidekick to immediately after the Text Field component.
      Note: this component features the submit button of the form.
      The form2 page looks as follows:

    Create the workflow

    To create the workflow:

    1. Go to the Workflow console.
    2. In the Models tab, create a new workflow model and call it Product of the Day.
    3. Edit the new workflow.
    4. Add a Participant Step after the Step 1.
    5. Edit the properties of Step 1 and set the Form path to /content/geometrixx/en/products/form1 to associate the payload to the form1.
    6. Edit the properties of the New Step (second step):
      • set the Form path to /content/geometrixx/en/products/form2 to associate the payload to the form2.
      • set User/Group to admin
    7. Save the workflow model.
      The workflow looks as follows:

    Apply the workflow to the page Product of the Day

    To apply the workflow to the Product of the Day page:

    1. Go to the page Product of the Day and refresh it.
    2. In the Sidekick, in the Workflow tab, select the workflow Product of the Day. Click Start Workflow.
    3. Go to the Workflow console, select the Inbox tab and refresh the page. 
    4. Click the payload link.
    5. The form1 page opens in publish mode. Enter the product name (for example Dream Car) in the Text Field and click Next.
    6. The form2 page opens in publish mode. Enter the product designer (for example Neo) and click finish.
    7. The page Product of the Day opens and displays the information that you have entered through the two step process.
      The page looks as follows:

    Workflow Packages

    Workflow packages are packages that can be passed to a workflow for processing.

    A workflow package:

    • contains links to a set of user-specified resources (such as pages, assets).
    • holds package information such as the creation date, the user that created the package and a short description.
    • is defined using a specialized page template; such pages allow the user to specify the resources in the package.
    • can be used multiple times.
    • can be changed by the user (add or remove resources) while the workflow instance is actually running.

    Creating a Workflow Package

    1. Open the Tools console.
    2. Navigate to Workflow, then Workflow Packages in the left pane.
    3. Create a New Page...; assign a name of your choice and select the Workflow Package Template.
    4. Open the new page:
    5. For each resource add an instance of the Resource Definition component. Then either drag resources from the content finder, or edit the component to select a resource:

    Using the Workflow Package in a Workflow

    After creating the workflow package page you can apply a workflow. This marks all resources as being subject to the workflow (assets and pages). The workflow will only take action on the resources listed, not on the definition page itself.

    1. Open the workflow package page.
    2. Select the Workflow tab from the sidekick.
    3. Select the required workflow.
    4. Click Start Workflow.
      From the Workflow console you can see the workflow running, with the workflow package page as Payload.

    For example, if you:

    • add new paragraphs to the Geometrixx Support and Product pages
    • create a workflow package holding the Geometrixx Support and Product pages as resources
    • apply the Publish Example workflow to this workflow package page
    • Complete the Validate Content step

    Both the Support and Product pages will be published by the same workflow instance.

    Note

    You must select a workflow that has been developed for use with workflow packages. For example in Geometrixx, Publish Example, Request for Activation or Request for Deactivation.

    Updating a Package While the Workflow is running

    Addtional resources can be added to a workflow package page even while a workflow is running:

    1. Create a workflow package page.
    2. Add resources to the page.
    3. Start a workflow for the package.
      Using the Websites console, confirm that the Status of the resources indicate they are in a workflow.
    4. Edit the workflow package page to add new resources.
      Using the Websites console, confirm that the Status of the new resources indicate that they are also in the workflow.