Task library

Functions for execution of asynchronous tasks.

Usage

Add the following to your build.gradle file:

dependencies {
  include "com.enonic.xp:lib-task:${xpVersion}"
}

In your JavaScript controller, add a require statement:

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

You are now ready to use the library functionality.

Events

Usage of this API produces the following events:

Table 1. Distributed events
Event	Occurs when
task.submitted	task is submitted
task.updated	task gets updated
task.removed	task is removed
task.finished	task completes
task.failed	task failed

For more information on events, check out the event API

Functions

get

Returns the current state and progress details for the specified task.

Parameters

Name	Type	Description
taskId	string	Id of the task

Name

Type

Description

taskId

string

Id of the task

Returns

object : (TaskInfo) Detail information for the task. Or null if the task could not be found.

Example

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');
}

Return value:

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
  }
};

isRunning

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.

Name

Type

Description

task

string

Name or id of the task.

Returns

boolean : true if there is a task with the specified name or id, and state 'RUNNING'; false otherwise.

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');
}

list

Returns the list of running tasks with their current state and progress details. On clustered environments aggregated list is returned.

Parameters

Name Type Attributes Description

params

object

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

Array : (TaskInfo[]) List with task information for every task.

Example

1. Obtains list of active tasks:

var tasks = taskLib.list();

Return value:

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
    }
  }
];

2. Obtains list of running tasks with a given name and state:

var tasks = taskLib.list({
  name: "com.enonic.myapp:clean-up",
  state: "RUNNING"
});

Return value:

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
    }
  }
];

progress

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

Returns

void

Example

Execute task and keep taskId for polling status:

var taskId = taskLib.executeFunction({
  description: 'Background task',
  func: 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'});
  }
});

sleep

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

Name

Type

Description

timeMillis

number

The length of time to sleep in milliseconds

Returns

void

Example

Execute task and keep taskId for polling status:

var retries = 3;
var result = fetchRemoteData();

while (!result && retries > 0) {
  // wait half a second before retrying
  taskLib.sleep(500);
  retries -= 1;
  result = fetchRemoteData();
}

executeFunction

Executes a function in the background. Returns an id representing the task of execution.

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
func	function	Callback function to be executed asynchronously

Returns

string : Id of the task function that will be executed.

Example

Execute task function and keep taskId for polling status:

var taskId = taskLib.executeFunction({
  description: 'Background function',
  func: function () {
    longRunningFunction();
  }
});

submitTask

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.

lib-task prior version 7.6 does not submit distributable named tasks, instead task always gets executed locally. Recompile your application with the newer library version in order for tasks to be distributable.

Parameters

Name

Type

Description

params

object

JSON with the parameters

Properties
Name	Type	Attributes	Description
descriptor	string		Descriptor of the task to execute. Descriptor can be relative to the current application, or a fully qualified task descriptor name (<appname>:<taskname>)
name	string	<optional>	Optional name of the task which appears in task info. If not specified, descriptor name will be used instead.
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

string : Id of the task that will be executed.

Example

Execute task, located in the current app, by name:

var taskId = taskLib.submitTask({
  descriptor: 'job42',
  config: {
    count: 123
  }
});

Execute a task located in a different app:

var taskId = taskLib.submitTask({
  descriptor: 'com.enonic.app.myapp:work',
  config: {}
});

Properties

Name Type Description

string

Task Id

name

string

Task name

description

string

Task description

state

string

Task state (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

node

string

XP cluster node the task is running on

Properties
Name	Type	Description
current	number	Integer value representing the number of items that have been processed in the task
total	number	Integer value representing the total number of items to process in the task
info	string	Text describing the current progress for the task

Task library

Contents

Usage

Events

Functions

get

isRunning

list

progress

sleep

executeFunction

submitTask

submit

submitNamed

Type Definitions

TaskInfo

Contents

Contents