Tasks

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.

warning

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: If the system property cmas-core-server, task.execution.smart.intervals is set to true, there is no idle time between the execution of two tasks. This can speed up task execution if you have lots of very small tasks. If you set the property to false, the time between to executions is determined by the system property cmas-core-server, task.execution.interval.seconds.
• 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 choose whether the task should be removed, deactivated or rescheduled 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.

info

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