---
title: Déclarer une tâche
slug: oip-next/v4/reference/starter-kit/task
icon: {"lucideIcon":"📘"}
createdAt: 2025-10-09T13:07:20.000Z
---

# Vue d’ensemble

Une tâche représente une action planifiée, identifiée par un type (e.g. envoi d’e-mail, lancement d’un processus de signature électronique).

Une tâche possède une date de déclenchement. À échéance, le service OIP Headless notifie l'OAV en publiant un message via le protocole AMQP. L'OAV exécute alors le code de la tâche dans un processus dédié.

Les *workflows* de tâches permettent de définir un graphe acyclique de dépendances entre tâches. Dans un *workflow* :

- une tâche ne démarre que lorsque toutes ses tâches parentes sont terminées ;
- elle hérite automatiquement des métadonnées de ses tâches parentes.

:::BlockQuote
**Info**
Les commandes SQL ci-dessous doivent être exécutées depuis le container hébergeant la base de données PostgreSQL du service OIP Headless.
:::

# Déclaration d’un type de tâche

## Tâche ponctuelle

Pour enregistrer un type de tâche ponctuelle `my_task`, exécutez :

```shell
psql -U postgres -d oip_headless << EOF
insert into events_types (type, application_id) values('my_task', (select id from applications where name = 'MyApp'));
EOF
```

:::BlockQuote
**Info**
Veillez à remplacer `MyApp` par le nom réel de votre OAV.
:::

## Tâche récurrente

Pour enregistrer un type de tâche récurrente (cron) `my_cron_task`, exécutez :

```shell
psql -U postgres -d oip_headless << EOF
insert into events_types (type, cron, application_id) values('my_cron_task', '0 10 * * *', (select id from applications where name = 'MyApp'));
EOF
```

:::BlockQuote
**Info**
Veillez à remplacer `MyApp` par le nom réel de votre OAV.
:::

La valeur de la colonne `cron` est un 5-uplet.

Elle doit respecter la notation `0 hh jj MMM JJJ` où :

- `hh` représente l'heure (de 0 à 23) ;
- `jj` représente le numéro du jour du mois (de 1 à 31) ;
- `MMM` représente le numéro du mois (de 1 à 12) ;
- `JJJ` représente le numéro du jour dans la semaine (de 0 à 6, 0 correspondant au dimanche).

:::BlockQuote
**Info**
La première valeur représentant les minutes doit être 0.
:::

Exemples :

- `0 13 * * *` : déclenchement à 13h chaque jour ;
- `0 13 1 * *` : déclenchement à 13h le premier jour de chaque mois ;
- `0 13 * * 1` : déclenchement à 13h chaque lundi ;
- `0 13 1 * 1` : déclenchement à 13h le premier jour de chaque mois et chaque lundi ;
- `0 13 1 1 *` : déclenchement à 13h le premier jour du mois de Janvier ;
- `0 13 * 1 1` : déclenchement à 13h chaque lundi au mois de Janvier ;
- `0 13 1 1 1` : déclenchement à 13h le premier jour de chaque mois et chaque lundi au mois de Janvier.

# Déclaration d’un type de workflow de tâches

Pour enregistrer un *workflow* nommé `my_workflow` :

```shell
psql -U postgres -d oip_headless << EOF
insert into events_workflows_types (type, application_id) values('my_workflow', (select id from applications where name = 'MyApp'));
EOF
```

Une fois le *workflow* enregistré, vous pouvez définir les tâches et leurs relations.

## Définition des relations dans un workflow

### Exemple 1

```mermaid
graph TD;
    A-->B;
    A-->C;
```

Le code SQL correspondant est :

```shell
psql -U postgres -d oip_headless << EOF
-- events_types
insert into events_types (type, application_id) values('a', (select id from applications where name = 'MyApp'));
insert into events_types (type, application_id) values('b', (select id from applications where name = 'MyApp'));
insert into events_types (type, application_id) values('c', (select id from applications where name = 'MyApp'));

-- events_relations_types
insert into events_relations_types (src_type_id, tgt_type_id, workflow_type_id) values ((select id from events_types where type = 'a'), (select id from events_types where type = 'b'), (select id from events_workflows_types where type = 'my_workflow'));
insert into events_relations_types (src_type_id, tgt_type_id, workflow_type_id) values ((select id from events_types where type = 'a'), (select id from events_types where type = 'c'), (select id from events_workflows_types where type = 'my_workflow'));
EOF
```

### Exemple 2

```mermaid
graph TD;
    A-->C;
    B-->C;
```

Le code SQL correspondant est :

```shell
psql -U postgres -d oip_headless << EOF
-- events_types
insert into events_types (type, application_id) values('a', (select id from applications where name = 'MyApp'));
insert into events_types (type, application_id) values('b', (select id from applications where name = 'MyApp'));
insert into events_types (type, application_id) values('c', (select id from applications where name = 'MyApp'));

-- events_relations_types
insert into events_relations_types (src_type_id, tgt_type_id, workflow_type_id) values ((select id from events_types where type = 'a'), (select id from events_types where type = 'c'), (select id from events_workflows_types where type = 'my_workflow'));
insert into events_relations_types (src_type_id, tgt_type_id, workflow_type_id) values ((select id from events_types where type = 'b'), (select id from events_types where type = 'c'), (select id from events_workflows_types where type = 'my_workflow'));
EOF
```

# Déclaration du code d’une tâche

Chaque type de tâche doit avoir un fichier dédié dans le dossier `tasks`.
Par exemple, pour une tâche de type `my_task`, le fichier `tasks/my_task.mjs` doit exister.

## Modèle de base d'une tâche

```javascript
const run = async ({ taskName, workflowName, projectId, metadata }) => {
  // Your logic goes here.
  process.exit(0);
};

// IPC channel is used for passing messages between parent and child
process.on('message', (args) => {
  run(args);
});
```

:::BlockQuote
Info
Assurez-vous que le processus enfant se termine correctement en appelant `process.exit(0);`.
:::

Le type de la donnée reçue (`args`) est :

```typescript
{ taskName: string; workflowName?: string; projectId?: string; metadata?: object }
```
