Workflow models consist of a series of steps of various types. According to the type, these steps can be configured and extended with parameters and scripts to provide the functionality and control you require.

Step Properties

Each step component has a Step Properties dialog that allows you to define and edit the required properties.

Step Properties - Common tab

A combination of the following properties are available for most workflow step components, on the Common tab of the properties dialog:

Title
The title for the step.

Description
A description of the step.

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

Handler Advance
Select this option to automatically advance the workflow to the next step after execution. If not selected, the implementation script must handle workflow advancement.

Step Properties - User/Group tab

The following properties are available for many workflow step components, on the User/Group tab of the properties dialog:

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.

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.

AND Split

The AND Split creates a split in the workflow, after which both branches will be active. You add workflow steps to each branch as required. This step enables you to introduce multiple processing paths into the workflow. For example, you can allow certain review steps to occur in parallel, so saving time.

AND Split - Configuration

To configure the split:

Edit and use the following tabs:

Common

Branches: Select the number of branches required; 2, 3, 4 or 5.

Add workflow steps to the branches as required.

Container Step

A container step starts another workflow model that executes as a child workflow.

This container can allow you to reuse workflow models to implement common sequences of steps. For example a translation workflow model could be used in multiple editing workflows.

Container Step - Configuration

Goto Step

The Goto Step allows you to specify the next step in the workflow model to execute, dependent on the result of an ECMAScript:

true: The Goto Step completes and the workflow engine executes the specified step.

false: The Goto Step completes and the normal routing logic determines the next step to execute.

The Goto Step enables you to implement advanced routing structures in your workflow models. For example, to implement a loop, the Goto Step can be defined to execute a prior step in the workflow, with the script evaluating a loop condition.

Goto Step - Configuration

Script Path: The path to the ECMAScript that determines whether to execute the Goto Step.

Script: The ECMAScript that determines whether to execute the Goto Step.

Attenzione:

Specify either the Script Path or Script. Both options cannot be used at the same time. If you specify values for both properties, the step uses the Script Path.

Simulating a for Loop

Simulating a for loop requires that you maintain a count of the number of loop iterations that have occurred:

The count typically represents an index of items that are acted on in the workflow.

The count is evaluated as the exit criteria of the loop.

For example, to implement a workflow that performs an action on several JCR nodes you can use a loop counter as an index for the nodes. To persist the count, store an integer value in the data map of the workflow instance. Use the script of the Goto Step to increment the count as well as to compare the count to the exit criteria.

OR Split

The OR Split creates a split in the workflow, after which only one branch will be active. This step enables you to introduce conditional processing paths into your workflow. You add workflow steps to each branch as required.

OR Split - Configuration

To configure the split:

Edit and use the following tabs:

Common

Branches: Select the number of branches required; 2, 3, 4 or 5.

Branch <x>

Script Path: The path to a file that contains the script.

Script: Add the script in the box.

Default Route: The default branch is followed when no script is defined for any branches in the split, or neither are fulfilled. You can specify only one branch as the default.

Nota:

There is a separate tab for each branch:

The script of each branch is evaluated one at a time.

The branch number determines the order in which they are evaluated.

The first script that evaluates to true is executed.

If no script evaluates to true, then the default branch is followed.

Attenzione:

Specify either the Script Path or Script. Both options cannot be used at the same time. If you specify values for both properties, the step uses the Script Path.

Participant Steps and Choosers

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 that is the workflow payload.

Some properties need to be configured to enable email notifications. You can also customize the email template or add an email template for a new language. See Configuring Email Notification to configure email notifications in AEM.

Dialog Participant Step

Use a Dialog Participant Step to collect information from the user who is assigned the work item. This step is useful for collecting small amounts of data that is used later in the workflow.

Upon completing the step, the Complete Work Item dialog contains the fields that you define in your dialog. The data that is collected in the fields is stored in nodes of the workflow payload. Subsequent workflow steps can then read the value from the repository.

To configure the step, you specify the group or user to assign the work item to, and the path to the dialog.

The Dialog Participant Step has the Dialog Path property (together with the properties of a Participant Step). The value of the Dialog Path property is the path to the dialog node of your dialog.

For example, the dialog is contained in a component named EmailWatch that is stored in the /etc/workflows/dialogs node. For the touch-optimized UI the following value is used for the Dialog Path property:

/etc/workflow/dialogs/EmailWatch/cq:dialog

Example Dialog Definition

The following XML code snippet represents a dialog that stores a String value in the watchEmail node of the payload content. The title node represents the TextField component:

Dynamic Participant Step - Developing the participant chooser

You create the participant chooser. Therefore, you can use any selection logic or criteria. For example, your participant chooser can select the user (within a group) that has the fewest work items. You can create any number of participant choosers to use with different instances of the Dynamic Participant Step component in your workflow models.

Create an OSGi service or an ECMAScript that selects a user to assign the work item to.

ECMAscript

Scripts must include a function named getParticipant that returns a user ID as a String value. Store the script in the /etc/workflow/scripts folder, or a subfolder.

SERVICE_PROPERTY_LABEL field: Use this field to specify the name of the participant chooser. The name appears in a list of available participant choosers in the Dynamic Participant Step properties.

getParticipant method: Returns the the dynamically resolved Principal id as a String value.

Attenzione:

The getParticipant method returns the the dynamically resolved Principal id. This can be either a group id or user id.

However, a group id can only be used for a Participant Step, when a list of participants is returned. For a Dynamic Participant Step an empty list is returned and this cannot be used for delegation.

To make your implementation available to Dynamic Participant Step components, add your Java class to an OSGi bundle that exports the service, and deploy the bundle to the AEM server.

Nota:

Random Participant Chooser is a sample service that selects a random user (com.day.cq.workflow.impl.process.RandomParticipantChooser). The Random Participant Chooser step component sample extends the Dynamic Participant Step and uses this service as the step implementation.

Dynamic Participant Step - Example Participant Chooser Service

The following Java class implements the ParticipantStepChooser interface. The class returns the name of the participant who initiated the workflow. The code uses the same logic that the sample script (initator-participant-chooser.ecma) uses.

The @Property annotation sets the value of the SERVICE_PROPERTY_LABEL field to Workflow Initiator Participant Chooser.

Form Participant Step - Creating the form

Create a form for use with a Form Participant Step as normal. However, forms for a Form Participant Step must have the following configurations:

The Start of Form component must have the Action Type property set to Edit Workflow Controlled Resource(s).

The Start of Form component must have a value for the the Form Identifier property.

The form components must have the Element Name property set to the path of the node where the field data is stored. The path must locate a node in the workflow payload content. The value uses the following format:

./jcr:content/path_to_node

The form must include a Workflow Submit Button(s) component. You do not configure any properties of the component.

The requirements of your workflow determine where you should store field data. For example, field data can be used to configure the properties of page content. The following value of an Element Name property stores field data as the value of the redirectTarget property of the jcr:content node:

./jcr:content/redirectTarget

In the following example, the field data is used as the content of a Text component on the payload page:

./jcr:content/par/text_3/text

The first example can be used for any page that the cq:Page component renders. The second example can only be used when the payload page includes a Text component that has an ID of text_3.

The form can be located anywhere in the repository, however workflow users must be authorized to read the form.

Random Participant Chooser - Configuration

Participants: Specifies the list of users available for selection. To add a user to the list, click Add Item and type the home path of the user node or the user ID. The order of the users does not affect the likelihood of being assigned a work item.

Workflow Initiator Participant Chooser

The Workflow Initiator Participant Chooser step is a participant chooser that assigns the generated work item to the user who started the workflow. There are no properties to configure other than the Common properties.