Functions for execution of asynchronous tasks.
Example
var taskLib = require('/lib/xp/task');
Methods
(static) get(taskId) → {TaskInfo}
Returns the current state and progress details for the specified task.
Parameters:
Name | Type | Description |
---|---|---|
taskId |
string | Id of the task. |
Returns:
Detail information for the task. Or null if the task could not be found.
- Type
- TaskInfo
Examples
// Obtains details for an active task
var taskInfo = taskLib.get('7ca603c1-3b88-4009-8f30-46ddbcc4bb19');
if (taskInfo) {
log.info('Current task state = %s', taskInfo.state);
} else {
log.info('Task not found');
}
// Task information returned
var expected = {
"description": "Long running task",
"id": "7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
"name": "task-7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
"state": "RUNNING",
"progress": {
"info": "Processing item 33",
"current": 33,
"total": 42
}
};
(static) isRunning(task) → {boolean}
Checks if any task with the given name or id is currently running.
Parameters:
Name | Type | Description |
---|---|---|
task |
string | Name or id of the task. |
Returns:
True if there is a task with the specified name or id, and state 'RUNNING'; False otherwise.
- Type
- boolean
Example
// Check if a task is currently running
var isRunning = taskLib.isRunning('com.enonic.myapp:clean-up-task');
if (!isRunning) {
log.info('Start task...');
} else {
log.info('Task already running');
}
(static) list(paramsopt) → {Array.<TaskInfo>}
Returns the list of active tasks with their current state and progress details.
Parameters:
Name | Type | Attributes | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
<optional> |
JSON with optional parameters. Properties
|
Returns:
List with task information for every task.
- Type
- Array.<TaskInfo>
Examples
// Obtains list of active tasks
var tasks = taskLib.list();
// Tasks returned
var expected = [
{
"description": "Long running task",
"id": "7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
"name": "task-7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
"state": "RUNNING",
"progress": {
"info": "Processing item 33",
"current": 33,
"total": 42
}
},
{
"description": "Update statistics",
"id": "b6173bcb-bf54-409b-aa6b-96ae6fcec263",
"name": "task-b6173bcb-bf54-409b-aa6b-96ae6fcec263",
"state": "FINISHED",
"progress": {
"info": "Work completed",
"current": 0,
"total": 0
}
},
{
"description": "Import remote data",
"id": "e1f57280-d672-4cd8-b674-98e26e5b69ae",
"name": "task-e1f57280-d672-4cd8-b674-98e26e5b69ae",
"state": "FAILED",
"progress": {
"info": "Fetching data",
"current": 33,
"total": 100
}
}
];
// Obtains list of active tasks with a given name and state
var tasks = taskLib.list({
name: "com.enonic.myapp:clean-up",
state: "RUNNING"
});
// Tasks returned
var expected = [
{
"description": "Long running task",
"id": "7ca603c1-3b88-4009-8f30-46ddbcc4bb19",
"name": "com.enonic.myapp:clean-up",
"state": "RUNNING",
"progress": {
"info": "Processing item 33",
"current": 33,
"total": 42
}
}
];
(static) progress(params)
Reports progress information from an executing task. This function may only be called within the context of a task function, otherwise it will fail and throw an exception.
Parameters:
Name | Type | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON with progress details. Properties
|
Example
// Execute task and keep taskId for polling status
var taskId = taskLib.submit({
description: 'Background task',
task: function () {
taskLib.progress({info: 'Initializing task'});
for (var i = 0; i < 10; i++) {
taskLib.progress({
info: 'Processing item ' + (i + 1),
current: i,
total: 10
});
processItem(i);
}
taskLib.progress({info: 'Task completed'});
}
});
(static) sleep(timeMillis)
Causes the current execution thread to sleep (temporarily cease execution) for the specified number of milliseconds.
Parameters:
Name | Type | Description |
---|---|---|
timeMillis |
string | The length of time to sleep in milliseconds. |
Example
var retries = 3;
var result = fetchRemoteData();
while (!result && retries > 0) {
taskLib.sleep(500); // wait half a second before retrying
retries--;
result = fetchRemoteData();
}
(static) submit(params) → {string}
Submits a task to be executed in the background and returns an id representing the task.
This function returns immediately. The callback function will be executed asynchronously.
Parameters:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON with the parameters. Properties
|
Returns:
Id of the task that will be executed.
- Type
- string
Example
// Execute task and keep taskId for polling status
var taskId = taskLib.submit({
description: 'Background task',
task: function () {
longRunningTask();
}
});
(static) submitNamed(params) → {string}
Submits a named task to be executed in the background and returns an id representing the task.
This function returns immediately. The callback function will be executed asynchronously.
Parameters:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object | JSON with the parameters. Properties
|
Returns:
Id of the task that will be executed.
- Type
- string
Examples
// Execute task, located in the current app, by name
var taskId = taskLib.submitNamed({
name: 'job42',
config: {
count: 123
}
});
// Execute a task located in a different app
var taskId = taskLib.submitNamed({
name: 'com.enonic.app.myapp:work',
config: {}
});
Type Definitions
TaskInfo
Type:
- Object
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id |
string | Task Id. |
||||||||||||
name |
string | Task Id. |
||||||||||||
description |
string | Task description. |
||||||||||||
state |
string | Task state. Possible values: 'WAITING' | 'RUNNING' | 'FINISHED' | 'FAILED' |
||||||||||||
progress |
object | Progress information provided by the running task. Properties
|