Developing Workflows

This page describes the main elements when developing workflows. If needed refer to the information on using workflows.

There are many code samples to help you get started quickly.

A workflow is made of steps. Automated steps, also called process steps, can be defined by using either an ECMA script or a service (a Java class in a bundle). Rules for OR split can be defined with ECMA scripts. Services can be developed to listen to special workflow events and perform tasks according to the business logic. The Java API, the main workflow objects and the REST API are described. The last section explains how to change the workflow specific log level to efficiently debug the code.

New and Noteworthy in 5.4

Step Components

CQ 5.4 introduces a new workflow editor built on the well known concept of components. Every process step is an own component in the sidekick. It allows to build step specific and user friendly edit dialogs, especially for configuring process arguments. You can have a look at the edit dialog of the new Create Web Enabled Image process step component. Instead of inputting the process arguments as a one single string, the user is presented a form with dedicated fields for the arguments.

There is also a generic process step component called Process Step that allows to use custom process step implementations without building a step component. Please refer to Creating a custom step component  for more information on how to create your own custom step component.

Dynamic Participant Step

While it was possible to create dynamic participant steps before, there is since 5.4 a step component called Dynamic Participant Step that allows to select custom participant chooser implementations for easy integration into the workflow model. 

See Defining a participant step: with a Java class  for more information on how to create your own custom participant chooser step.

API Changes

The step components allow to create more flexible process arguments than just a single string like until 5.3. And because it is possible to define multi valued arguments, the existing API changed to reflect this flexiblity. So API changes are mainly around passing and accessing process arguments, also known as meta data in the API. 

The following interfaces are declared deprecated:

  • com.day.cq.workflow.exec.JavaProcess
  • com.day.cq.workflow.exec.JavaProcessExec
  • com.day.cq.workflow.exec.ParticipantChooser

And replaced by the following new interfaces:

  • com.day.cq.workflow.exec.WorkflowProcess
  • com.day.cq.workflow.exec.ParticipantStepChooser
  • com.day.cq.workflow.metadata.MetaDataMap

Deprecated API means it is still available in 5.4 and also backward compatible, but it will probably be removed in future releases. So you are encouraged to use the new API and migrate existing custom process steps if any.

MetaDataMap

This new interface replaces the previous string array to pass meta data (process arguments) into the new step execution method. It is basically a map and works like the Sling ValueMap. See Working with process arguments for more details.

Overview of the Main Workflow Objects

This section describes the main workflow objects.

Model

Is made of WorkflowNodes and WorkflowTransitions. The transitions connect the nodes and define the "flow". The Model has always a start node and an end node.

Workflow models are versioned. Running Workflow Instances keep the initial workflow model version that is set when the workflow is started.

Step

There are different types of workflow steps: 

  • Participant (User/Group) 
  • Process (Script, Java method call) 
  • Container (Sub Workflow) 
  • OR Split/Join 
  • AND Split/Join

All the steps share the following common properties: Autoadvance and Timeout alerts (scriptable).

Transition

Defines the link between two consecutive steps.

It is possible to apply rules.

WorkItem

Is the "there is a task identifier" and is put into the respective inbox.

A workflow instance can have one or many WorkItems at the same time (depending on the workflow model).

The WorkItem references the workflow instance.

In the repository the WorkItem is stored below the workflow instance.

Payload

References the resource that has to be advanced through a workflow.

The payload implementation references a resource in the repository (by either a path or an UUID) or a resource by a URL or by a serialized java object. Referencing a resource in the repository is very flexible and in conjunction with sling very productive: for example the referenced node could be rendered as a form.

Lifecycle

Is created when starting a new workflow (by choosing the respective workflow model and defining the payload) and ends when the end node is processed. 

The following actions are possible on a workflow instance:  

  • Terminate
  • Suspend
  • Resume
  • Restart

Completed and terminated instances are archived.

Inbox

Each logged in user has its own workflow inbox in which the assigned WorkItems are accessible.

The WorkItems are assigned either to the user itself or to the group to which he belongs.

Overview of the APIs: Java, ECMA and REST

Workflow objects can be accessed through the following APIs: the Java, ECMA and REST APIs.

This section gives an overview of the different APIs. For a complete description of:

The following table points to the appropriate Java objects when developing workflows:

Features Objects
Accessing a workflow
WorkflowService
WorkflowSession
Executing a workflow
WorkflowSession
Workflow
WorkItem
WorkflowData
Querying a workflow
WorkflowSession
WorkItem
Workflow
Managing a workflow model
WorkflowModel
WorkflowNode
WorkflowTransition
WorkflowSession

The following code snippets help you to programmatically access the most used workflow objects and methods. The REST API is shown by using curl, a command line tool that sends requests to a server and manages its responses.

Getting the Workflow Service

In an OSGI service or in an OSGI component:

Java: in a JSP script or in a servlet:

ECMAScript:

Getting a Workflow Session

The WorkflowService (OSGI service) provides a method in order to get a WorkflowSession.

Java:

ECMAScript:

Creating, Reading or Deleting Workflow Models

Java:

ECMAScript:

REST:

Managing Workflow Instances

Java:

ECMAScript:

REST:

Managing Work Items

Java:

ECMAScript:

REST:

Working with Process Arguments

Since the 5.4 version, process arguments can be easily accessed. This section describes how to access the MetaDataMap object passed into the API methods, to get access to the process arguments.

Note

This section describes how to work with arguments for process steps, but the same applies for dynamic participant choosers as well.

Using the Process Step Component

Using the Process Step component allows to add a single argument string in the components edit dialog. This argument string is then available to the arguments map through the PROCESS_ARGS key. 

For example, setting the arguments argument1, argument2 as shown in the screenshot below:

file

The arguments are available through the arguments map as follows:

Note

It is in the callers responsability to extract multiple arguments from the single argument string, as for example comma-separated.

Using a Custom Step Component

Using a custom step component gives you control over the arguments that are put on the arguments map through the argument keys. Let's look at the Create Web Enabled Image component as an example of a custom step component. This component offers a more user-friendly way of setting arguments, as shown below:

file

The same arguments had to be encoded in a singe argument string until 5.4, looking like:

dimension:300:200", "skip:image/gif", "skip:image/jpeg"

Since 5.4 the arguments are available in the implementation as follows:

Using Both the Process Step Component and a Custom Step Component

You can also design your process implementation to be used with the Process Component and a custom component at the same time. It is then up to the implementation to find out how the process is called and treat the arguments accordingly. You can find out if the process is called from the Process Component by testing for the PROCESS_ARGS key. The following snippet should give you an idea:

Scripts and Process Arguments

Within a script for a Process Step component, arguments are available through the args object.

When creating a custom step component, the object metaData is available in a script. This object is limited to single string argument. 

Creating a Custom Step Component

This section walks you through the steps of creating a custom step component. It shows how to create a step component that allows to set a few arguments, and a process step that writes the values of the arguments into the log file:

  1. Copy the noopprocess at /libs/cq/workflow/components/workflow/noopprocess to /apps/cq/workflow/components/workflow/loggerprocess
  2. Change the jcr:title and jcr:description properties of /apps/cq/workflow/components/workflow/loggerprocess accordingly.
  3. Go to the cq:formParamters node at /apps/cq/workflow/components/workflow/loggerprocess/cq:editConfig/cq:formParameters
  4. Change the jcr:title and jcr:description properties accordingly.
  5. Change the PROCESS property to the step implementation: let's assume com.day.cq.workflow.impl.process.LoggerProcess
  6. Change the title property of the dialog node at /apps/cq/workflow/components/workflow/loggerprocess/dialog
  7. Change the path property of the processargs node at /apps/cq/workflow/components/workflow/loggerprocess/dialog/items/tabs/items/processargs and set it to /apps/cq/workflow/components/workflow/loggerprocess/processargs.infinity.json
  8. Add the argument widgets below /apps/cq/workflow/components/workflow/loggerprocess/processargs/items/arguments/items
  9. Add a text field widget and set the name property to ./metaData/argSingle
  10. Add a multifield widget and set the name property to ./metaData/argMulti
The Logger Process component is added to the Sidekick as follows:

file

Add the Logger Process to your workflow model and open the edit dialog. It looks similiar to the following:

file

Let's continue by creating the com.day.cq.workflow.impl.process.LoggerProcess implementation. See here for details about creating a Java based process step:

Custom Step Components for Participant Choosers

To create a custom dynamic participant chooser component, the same process described in the Creating a Custom Step Component section  applies except that at step 5, the property to reference the participant chooser implementation needs to be called DYNAMIC_PARTICIPANT instead of PROCESS.

Defining a Participant Step: with a Java class


To define a participant step as an OSGI service component (Java bundle):

  1. The OSGI component needs to implement the ParticipantStepChooser interface with its getParticipant() method. See the example code below. 
    Create the bundle and deploy it into the OSGI container. Refer to the documentation about creating a bundle with CRXDE LiteCRXDE or Eclipse.
    Note: The package name needs to be added to the <Private-Package> section of the maven-bundle-plugin configuration.
  2. Add the SCR property "chooser.label" and set the value as you please. This will be the name as which your participant chooser is listed, using the Dynamic Participant Step component. See the example below.
  3. In the CQ Workflow console, add the dynamic participant step to the workflow using the generic Dynamic Participant Step component.
  4. In the edit dialog select the Participant Chooser tab and select your chooser implementation.
  5. If  you use arguments in your code set the Process Arguments. For this example: /content/geometrixx/en.
  6. Save the changes.

The java methods, respectively the classes that implement the executable Java method are registered as OSGI services, enabling you to add methods at anytime during runtime.

Defining a Participant Step: with an ECMA Script

To define a participant step as an ECMA script:

  1. Create the script (for example with CRXDE Lite) and save it in the repository under /etc/workflow/scripts.
    For example: /etc/workflow/scripts/myDynamicParticipant.ecma
  2. As you can see in the following code samples, a typical script starts with the workItem to get a workflow data object. It then checks for the relevant criteria and returns the name of the dynamically chosen participant.
  3. By adding the jcr:title property to the jcr:content node of your script in the repository, you can define the title under which the script get's listed in the Dynamic Participant Step component. To add the jcr:title property you must first add the mix:title mixin to the jcr:content node.
  4. In the CQ Workflow console, add the dynamic participant step to the workflow using the generic Dynamic Participant Step component.
  5. In the edit dialog select the Participant Chooser tab and select your chooser implementation.
  6. Save the changes.

The scripts are located in the jcr repository and executed from there.

The following objects are available within ECMA scripts:

The following script sample help you get started.

Defining a Process Step: with a Java Class

To define a process step as an OSGI service component (Java bundle):

  1. Create the bundle and deploy it into the OSGI container. Refer to the documentation about creating a bundle with CRXDE LiteCRXDE or Eclipse.
    Note 1: the OSGI component needs to implement the WorkflowProcess interface with its execute() method. See the example code below.
    Note 2: The package name needs to be added to the <Private-Package> section of the maven-bundle-plugin configuration.
  2. Add the SCR property "process.label"  and set the value as you please. This will be the name which your process step is listed as when using the generic Process Step component. See the example below.
  3. In the CQ Workflow console, add the process step to the workflow using the generic Process Step component.
  4. In the edit dialog, go to the Process tab and select your process implementation. 
  5. If you use arguments in your code, set the Process Arguments . For example: false.
  6. Save the changes.

The java methods, respectively the classes that implement the executable Java method are registered as OSGI services, enabling you to add methods at anytime during runtime.

The following OSGI component adds the property approved to the page content node when the payload is a page:

Note

If the process fails three times in a row, an item is placed in the Inbox of the workflow administrator to inform him.

Defining a Process Step: with an ECMA Script

To define a process step as an ECMA script:

  1. Create the script (for example with CRXDE Lite) and save it in the repository under /etc/workflow/scripts.
    As you can see in the following code samples, a typical script starts with the workItem to get a workflow data object. It then checks the payload type, gets the payload node, sets a property and saves the node.
  2. By adding the jcr:title property to the jcr:content node of your script in the repository, you can define the title under which the script get's listed in the Process Step component. To add the jcr:title property you must first add the mix:title mixin to the jcr:content node.
  3. In the CQ Workflow console, add the process step to the workflow using the generic Process Step component.
  4. In the edit dialog, go to the Process tab and select your process implementation.
  5. Save the changes

The scripts are located in the JCR repository and executed from there.

The following objects are available within ECMA scripts:

The following script samples help you get started.

The following script adds the property approved to the payload.

The following script checks if the payload is an image (png file), creates a black and white image out of it and saves it as a sibling node.

Note

If the process fails three times in a row, an item is placed in the Inbox of the workflow administrator to inform him.

Extending the DAM Delete Asset Workflow to Deactivate the Asset

In the default configuration an asset is deleted from /content/dam but not deactivated when its original file is deleted in /var/dam (for example by using WebDAV). To trigger the deactivation of the asset when its original file is deleted in /var/dam, add the following ECMA script based process step after the Delete asset step in the DAM Delete Asset Workflow:

Listening to Workflow Events

This section shows you through an example how to define a service that listens to workflow events and performs tasks when a specific workflow event happens.

Defining a Rule for an OR Split

OR splits allow you to introduce conditional processing paths into your workflow. To define an OR rule, proceed as follows:

  1. Create the two scripts and save them in the repository, for example under /apps/myapp/workflow/scripts.
    Note: the scripts must have a function check() that returns a boolean.
  2. In the CQ Workflow console, add the OR split to the workflow.
  3. Edit the properties of one branch of the OR split.
  4. Define the Default Route by setting the Value to true.
  5. As Rule, set the path to the script. For example: /apps/myapp/workflow/scripts/myscript1.ecma.
  6. Edit the properties of the other branch of the OR split.
  7. As Rule, set the path to the other script. For example: /apps/myapp/workflow/scripts/myscript2.ecma.
  8. Set the properties of the steps in each branch. Make sure the User/Group is set.

The following objects are available within ECMA scripts:

The following sample script returns true if the node is a JCR_PATH located under /content/geometrixx/en:

Managing Workflow Packages

Workflow packages can be passed to a workflow for processing. They are defined, on a specialized page, as a list of links to the required resources (for example, links to pages and assets).

The workflow script must be programmed to process the resources listed in the package, but not the page defining the package itself. For example, the workflow scripts com.day.cq.wcm.workflow.process.ActivatePageProcess and com.day.cq.wcm.workflow.process.DeactivatePageProcess will activate/deactivate all resources listed in the package.

You can develop your own workflow scripts to process such a package, for example:

Debugging and Testing Workflows

Refer to the section Debugging to start the CQ server in debug mode.

You can display Debug messages related to workflows in the log files:

  1. In your browser, go to the Apache Felix Console and select Configuration.
  2. As Factory Configurations select Factory Apache Sling Logging Logger Configuration. Click Create.
  3. Set the Log Level to Debug.
  4. Set the Logger to com.day.cq.workflow.
  5. Click Save.
  6. When the development is finished, set the Log Level back to Info.

Test a new workflow as follows:

  1. Open the Workflow console; for example http://localhost:4502/libs/cq/workflow/content./console.html
  2. In the Models tab, right-click the model and select Start.
  3. Define the Payload and click OK.
  4. If one of the steps is a User Step, click the Inbox tab, select the step and perform the desired action.
  5. While running the workflow, monitor the log files.

Note

It is a good practice when debugging a workflow to test the workflow with a  payload type that is different than 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.


Any questions?
Find tips, tricks, and solutions to common issues in our support community:
https://helpx.adobe.com/marketing-cloud/experience-manager.html
​