Tasks

Introduction to tasks in ConSol CM

Tasks are used to execute scripts asynchronously, so that script execution is not tied to user actions in the Web Client or CM/Track. Tasks can be used for general operations and operations whose processing takes long, so that it would cause a timeout when executed as a regular script.

Concepts, terms and definitions

Concept	Other terms	Definition
task		Asynchronous execution of a script
task script		Script which implements the operations performed by a task and the task behavior if an error occurs or the task is canceled
task executor		Module which scans the database for new scheduled tasks and executes them
task descriptor		Internal object which holds information about a task
execution specification		Internal object which hold information about the start date and time of the task; if not specified, the task is started immediately

Purpose and usage

Tasks enable asynchronous operations. They can be created either manually in the Web Admin Suite or automatically in a script. In both cases, the task is based on a script of the type Task which implements the logic of the operations to be performed. Tasks can be used for operations which are not related to specific user actions in the Web Client or CM/Track, e.g. general maintenance work. In addition, tasks allow to perform operations whose processing takes long, so that it would cause a timeout when executed as a regular script.

Tasks can permanently delete objects from the ConSol CM database. The actions performed by a task cannot be undone. Tasks performing bulk operations can have a severe impact on system performance.

Available settings for task execution

The following settings are available for task execution in general:

• Transaction timeout

  The system property cmas-core-server, transaction.timeout.minutes determines the transaction timeout for tasks. One run of a task must finish before this timeout is reached. If the operations to be performed by the task take longer, you need to split the processing and repeat the task, see Repeating a task.

• Thread pool

  The system property cmas-core-server, number.of.tasks determines the size of the thread pool, i.e. how many tasks can be executed in parallel.

• Time between executions

  The system property cmas-core-server, task.execution.interval.seconds determines the time between the execution of two tasks.

• Node ID (only relevant for clusters)

  The system property cmas-core-server, task.execution.node.id determines on which cluster node the tasks are executed.

Basic tasks

You need to perform the following steps to use tasks in ConSol CM:

1. Create a task script which implements the logic of the operations to be performed, see Creating a task script.
2. Create a task which executes the task script, see Creating a task.
3. You can track the task’s progress in the task list, see Tracking the task execution.

Creating a task script

Create a script of the type Task in the Scripts section of the Web Admin Suite (see Scripts). The script has to implement the logic of the operations to be performed.

The task script needs to implement the following four methods:

• onInitialize()
  Code to be executed when the task has been created
• onExecute()
  Code to be executed when the task has been started
• onError()
  Code to be executed if an error occurs during task execution
• onCancel()
  Code to be executed if the task is canceled

Creating a task

There are two ways to create a task:

• Manually create a task for immediate execution:
  1. Open the Tasks section of the Web Admin Suite.
  2. Click the New task button.
  3. Select a task script and click Start task.

  You can also create a task by clicking the Execute task button which is displayed for task scripts in the Scripts section of the Web Admin Suite.

• Create a task within another script (workflow activity, action or email script):

  • Open the script in the Web Admin Suite or Process Designer.

  • Add code to create a task (replace “taskScript.groovy” by the task script created in Creating a task script):

    GroovyTask groovyTask = new GroovyTask();

    groovyTask.setStaticScript(scriptSourceService.getByName("taskScript.groovy"));

    taskDescriptor = taskExecutionService.schedule(groovyTask, "task");

By default, tasks are executed immediately. It is not possible to schedule manually created tasks for another point in time using the graphical user interface. See Defining the execution date of a task for how to change the execution date within the task script.

Tracking the task execution

The task list shows all active tasks in the system. The following information is displayed for each task:

• Name
  Name of the task script
• Progress
  Progress bar showing the progress of task execution
• Created at
  Date and time when the task was created
• Next execution at
  Date and time when the task execution will begin. This is usually the same as Created at, unless another execution date was defined in the task script, see Repeating a task and Defining the execution date of a task.
• Status
  The status of the task. This can be Initialized, Executing, Locked or Stopping.

Advanced tasks

Canceling a task

There are two ways to cancel a running task:

• Locate the task in the Tasks section of the Web Admin Suite and click the Stop button in the row of the task.

• Cancel the tasks in another script. In this case, you need the descriptor ID of the task to be canceled.

  Use the following code to save the descriptor ID when creating the task:

  GroovyTask groovyTask = new GroovyTask();

  groovyTask.setStaticScript(scriptSourceService.getByName("taskScript.groovy"));

  taskDescriptor = taskExecutionService.schedule(groovyTask, "task");

  def myTaskDescriptorId = groovyTask.getId()

  //save this ID

  You can then cancel the task by using the following piece of code:

  taskExecutionService.cancel(myTaskDescriptorId)

Canceled tasks are removed and cannot be started again.

Repeating a task

There are two scenarios where you might want to repeat a task:

• An error has occurred during task execution.
• The task processes large amounts of data and you want to do the processing in chunks.

In both cases you can use the following method to repeat the task:

return new ExecutionSpecification().setRetryRequested(true);

If you want to set a specific date or time when the repeated task should be executed, use:

return new ExecutionSpecification().setRetryRequested(true).setExecutionDate(new Date(new Date().getTime() + 15000));

Add this piece of code to the end of the onExecute() method in the task script, if you want repeat the task in the regular execution. If you want to repeat the task if an error occurred, add it to the onError() method.

Defining the execution date of a task

If a task should not be started immediately, you can set the start time in the onInitialize() method.

When the task is started, the set execution date is displayed in the Next execution at column of the task list.

Using the context reference

If you create tasks from other scripts, you can use the context reference to determine which script created the task. When creating the task, you set a context reference, which can be retrieved in the task script to implement a different behavior depending on the source script.

• Set the context reference in the source script, e.g. a workflow script:

  GroovyTask groovyTask = new GroovyTask();

  groovyTask.setStaticScript(scriptSourceService.getByName("taskScript.groovy"));

  groovyTask.setContextReference("context reference")

• Retrieve the context reference in the task script:

  taskDescriptor.getContextReference()