Tasks allow the asynchronous execution of jobs. Each task has a name, a JavaScript controller file, and an XML descriptor in the folder tasks/[task-name]


The task descriptor is an XML file that defines configuration parameters for the task.

When parameters are passed to the task controller, they will be validated according to the XML config schema (see Schemas).

The config element in the descriptor XML is optional. It can be left empty if the task does not take any parameters.

The descriptor file must have the same name as the task, i.e. tasks/[task-name]/[task-name].xml:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <description>Background job</description>
    <input type="Long" name="count">
      <label>Number of items to process</label>
      <occurrences minimum="1" maximum="1"/>


A task controller handles the execution of the task. The controller is a required file written in JavaScript and must have the same name as the task, i.e. tasks/[task-name]/[task-name].js.

A task controller must export a run function, that will be called when the task is executed. The run function will receive the task parameters as a JSON object.

The following is an example of task controller.

var taskLib = require('/lib/xp/task');

exports.run = function (params) {

    var count = params.count || 42;

    taskLib.progress({info: 'Initializing task'});

    for (var i = 0; i < count; i++) {
            info: 'Processing item ' + (i + 1),
            current: i,
            total: count


    taskLib.progress({info: 'Task completed'});


Using Tasks

Tasks can be started by calling the submitNamed function in lib-task library.

Task Properties

A running task has the following properties, which can be obtained using the functions in lib-task library

Name Type Description
id string Task unique id.
name string Task name.
description string Task description.
state string Task state. Possible values: WAITING, RUNNING, FINISHED, FAILED
application string Application containing the callback function to run.
user string Key of the user that submitted the task.
startTime string Time when the task was submitted (in ISO-8601 format).
progress Object Progress information provided by the running task.
progress.current number Latest progress current numeric value.
progress.total number Latest progress target numeric value.
progress.info string Latest progress textual information.