Task Management

const tasks = require('@arangodb/tasks')

Note: If you are trying to schedule tasks in Foxx you shouldconsider using the Foxx queues module instead,which provides a more high-level API that also persists tasks across reboots.

Introduction to Task Management in ArangoDB

ArangoDB can execute user-defined JavaScript functions as one-shotor periodic tasks. This functionality can be used to implement timedor recurring jobs in the database.

Tasks in ArangoDB consist of a JavaScript snippet or function that isexecuted when the task is scheduled. A task can be a one-shot task(meaning it is run once and not repeated) or a periodic task (meaningthat it is re-scheduled after each execution). Tasks can have optionalparameters, which are defined at task setup time. The parametersspecified at task setup time will be passed as arguments to thetask whenever it gets executed. Periodic Tasks have an execution frequency that needs to be specified when the task is set up. One-shottasks have a configurable delay after which they’ll get executed.

Tasks will be executed on the server they have been set up on. Tasks will not be shipped around in a cluster. A task will be executed in the context of the database it was created in. However,when dropping a database, any tasks that were created in the contextof this database will remain active. It is therefore sensible tofirst unregister all active tasks for a database before dropping thedatabase.

Tasks registered in ArangoDB will be executed until the servergets shut down or restarted. After a restart of the server, any user-defined one-shot or periodic tasks will be lost.

Commands for Working with Tasks

ArangoDB provides the following commands for working with tasks.All commands can be accessed via the tasks module, which can beloaded like this:

require("@arangodb/tasks")

Please note that the tasks module is available inside the ArangoDBserver only. It cannot be used from the ArangoShell or ArangoDB’s webinterface.

Register a task

To register a task, the JavaScript snippet or function needs to bespecified in addition to the execution frequency. Optionally, a taskcan have an id and a name. If no id is specified, it will be auto-assignedfor a new task. The task id is also the means to access or unregister atask later. Task names are informational only. They can be used to makea task distinguishable from other tasks also running on the server.

The following server-side commands register a task. The command to beexecuted is a JavaScript string snippet which prints a message to the server’s logfile:

const tasks = require("@arangodb/tasks");
tasks.register({
  id: "mytask-1",
  name: "this is a snippet task",
  period: 15,
  command: "require('console').log('hello from snippet task');"
});

The above has register a task with id mytask-1, which will be executedevery 15 seconds on the server. The task will write a log message wheneverit is invoked.

Tasks can also be set up using a JavaScript callback function like this:

const tasks = require("@arangodb/tasks");
tasks.register({
  id: "mytask-2",
  name: "this is a function task",
  period: 15,
  command: function () {
    require('console').log('hello from function task');
  }
});

It is important to note that the callback function is late bound and will be executed in a different context than in the creation context. The callback function must therefore not access any variables defined outside of its own scope. The callback function can still define anduse its own variables.

To pass parameters to a task, the params attribute can be set whenregistering a task. Note that the parameters are limited to data typesusable in JSON (meaning no callback functions can be passed as parametersinto a task):

const tasks = require("@arangodb/tasks");
tasks.register({
  id: "mytask-3",
  name: "this is a parameter task",
  period: 15,
  command: function (params) {
    var greeting = params.greeting;
    var data = JSON.stringify(params.data);
    require('console').log('%s from parameter task: %s', greeting, data);
  },
  params: { greeting: "hi", data: "how are you?" }
});

Registering a one-shot task works the same way, except that the period attribute must be omitted. If period is omitted, then thetask will be executed just once. The task invocation delay can optionallybe specified with the offset attribute:

const tasks = require("@arangodb/tasks");
tasks.register({
  id: "mytask-once",
  name: "this is a one-shot task",
  offset: 10,
  command: function (params) {
    require('console').log('you will see me just once!');
  }
});

Note: When specifying an offset value of 0, ArangoDB will internally add a very small value to the offset so will be slightly greater than zero.

Unregister a task

After a task has been registered, it can be unregistered using its id:

const tasks = require("@arangodb/tasks");
tasks.unregister("mytask-1");

Note that unregistering a non-existing task will throw an exception.

List all tasks

To get an overview of which tasks are registered, there is the get method. If the get method is called without any arguments, it willreturn an array of all tasks:

const tasks = require("@arangodb/tasks");
tasks.get();

If get is called with a task id argument, it will return information about this particular task:

const tasks = require("@arangodb/tasks");
tasks.get("mytask-3");

The created attribute of a task reveals when a task was created. It isreturned as a Unix timestamp.