Administering Workflow Instances

You are reading the AEM 6.1 version of Administering Workflow Instances.
This documentation is also available for the following versions:  AEM 6.2  AEM 6.0  AEM 5.6.1  AEM 5.6  CQ 5.5 

The workflow console provides several tools for administering workflow instances to ensure that they are executing as expected.


The JMX console provides additional workflow maintenance operations.

Open the workflow console using the Workflows link on the AEM Welcome page (Classic UI), and the Tools section of the touch-optimized UI.

Within the console are several tabs:


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


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


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


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


Enables you to monitor and manage failed worklow instances.

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: Progression of the workflow instance requires that a background job executes, however the job cannot be found in the system. This situation can occur when an error occurs when executing the workflow.

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. 

Note: When the execution of a Process Step results in errors, the step appears in the administrator's Inbox and the workflow status is RUNNING. 

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:


Select an instance and click Open History to show the actions executed to date on the workflow instance:


You can also use the JMX console to see a list of running and completed workflows.

Suspending, Resuming, and Terminating a Workflow Instance

Perform actions on running workflow instances when you need to intervene in the normal progression of a workflow instance:

  • Suspend: Temporarily stops the execution of the workflow. Suspending is useful in exceptional cases when you do not want the workflow to proceed, for example for maintenance. Suspending changes the workflow state to Suspended.
  • Resume: Restarts a suspended workflow at the same point of execution where it was suspended, using the same configuration. 
  • Terminate: Ends the workflow execution and changes the state to ABORTED. An aborted workflow instance cannot be restarted.
  1. Select the Instances tab. You will see a list of active (neither finished, nor terminated) workflow instances.

  2. Select an entry.

  3. In the navigation bar, click Suspend, Resume, or Terminate.

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.

Fixing Workflow Instance Failures

Workflow instances appear on the Failures tab of the Workflows console when the execution of a Process Step component results in errors. The Failures tab enables you to investigate the cause of the errors, and provides options for resuming execution when the causes are fixed:

  • Failure Details: Provides information about the execution error, including the name of the step that failed, the error message, and the stack trace for the error.

  • Retry Step: Executes the Script Step component instance again. Use the Retry Step command after you have fixed the cause of the original errror. For example, retry the step after you fix a bug in the script that the Process Step executes.

  • Terminate Workflow: Terminate the workflow if the error has caused an irreconsilable situation for the workflow. For example, the workflow can rely on environmental conditions such as information in the respository that are no longer valid for the workflow intance.

  • Terminate and Start New Workflow: Similar to Terminate except that a new workflow instance is started using the original payload, title, and description.

You can use the JMX console to terminate and retry workflows as a bulk operation.

  1. Select the Failurs tab and select a workflow intance.

  2. Click Failure Details, Retry Step, Terminate Workflow, or Terminate and Start New Workflow.

Archived Workflows

After a Workflow instance has finished, for example after being terminated 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.

You can use the JMX console to purge the repository of completed workflows or schedule regular purging. If the list of archived workflows grows too large, purge those that are of a certain age to speed page loading.

Regular Purging of Workflow Instances

Regularly purge completed or running workflow instances from the repository. Minimizing the number of workflow instances increases the performance of the workflow engine. Configure the Workfow Purge Scheduler service to purge workflow instances according their age and status. You can also purge workflow instances of all models or of a specific model.

Create multiple configurations of the service to purge workflow instances that satisfy different criteria. For example, create a configuration that purges the instances of a particular workflow model when they are running for much longer than the expected time. Create another configuration that purges all completed workflows after a certain number of days to minimize the size of the repository.

To configure the Purging Workflow Instances service, you can use the Web Console or add an OSGi configuration to the repository. The following table desribes the properties that you need for either method. 

Note: For adding the configuration to the repository, the service PID is com.adobe.granite.workflow.purge.Scheduler. Because the service is a factory service, the name of the sling:OsgiConfig node requires an identifier suffix, for example com.adobe.granite.workflow.purge.Scheduler-myidentifier.

Property Name (Web Console) OSGi Property Name Description
Job Name A descriptive name for the scheduled purge.
Workflow Status scheduledpurge.workflowStatus

The status of the workflow instances to purge. The following values are valid:

  • COMPLETED: Completed workflow instances are purged.
  • RUNNING: Running workflow instances are purged.
Models To Purge scheduledpurge.modelIds

The ID of the workflow models to purge. The ID is the path to the model node, for example /etc/workflow/models/dam/update_asset/jcr:content/model. Specify no value to purge instances of all workflow models.

To specify multiple models, click the + button in the Web Console. 

Workflow Age scheduledpurge.daysold The age of the workflow instances to purge, in days.

Setting the Maximum Size of the Inbox

To configure the Purging Workflow Instances service, you can use the Web Console or add an OSGi configuration to the repository. The following table describes the property that you configure for either method. 

Note: For adding the configuration to the repository, the service PID is com.adobe.granite.workflow.core.WorkflowSessionFactory

Property Name (Web Console) OSGi Property Name
Max Inbox Query Size granite.workflow.inboxQuerySize