Tasks
Contents
The XP framework also supports execution of asynchronous (potentially long running) background tasks.
Tasks may simply be executed as inline functions, or as named tasks. Named tasks are defined by creating a folder i.e. src/main/resources/tasks/<taskname> in your project.
Descriptor
Named tasks requires a descriptor file. The descriptor must be placed in task folder as follows: src/main/resources/tasks/<taskname>/<taskname>.xml.
<task>
<description>Background job</description>
<form>
<input type="Long" name="count">
<label>Number of items to process</label>
<default>42</default>
<occurrences minimum="1" maximum="1"/>
</input>
</form>
</task>When parameters are passed to the task controller, they will be validated according to the descriptor schema.
The form element in the descriptor XML is optional, and may be left empty if the task does not accept any parameters.
Controller
Named tasks require a controller that represents the actual code to be executed. The controller must be placed in the task folder as src/main/resources/tasks/<taskname>/<taskname>.js.
A named task controller must export a run function, which will be invoked by the task engine. once a task is executed.
The run function will receive the task parameters as a JSON object.
taskId is provided as a second argument of the function
var taskLib = require('/lib/xp/task');
exports.run = function (params, taskId) {
var count = params.count || 42;
taskLib.progress({info: 'Initializing task ' + taskId});
for (var i = 0; i < count; i++) {
taskLib.progress({
info: 'Processing item ' + (i + 1),
current: i,
total: count
});
processItem(i);
}
taskLib.progress({info: 'Task completed ' + taskId});
};Execution
Named tasks may be executed by any controller in the system. Applications may even run tasks in other applications.
Below is an example of how to run a specific task.
var taskLib = require('/lib/xp/task');
var taskId = taskLib.submitTask({
descriptor: `mytask`,
config: {
count: 10
}
}
);Distributable
Named tasks may get distributed over other cluster nodes. Cluster node can be configured to accept or decline distributable tasks execution. If multiple cluster nodes can accept a task, only one cluster node will be selected to execute it. If none of the nodes can accept a distributable task, an error will be thrown.
Distributable task gets executed with the same context (user, repository/branch) it was originally submitted.
Make sure your Named task does not require a specific node to run on (i.e. it must not check for isMaster). If you need such check, use inline function task instead. |
| Nodes that do not accept distributable tasks execution are still capable to submit them. |
| For fine-grained control which nodes should be capable to execute distributable tasks use Application filter config or local apps. Or disable execution of named tasks entirely on some nodes by Task config. |
API
Tasks are capable of producing status reports during execution. This is in particular useful for long running tasks where feedback is crucial.
Additionally, tasks produce a range of pre-defined events throughout their life cycle.
For more details on tasks, visit the task API documentation.
