Scheduler Plugin Overview #

This plugin allows to define scheduled tasks at specified intervals expressed in cron syntax.

Documents are stored in a config collection in indexes having a Scheduler Engine.

They can be edited dynamically (with the Admin Console for example) and the associated Task will be automatically planned in accordance with the config document.

Scheduled Tasks #

Tasks are document stored in the database. Each document describe a task:

• execution schedule
• action
• last execution status
• metadata

{
  name: 'Clean abandonned transactions',
  description: 'Task that run daily to clean unpaid transactions',

  // If true, the task won't be executed
  disabled: false,

  // Task scheduling
  schedule: {
    // Syntax type
    syntax: 'cron',

    // Cron string
    value: '0 1 * * *';

    // Humand readable planning (computed)
    humanized: 'Every day at 1 am';

    // Next execution timestamp (computed)
    nextExecution: 1641888701000;
  }

  // Action to be executed
  action: {
    type: 'api',

    // Request payload
    request: {
      controller: 'transactions',
      action: 'clean-unpaid',
    }
  };

  // Last execution status
  status: {
    // Task ID
    id: 'scheduler--task--clean-abandonned-transaction';

    // Last execution timestamp
    executedAt: 1641887701000;

    // Name of cluster node that executed the task
    node: 'knode-envy-einstein-422184';

    // Task error (here an API error)
    error: null

    // Task result (here an API result)
    result: {
      transactions: 4
    };
  };

  metadata: {
    // additional metadata
  };
}

Cluster and multi-tenant environment #

The plugin is designed to work in a masterless cluster environment.

Each node is running it's own timer to executer the next task but a lock is acquired before execution to ensure the task is executed only once.

Also, thanks to the Engine system, the plugin is able to run smoothly in a multi-tenant environment where each tenant has it's own separate index.

Scheduler Engine #

First, you must create a Scheduler Engine on the index you want to enable the Scheduler.

You should use the scheduler/engine:create API action.

Example with Kourou to create an engine on the iot-data index:

kourou scheduler/engine:create iot-data

This will creates or updates the following collections:

• config: contains tasks definition
• scheduled-task-journal: contains execution journal

Task Definition #

Task are documents created in the config collection.

The documents must have the following structure:

{
  type: "scheduled-task",
  "scheduled-task": {
    // Scheduled task content
  }
}

Example:

kourou document:create iot-data config '{
  type: "scheduled-task",

  "scheduled-task": {
    name: "Test Task",
    description: "Asking server time every minute",
    schedule: {
      syntax: "cron",
      value: "* * * * *"
    },
    action: {
      type: "api",
      request: {
        controller: "server",
        action: "now"
      }
    }
  }
}'

Schedule #

The task execution planning should be defined in the schedule property.

The syntax type should be defined in the schedule.syntax property and the associated value in the schedule.value property.

The following syntaxes are available:

• cron: use a cron-like string to plan task execution

The humanized and nextExecution properties will be computed by the plugin.

Example with a task running daily at 23h00 :

{
  // [...]

  schedule: {
    type: 'cron',
    value: '0 23 * * *'
  },
}

Actions #

You can define an action to be executed in the action property.

The action type should be defined in the action.type property.

The following action types are available:

• api: execute an API action

API action #

You need to define which API action should be executed in the action.request property.

Example with a task executing an API action :

{
  // [...]

  action: {
    type: 'api',
    request: {
      controller: 'collection',
      action: 'truncate',
      index: 'iot-data',
      collection: 'payloads',
    }
  },
}

Scheduled Task Journal #

Task execution results are stored in a separated collection: scheduled-tasks-journal.

Each entry contains the following properties:

{
  // Task ID
  "id": "scheduled-task--check-counters-2",

  // Execution timestamp
  "executedAt": 1642569600005,

  // ID of the cluster node who executed the task
  "node": "knode-confused-ungoliant-2354",

  // Result of the task execution
  "result": {
    "cleaned": 32
  },

  // Error of the task execution
  "error": null,
}