Gestions des tasks

14 min

Tasks

Cette version de la gestion des tasks est disponible à partir de la version 2.2.0

Introduction

Les tâches (tasks) sont des fonctions qui peuvent être exécutées par un utilisateur ou par un planificateur (cron) pour des évènements récurrents, par exemple tous les jours à 18h.

Initialisation d'une tâche standard

Dans le fichier de configuration de l'OIP, la propriété tasks contient les tâches disponibles qui peuvent être exécutées grâce au contrôleur runTask.

// config file
import { baseConfig } from './base.config.mjs';

export default {
  ...baseConfig,
  tasks: {
    myTask: myCallback        // a standard task
  }
}

La fonction de rappel sera appelée lors de l'exécution de la tâche.

Initialisation d'une tâche de type CRON

De la même manière que pour une tâche standard, les tâches de type CRON sont à définir dans l'objet de la propriété tasks du fichier de configuration de l'OIP.

// congif file
import { baseConfig } from './base.config.mjs';

export default {
  ...baseConfig,
  tasks: {
    myTask: myCallback,      // a standard task
    myCronTask: {            // a CRON task
      callback: myCronTaskCallback,
      cron: '0 18 * * *'     // every day at 18:00
    }
  }
}

Les tâches de type CRON seront exécutées automatiquement à l'horaire spécifiée en valeur de la propriété cron de la tâche. Il n'est pas nécessaire de passer par le contrôleur runTask pour l'exécution de ce type de tâches.

Exécution d'une tâche

Le contrôleur runTask est exposé par l'OIP pour exécuter une tâche définie dans le fichier de configuration.

Une tâche peut être liée à un projet ou non.

import { runTaskCtrl as runTask } from '@fasstech/oip-core/controllers';

/**
 * @param {string} projectId
 */
export const myProcess = async (projectId) => {
  const { taskId, taskName } = runTask({ 
    taskName: 'myTask', 
    projectId,
    // metadata est disponible à partir de la version 2.4.0 (ou 2.4.0-rc.0)
    metadata: {
      message: 'hello world!'
    }
  });
  console.log(`Task ${taskId}-${taskName} executed successfully`);
};

La propriété taskName passée en paramètre au contrôleur runTask doit correspondre au nom d'une tâche déclarée dans le fichier de configuration de l'OIP.

Mise à jour de l'état d'une tâche

La fonction de rappel d'une tâche est appelée lors de l'exécution de la tâche. L'objet passé en paramètre permet de récupérer la propriété taskHandler.

taskHandler permet d'accéder à la fonction updateState. updateState prend en paramètre un objet de la forme suivante :

{
  state: {
    status: string;
    statusCode: number;
  },
  error: string;
  metadata: any;
}

L'appel à la fonction updateState permet alors de mettre à jour l'état de la tâche courante.

// config file
import { baseConfig } from './base.config.mjs';
import { myTask } from './server/tasks/my-task.mjs';

export default {
  ...baseConfig,
  tasks: {
    myTask,
  }
}

// my-task.mjs
export const myTask = async ({ taskHandler, metadata }) => {
  const updateState = taskHandler.updateState;

  console.log('Task started');
  await new Promise(res => setTimeout(res, 1500)); // heavy processing

  // state update of the current task
  updateState({ state: {
    status: 'IN_PROGRESS', 
    statusCode: 21,
    metadata 
  }});

  console.log('Task in progress');
  await new Promise(res => setTimeout(res, 4200)); // heavy processing

  // state update of the current task
  updateState({ state: {
    status: 'COMPLETED', 
    statusCode: 42,
    metadata: {
      message: 'my message'
    }
  }});
};

// app.mjs
import OIP from '@fasstech/oip-core';

await OIP.start();

Contrôleurs associés à la gestion des tâches

runTaskCtrl

Ce contrôleur remplace le contrôleur déprécié runTask

La gestion du paramètre metadata n'est disponible qu'à partir de la version 2.4.0

Paramètres : { taskName, projectId, metadata }

Ce contrôleur permet d'exécuter une tâche. Si projectId est passé en paramètre, la tâche sera liée à un projet.

Si metadata est passé en paramètre, metadata est alors reçu en paramètre de la callback de la tâche et peut être passé à la méthode updateState exposée par le taskHandler reçu également en paramètre de la callback pour un enregistrement en base de données. Voir l'exemple de la mise à jour de l'état d'une tâche.

Exemple :

import { runTaskCtrl } from '@fasstech/oip-core/controllers';

const { taskId, taskName } = await runTaskCtrl({ 
  taskName: 'magicTask', 
  projectId: 'my-project-id',
  metadata: {
    message: 'hello world!'
  }
});

console.log(`Task #${taskId}-${taskName} executed`);

getTask

Paramètres : { taskName, projectId }

Ce contrôleur permet de récupérer une tâche. Soit uniquement par { taskName } soit par la paire { taskName, projectId } si la tâche est liée à un projet.

Attention, si la tâche n'est pas trouvée, elle est créée dans la base de données si taskName correspond à une tâche définie dans le fichier de configuration de l'OIP mais ne sera pas exécutée.

Exemple :

import { getTask } from '@fasstech/oip-core/controllers';

const task = await getTask({ 
  taskName: 'magicTask', 
  projectId: 'my-project-id'
});

console.log(task);

getAllTasks

Paramètres : { projectId }

Ce contrôleur permet de récupérer toutes les tâches ou toutes les taches liées à un projet si projectId est passé en paramètre.

Exemple :

import { getAllTasks } from '@fasstech/oip-core/controllers';

const tasks = await getAllTasks({});

console.log(tasks);

// or

const tasksFromProject = await getAllTasks({ projectId: 'my-project-id' });

console.log(tasksFromProject);

killCronTask

Paramètres : { taskName }

Ce contrôleur permet de stopper et de supprimer en database une tache de type CRON. taskName doit correspondre au nom d'une tâche de type CRON définie dans le fichier de configuration de l'OIP.

Exemple :

import { killCronTask } from '@fasstech/oip-core/controllers';

const killedTaskName = await killCronTask({ taskName: 'magicTask' });

console.log(killedTaskName);

killAllCronTask

Paramètres : aucun

Ce contrôleur permet de stopper et de supprimer en database toutes les tâches de type CRON.

Exemple :

import { killAllCronTask} from '@fasstech/oip-core/controllers';

await killAllCronTask();