task

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",
    "application": "com.enonic.myapp",
    "user": "user:store:me",
    "startTime": "2017-10-01T09:00:00Z",
    "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
Name Type Attributes Description
name string <optional>

Filter by name.

state object <optional>

Filter by task state ('WAITING' | 'RUNNING' | 'FINISHED' | 'FAILED').

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",
        "application": "com.enonic.app1",
        "user": "user:store:user1",
        "startTime": "2017-10-01T09:00:00Z",
        "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",
        "application": "com.enonic.app2",
        "user": "user:store:user2",
        "startTime": "2017-10-02T09:00:00Z",
        "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",
        "application": "com.enonic.app3",
        "user": "user:store:user3",
        "startTime": "2017-10-03T09:00:00Z",
        "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",
        "application": "com.enonic.myapp",
        "user": "user:store:user",
        "startTime": "2017-10-01T09:00:00Z",
        "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
Name Type Attributes Description
current number <optional>

Integer value representing the number of items that have been processed in the task.

total number <optional>

Integer value representing the total number of items to process in the task.

info string <optional>

Text describing the current progress for the task.

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 number

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
Name Type Description
description string

Text describing the task to be executed.

task function

Callback function to be executed asynchronously.

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
Name Type Attributes Description
name string

Name of the task to execute.

config object <optional>

Configuration parameters to pass to the task to be executed. The object must be valid according to the schema defined in the form of the task descriptor XML.

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 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.

Properties
Name Type Description
current number

Latest progress current numeric value.

total number

Latest progress target numeric value.

info string

Latest progress textual information.