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 on the Scripts page 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 page of the Web Admin Suite.

  2. Click the Schedule task button.

  3. Select a task script and schedule the task. The following scheduling options are available:

     • Now: The task is started immediately.

     • Once: The task is started at the selected date and time.

     • Periodic: The task is executed repeatedly according to the defined scheduling. This can be daily, weekly or monthly at one or more defined times, or in a minute interval.

       If more than one execution time, day of week or day of month is selected, a separate task will be created for each scheduling option. For minutely scheduling, there is only one task which is rescheduled automatically.

     The task name is prefilled with the script name. You can modify it if desired.

     You can select the High priority task checkbox if the task should be executed as soon as possible, i.e. in the next available slot before other tasks which are waiting for execution.

     In the Error handling section, you can select the checkbox Notify administrator after error if an email should be sent to the administrator in case the task fails. For periodic tasks, you can also deactivate the task automatically in this situation.

  4. Click the Start task button.

  You can also create a task by clicking the Execute task button which is displayed for task scripts on the Scripts page 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.

  • 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");

Tracking the task execution

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

• Task name
  Name of the task, entered during task creation or provided in the task script
• Script 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 Tasks.
• Status
  The status of the task. This can be Waiting for execution, Executing, Locked or Stopping.
• Scheduling interval
  Interval in which the task is executed. This can be Daily, Weekly, Monthly or Once.
• Scheduling option
  Day and time of the scheduled task execution
• Last execution at
  Date and time of the last execution of a periodic task
• Last duration (sec)
  Duration in seconds of the last execution of a periodic task

You can search the table by task name or status, or apply a filter to display tasks with a certain scheduling interval or status.

Periodic tasks with several planned executions are grouped by default. This means that only the next execution is displayed. The Scheduling option column contains the number of planned executions and a clock icon to see all scheduling options. The Next execution at column shows the data for the next execution and you can hover the clock icon the see all executions. If you want to display each scheduled execution in its own row, e.g. to deactivate or cancel one execution only, you can deselect the Only next executions checkbox.

Advanced tasks

Canceling a task

There are two ways to cancel a running task:

• Locate the task on the Tasks page of the Web Admin Suite and click the Cancel icon 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.

Deactivating a task

By clicking the Deactivate icon, you can deactivate a task with the status Waiting for execution which is needed for the proper functioning of the system but should not be executed at the moment. Deactivated tasks remain in the task list with the status Deactivated. They can be executed again by clicking the Activate icon.

When planning a periodic task, you can select the option Deactivate task after error to deactivate the task if an error occurs during task execution. This affects only the scheduled execution for which the error occurs.

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.

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()