Working with Workflows

CQ 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, a key application of CQ is Web Content Management (CQ WCM), which 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.

Workflows are at the center of how form submissions in CQ WCM are typically processed. When creating a new form, the form submission can be easily associated with a workflow model, for example to store the content in a particular location of the repository or to notify a user about the form submission and its content.

file

Many useful workflow models are provided as part of CQ's default installation. In addition, any number of custom workflow models, tailored to the specific needs of your project, can be defined using the Workflow console.

Workflow models consist of a series of steps. When a workflow is started, that new workflow instance, associated with its payload, for example the data that was submitted in a form, advances through these steps. Such workflows can pass through automated Process steps or manual Participant steps, and can follow rules (AND/OR splits and joins) as well as trigger Container sub workflows.

Authorization needed for working with Workflows

Actions on workflows can only be undertaken if either:

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

Workflow Console

The Workflow console is the centralized location for workflow management in CQ. It can be accessed via the Workflows link on the CQ Welcome page. 

Note

The Welcome page also offers access to the Inbox, which lists workflows awaiting action and allows you to take action as required. Workflow related functionality is also made available elsewhere in CQ, in the drop-down menus, in dialog windows, and from the sidekick when editing a page.

file

Within the console there are 4 tabs:

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

Workflow Models

Workflow models consist of a series of steps of various types which can be 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.

Please refer to Configuring Email Notification to configure email notifications in CQ.

Note: The workflow initiator is always notified when:

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

Note

A few settings need to be configured in order to be notified by email. It is also possible to customize the email template or to add an email template for a new language. Please refer to Configuring Email Notification to configure email notifications in CQ.

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.

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.

    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.

    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.

      file

      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.

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

    5. 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 a workflow instance

    There are several ways a workflow can be started; from a form submission, from the Workflow Console, from the Websites Console, or from the workflow tab in the Sidekick.

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

    At that point, 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 already assigned instance.

    Using workflows to process form submissions

    1. Open the Websites console.

    2. Open the page on which you want add the form.

    3. Drag a Form component from the Components tab in the Sidekick and place it in the page.

    4. Edit the Start of Form component that appeared in the page.

    5. Select the desired workflow from the available options under Start Workflow.

      file
    6. Click OK to confirm the new form configuration.

    The form is now configured to be processed by the selected workflow. When users submit the form, a new workflow instance will be created, with the data of the form submission as its payload.

    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 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:

      file
    5. Click OK to start a workflow instance with the properties you configured. Now the workflow is running.

    Starting a workflow from the sidekick

    1. Open the Websites console.

    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 optionally enter Workflow Title and Comment.

      file
    5. Click Start Workflow to start a new 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:

    file

    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 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:

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

      file

      The number of steps listed depends on the design of the workflow model.

    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.

      file
    3. Click OK to confirm the action.