DocumentationAEM 6.4Developing Guide

Creating Workflow Models creating-workflow-models

Last update: Wed May 03 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.
CAUTION
For use of the classic UI, please see the AEM 6.3 documentation for reference.

You create a workflow model to define the series of steps executed when a user starts the workflow. You can also define model properties, such as whether the workflow is transient or uses multiple resources.

When a user starts a workflow, an instance is started; this is the corresponding runtime model, created when you Sync your changes.

Creating a New Workflow creating-a-new-workflow

When you first create a new workflow model it contains:

  • The steps, Flow Start and Flow End.

    These represent the beginning and end of the workflow. These steps are required and cannot be edited or removed.

  • An example Participant step named Step 1.

    This step is configured to assign a work item to the workflow initiator. Edit or delete this step, and add steps as required.

To create a new workflow with the editor:

  1. Open the Workflow Models console; by way of Tools, Workflow, Models or, for example:

    http://localhost:4502/aem/workflow

  2. Select Create, then Create Model.

  3. The Add Workflow Model dialog box appears. Enter the Title and Name (optional) before selecting Done.

  4. The new model is listed in the Workflow Models console.

  5. Select your new workflow, then use Edit to open it for configuration:

    wf-01

NOTE
If creating models programmatically (using a crx package) you can also create a sub-folder within:
/var/workflow/models
For example, /var/workflow/models/prototypes
This folder can then be used for managing access to the models in that folder.

Editing a Workflow editing-a-workflow

You can edit any existing workflow model to:

Editing a Default or Legacy (out-of-the-box) workflow has an additional step, to ensure that a safe copy is taken prior to your changes being made.

When updates to your workflow are complete you must use Sync to Generate a Runtime Model. See Sync your Workflow for details.

Sync your Workflow - Generate a Runtime Model sync-your-workflow-generate-a-runtime-model

Sync (right in the editor toolbar) generates a runtime model. The runtime model is the model actually used when a user starts a workflow. If you do not Sync your changes, then the changes will not be available at runtime.

When you (or any other user) make any changes to the workflow you must use Sync to generate a runtime model - even when individual dialogs (for example, for steps) have had their own save options.

When the changes are synchronized with the runtime (saved) model, Synched is shown instead.

Some steps have mandatory fields and/or built in validation. When these conditions are not satisfied an error will be shown when you attempt to Sync the model. For example, when no participant has been defined for a Participant step:

wf-21

Editing a Default or Legacy Workflow for the First Time editing-a-default-or-legacy-workflow-for-the-first-time

When you open a Default and/or Legacy model for editing:

  • The Steps browser is not available (left side).

  • There is an Edit action available in the toolbar (right side).

  • Initially the model, and its properties, is presented in read-only mode as:

    • Default workflows are located in /libs
    • Legacy workflows are located in /etc

Selecting Edit will:

  • take a copy of the workflow into /conf
  • make the Steps browser available
  • enable you to make changes
NOTE
See Locations of Workflow Models for further information.

wf-22

Adding a Step to a Model adding-a-step-to-a-model

You will need to add steps to your model to represent the activity to perform - each step performs a specific activity. A selection of step components are available in a standard AEM instance.

When you edit a model, the available steps appear in the various groups of the Steps browser. For example:

wf-10

NOTE
For information about the primary step components that are installed with AEM, see Workflow Steps Reference.

To add a step to a model:

  1. Open an existing workflow model for editing. From the Workflows Model console, select the required model, then Edit.

  2. Open the Steps browser; using Toggle Side Panel, at the far left of the top toolbar. Here you can:

    • Filter for specific steps.
    • Use the drop down selector to limit the selection to a specific group of steps.
    • Select the Show Description icon wf-stepinfo-icon to show more details about the appropriate step.

    wf-02

  3. Drag the appropriate step(s) to the required location in the model.

    For example, a Participant Step.

    After it is added to the flow you can configure the step.

    wf-03

  4. Add as many steps, or other updates, as required.

    At run time, steps are executed in the order in which they appear in the model. After adding step components, you can drag them to a different location in the model.

    You can also copy, cut, paste, group or delete existing steps; as with the page editor.

    Split steps can also be collapsed/expanded using the toolbar option: wf-collapseexpand-toolbar-icon

  5. Confirm the changes with Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

Configuring a Workflow Step configuring-a-workflow-step

You can Configure and customize the behavior of a workflow step using the Step Properties dialog boxes.

  1. To open the Step Properties dialog box for a step either:

    • Tap the step in the workflow model and select Configure from the component toolbar.
    • Double-click on the step.
    note note
    NOTE
    For information about the primary step components that are installed with AEM, see Workflow Steps Reference.

  2. Configure the Step Properties as required; the properties available depend on the step type, there may also be several tabs available. For example, the default Participant Step, present in a new workflow as Step 1:

    wf-11

  3. Confirm your updates with the tick.

  4. Confirm the changes with Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

Creating a Transient Workflow creating-a-transient-workflow

You can create a Transient workflow model when creating a new model, or by editing an existing one:

  1. Open the workflow model for editing.

  2. Select Workflow Model Properties from the toolbar.

  3. In the dialog box, activate Transient Workflow (or deactivate if required):

    wf-07

  4. Confirm the change with Save & Close; followed by Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

NOTE
When you run a workflow in transient mode AEM does not store any workflow history. Therefore, Timeline does not display any information related to that workflow.

Make workflow models available in Touch UI make-workflow-models-available-in-touchui

If a workflow model is present in Classic UI, but missing in the selection popup menu in the Timeline rail of Touch UI, then follow the configuration to make it available. The following steps illustrates using the workflow model called Request for Activation.

  1. Confirm that the model is not available in Touch-enabled UI. Access an asset using /assets.html/content/dam path. Select an asset. Open Timeline in left rail. Click Start Workflow and confirm that the Request for Activation model is not present in the popup list.

  2. Navigate through Tools > General > Tagging. Select Workflow.

  3. Select Create > Create Tag. Set Title as DAM and Name as dam. Select Submit.
    Create tag in workflow model

  4. Navigate to Tools > Workflow > Models. Select Request for Activation, then select Edit.

  5. Select Edit , then open Workflow Model Properties. Go to the Basic tab.

  6. Add Workflow : DAM to Tags field. Confirm the selection with the check (tick).

  7. Confirm the addition of the tag with Save & Close.
    Edit Page Properties of Model

  8. Complete the process with Sync. The workflow is now available in the Touch-enabled UI.

Configuring a Workflow for Multi Resource Support configuring-a-workflow-for-multi-resource-support

You can configure a workflow model for Multi Resource Support when creating a new model, or by editing an existing one:

  1. Open the workflow model for editing.

  2. Select Workflow Model Properties from the toolbar.

  3. In the dialog box, activate Multi Resource Support (or deactivate if required):

    wf-08

  4. Confirm the change with Save & Close; followed by Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

Configuring Workflow Stages (that show Workflow Progress) configuring-workflow-stages-that-show-workflow-progress

Workflow Stages help visualize the progress of a workflow when handling tasks.

CAUTION
If workflow stages are defined in Page Properties, but not used for any of the workflow steps, then the progress bar will not show any progress (regardless of the current workflow step).

The stages to be available are defined in the workflow models; existing workflow models can be updated to include stage definitions. You can define any number of stages for the workflow model.

To define Stages for your workflow:

  1. Open your workflow model for editing.

  2. Select Workflow Model Properties from the toolbar. Then open the Stages tab.

  3. Add (and position) your required Stages. You can define any number of stages for the workflow model.

    For example:

    wf-08-1

  4. Click Save & Close to save the properties.

  5. Assign a stage to each of the steps in the workflow model. For example:

    wf-09

    A stage can be assigned to more than one step. For example:

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2
    Step Stage
    Step 1 Create
    Step 2 Create
    Step 3 Review
    Step 4 Approve
    Step 5 Approve
    Step 6 Complete

  6. Confirm the changes with Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

Exporting a Workflow Model in a Package exporting-a-workflow-model-in-a-package

  1. Create a new package using the Package Manager:

    1. Navigate to the Package Manager by way of Tools, Deployment, Packages.
    2. Click Create Package.
    3. Specify the Package Name, and any other details as required.
    4. Click OK.

  2. Click Edit on the toolbar of your new package.

  3. Open the Filters tab.

  4. Select Add Filter and specify the path of your workflow model design:

    /conf/global/settings/workflow/models/<*your-model-name*>

    Click Done.

  5. Select Add Filter and specify the path of your runtime workflow model:

    /var/workflow/models/<*your-model-name*>

    Click Done.

  6. Add additional filters for any custom scripts that are used by your model.

  7. Click Save to confirm your filter definitions.

  8. Select Build from the toolbar of your package definition.

  9. Select Download from the package toolbar.

Using Workflows to Process Form Submissions using-workflows-to-process-form-submissions

You can configure a form to be processed by the selected workflow. When users submit the form, a new workflow instance is created with the data of the form submission as its payload.

To configure the workflow to be used with your form:

  1. Create a new page and open it for editing.

  2. Add a Form component to the page.

  3. Configure the Form Start component that appeared in the page.

  4. Use Start Workflow to select the desired workflow from those available:

    wf-12

  5. Confirm the new form configuration with the tick.

Testing Workflows testing-workflows

It is a good practice when testing a workflow to use a variety of payload types; including types that are different to the one for which it has been developed. For example, if you intend your workflow to deal with Assets, test it by setting a Page as payload and make sure that it does not throw errors.

For example, test your new workflow as follows:

  1. Start your workflow model from the console.

  2. Define the Payload and confirm.

  3. Take actions as required so that the workflow proceeds.

  4. Monitor the log files while the workflow is running.

You can also configure AEM to display DEBUG messages in the log files. See Logging for further information and when the development is finished, set the Log Level back to Info.

Examples examples

Example: Creating a (Simple) Workflow to Accept or Reject a Request for Publication example-creating-a-simple-workflow-to-accept-or-reject-a-request-for-publication

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

  1. Create a new workflow model.

    The new workflow will contain:

    • Flow Start
    • Step 1
    • Flow End

  2. Delete Step 1 (as it is the wrong step type for this example):

    • Click on the step and select Delete from the component toolbar. Confirm the action.

  3. From the Workflow selection of the steps browser, drag a Participant Step onto the workflow and position it between Flow Start and Flow End.

  4. To open the properties dialog box either:

    • Click on the participant step and select Configure from the component toolbar.
    • Double-click on participant step.

  5. In the Common tab enter Validate Content for both the Title and Description.

  6. Open the User/Group tab:

    • Activate Notify user via email.
    • Select Administrator ( admin) for the User/Group field.
    note note
    NOTE
    For emails to be sent, the mail service and user account details need to be configured.

  7. Confirm the updates with the tick.

    You will be returned to the overview of the workflow model, here the participant step will have been renamed to Validate Content.

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

  9. Open the Or Split for configuration.

  10. Configure:

    • Common: select 2 Branches
    • Branch 1: select Default Route.
    • Branch 2: ensure Default Route is not selected.

  11. Confirm your updates to the OR Split.

  12. Drag a Participant Step to the left-hand branch, open the properties, specify the following values, then confirm the changes:

    • Title: Reject Publish Request
    • User/Group: for example, projects-administrators
    • Notify user via email: Activate to have the user notified by email.

  13. Drag a Process Step to the right-hand branch, open the properties, specify the following values, then confirm the changes:

    • Title: Publish Page as Requested
    • Process: select Activate Page. This process publishes the selected page to the publisher instances.

  14. Click Sync (editor toolbar) to generate the runtime model.

    See Sync your Workflow for details.

    Your new workflow model will look like:

    wf-13

  15. Apply this workflow to your page, so that when the user moves to Complete the Validate Content step, they can select whether they want to Publish Page as Requested, or Reject Publish Request.

    chlimage_1-182

Example: Defining a Rule for an OR Split example-defining-a-rule-for-an-or-split

OR Split steps allow you to introduce conditional processing paths into your workflow.

To define an OR rule:

  1. Create two scripts and save them in the repository, for example under:

    /apps/myapp/workflow/scripts

    note note
    NOTE
    The scripts must have a function check() that returns a boolean.

  2. Edit the workflow and add the OR Split to the model.

  3. Edit the properties of Branch 1 of the OR Split:

    • Define this as the Default Route by setting the Value to true.

    • As Rule, set the path to the script. For example:

      /apps/myapp/workflow/scripts/myscript1.ecma

    note note
    NOTE
    You can switch the branch order if required.

  4. Edit the properties of the Branch 2 of the OR Split.

    • As Rule, set the path to the other script. For example:

      /apps/myapp/workflow/scripts/myscript2.ecma

  5. Set the properties of the individual steps in each branch. Make sure the User/Group is set.

  6. Click Sync (editor toolbar) to persist your changes to the runtime model.

    See Sync your Workflow for details.

Function Check() function-check

NOTE
See Using ECMAScript.

The following sample script returns true if the node is a JCR_PATH located under /content/we-retail/us/en:

function check() {
    if (workflowData.getPayloadType() == "JCR_PATH") {
      var path = workflowData.getPayload().toString();
      var node = jcrSession.getItem(path);

      if (node.getPath().indexOf("/content/we-retail/us/en") >= 0) {
       return true;
      } else {
       return false;
      }
     } else {
      return false;
     }
}

Example: Customized Request for Activation example-customized-request-for-activation

You can customize any of the out-of-the-box workflows. To have customized behavior you overlay details of the appropriate workflow.

For example, Request for Activation. This workflow is used for publishing pages within Sites and is automatically triggered when a content author does not have the appropriate replication rights. See Customizing Page Authoring - Customizing the Request for Activation Workflow for further details.

recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e