Programmation¶

Obtenir les types d'emplois disponibles¶

Pour obtenir une liste de tous les types de travaux disponibles, vous pouvez utiliser le point d'extrémité suivant :

GET /api/jobConfigurations/jobTypes

La réponse contient des informations sur chaque type de travail, notamment le nom, le type de travail, la clé, le type de programmation et les paramètres disponibles. Le type de programmation peut être soit CRON, ce qui signifie que les travaux peuvent être programmés en utilisant une expression cron avec le champ cronExpression, soit FIXED_DELAY, ce qui signifie que les travaux peuvent être programmés pour s'exécuter avec un délai fixe entre les deux avec le champ delay. Le champ delay est donné en secondes.

Une réponse ressemblera à ceci :

{
  "jobTypes": [
    {
      "name": "Data integrity",
      "jobType": "DATA_INTEGRITY",
      "key": "dataIntegrityJob",
      "schedulingType": "CRON"
    }, {
      "name": "Resource table",
      "jobType": "RESOURCE_TABLE",
      "key": "resourceTableJob",
      "schedulingType": "CRON"
    }, {
      "name": "Continuous analytics table",
      "jobType": "CONTINUOUS_ANALYTICS_TABLE",
      "key": "continuousAnalyticsTableJob",
      "schedulingType": "FIXED_DELAY"
    }
  ]
}

Configurations de tâches¶

DHIS2 permet de programmer des tâches de différents types. Chaque type de tâche possède des propriétés de configuration différentes, ce qui vous permet de contrôler plus finement la façon dont les tâches sont exécutées. En outre, vous pouvez configurer une même tâche de manière à ce qu'elle s'exécute avec différentes configurations et à différents intervalles, si nécessaire.

Tableau : Principales propriétés

Paramètres de tâches¶

Tableau : Paramètres des tâches de DATA_INTEGRITY.

Tableau : Paramètres des tâches de ANALYTICS_TABLE.

Tableau : Paramètres des tâches de CONTINUOUS_ANALYTICS_TABLE.

Tableau : Paramètres des tâches de DATA_SYNC.

Tableau : Paramètres des tâches de META_DATA_SYNC.

Tableau : Paramètres des tâches MONITORING (Analyse des règles de validation)

Tableau : Paramètres des tâches de PUSH_ANALYSIS.

Tableau : Paramètres des tâches de PREDICTOR.

Tableau : Paramètres des tâches de MATERIALIZED_SQL_VIEW_UPDATE.

Créer une configuration de tâches¶

Pour configurer les tâches, vous pouvez envoyer une requête POST à la ressource suivante :

/api/jobConfigurations

Une tâche sans paramètres au format JSON ressemble à ceci :

{
  "name": "",
  "jobType": "JOBTYPE",
  "cronExpression": "0 * * ? * *",
}

Exemple d'un tableau d'analyse de tâches avec des paramètres au format JSON :

{
  "name": "Analytics tables last two years",
  "jobType": "ANALYTICS_TABLE",
  "cronExpression": "0 * * ? * *",
  "jobParameters": {
    "lastYears": "2",
    "skipTableTypes": [],
    "skipResourceTables": false
  }
}

Exemple d'une tâche d'analyse push avec des paramètres au format JSON :

{
   "name": "Push anlysis charts",
   "jobType": "PUSH_ANALYSIS",
   "cronExpression": "0 * * ? * *",
   "jobParameters": {
     "pushAnalysis": [
       "jtcMAKhWwnc"
     ]
    }
 }

Exemple de tâche avec le type de planification FIXED_DELAY et un délai de 120 secondes :

{
  "name": "Continuous analytics table",
  "jobType": "CONTINUOUS_ANALYTICS_TABLE",
  "delay": "120",
  "jobParameters": {
    "fullUpdateHourOfDay": 4
  }
}

Obtenir des configurations de tâches¶

Liste de toutes les configurations de tâches :

GET /api/jobConfigurations

Récupérer une tâche :

GET /api/jobConfigurations/{id}

Le contenu de la réponse se présente comme suit :

{
  "lastUpdated": "2018-02-22T15:15:34.067",
  "id": "KBcP6Qw37gT",
  "href": "http://localhost:8080/api/jobConfigurations/KBcP6Qw37gT",
  "created": "2018-02-22T15:15:34.067",
  "name": "analytics last two years",
  "jobStatus": "SCHEDULED",
  "displayName": "analytics last two years",
  "enabled": true,
  "externalAccess": false,
  "jobType": "ANALYTICS_TABLE",
  "nextExecutionTime": "2018-02-26T03:00:00.000",
  "cronExpression": "0 0 3 ? * MON",
  "jobParameters": {
    "lastYears": 2,
    "skipTableTypes": [],
    "skipResourceTables": false
  },
  "favorite": false,
  "configurable": true,
  "access": {
    "read": true,
    "update": true,
    "externalize": true,
    "delete": true,
    "write": true,
    "manage": true
  },
  "lastUpdatedBy": {
    "id": "GOLswS44mh8"
  },
  "favorites": [],
  "translations": [],
  "userGroupAccesses": [],
  "attributeValues": [],
  "userAccesses": []
}

Mettre à jour la configuration d'une tâche¶

Mettre à jour une tâche avec des paramètres en utilisant le endpoint et le format de charge JSON suivants :

PUT /api/jobConfigurations/{id}

{
  "name": "analytics last two years",
  "enabled": true,
  "cronExpression": "0 0 3 ? * MON",
  "jobType": "ANALYTICS_TABLE",
  "jobParameters": {
    "lastYears": "3",
    "skipTableTypes": [],
    "skipResourceTables": false
  }
}

Supprimer la configuration d'une tâche¶

Supprimer une tâche en utilisant :

DELETE /api/jobConfigurations/{id}

Notez que certaines tâches avec des paramètres de configuration personnalisés peuvent ne pas être ajoutées si les paramètres système requis ne sont pas configurés. C'est le cas par exemple de la synchronisation des données, qui nécessite la configuration d'un serveur distant.

Exécuter des tâches manuellement¶

Les tâches peuvent être exécutées manuellement à l'aide de :

POST /api/jobConfigurations/{id}/execute

Searching for jobs with execution errors¶

Since version 2.41 jobs can store errors of the job run to allow inspection at a later point in time.

Note This feature is only accessible for administrator with the F_JOB_LOG_READ authority and superusers.

To view the errors associated with a specific job use:

GET /api/jobConfigurations/{id}/errors

To search for jobs that match user specified search criteria use:

GET /api/jobConfigurations/errors

with one or more of the following search parameters

• user: include jobs ran by this user
• from: include jobs that started after this point in time
• to: include jobs that did not start later than this point in time
• code: include jobs that have errors with one of the given error codes
• object: include jobs that have errors linked to one of the given object IDs
• type: include job with errors of the specified type(s)

When multiple criteria are used all have to be met (AND logic). If multiple code, object or type parameters are given just one has to match (OR logic).

For example, to find tracker import errors for the 1. of January 2024 with error code E1002 (tracked entity already exists) the following search is made:

GET /api/jobConfigurations/errors?type=TRACKER_IMPORT_JOB&code=E1002&from=2024-01-01&to=2024-01-02

The results show the job run error details. By default, the input (the payload of the impport) is excluded from the results. To include it add includeInput=true:

GET /api/jobConfigurations/errors?includeInput=true

Note Not all job types do store their errors. Currently, this feature is mostly supported by import jobs.

API du programmateur¶

Alors que /api/jobConfigurations est centré sur les objets de configuration des tâches l'API /api/scheduler reflète l'état du programmateur et l'API /api/scheduling fournit des informations sur la progression des tâches.

Observer les tâches en cours d'exécution¶

Les étapes et l'état d'exécution peuvent être observés pendant que la tâche est en cours. Une liste de tous les types de tâches en cours d'exécution est fournie par :

GET /api/scheduling/running/types

Pour obtenir un aperçu de toutes les tâches en cours d'exécution par type de tâche, utilisez :

GET /api/scheduling/running

Comme il ne peut y avoir qu'une seule tâche en cours pour chaque type à la fois, l'état d'une tâche en cours peut être visualisé en détail à l'aide de la commande suivante:

GET /api/scheduling/running/{type}

Par exemple, pour voir l'état d'une tâche ANALYTICS_TABLE en cours d'exécution, utilisez

GET /api/scheduling/running/ANALYTICS_TABLE

Une tâche est une séquence de processus. Chaque processus comporte une séquence d'étapes Dans chaque étape, il peut y avoir zéro, un ou plusieurs éléments. Les éléments peuvent être traités de manière strictement séquentielle ou parallèle, n éléments à la fois. Souvent, le nombre d'éléments total est souvent connu à l'avance.

En général, les étapes d'un processus et les éléments d'une étape sont « découverts » en tant qu'« effet secondaire » du traitement des données. Alors que la plupart des processus ont une séquence fixe d'étapes, certains processus peuvent avoir des étapes variables en fonction des données traitées. Les éléments dépendent généralement des données. La plupart des travaux ne comprennent qu'un seul processus.

Chacun des nœuds de l'arbre processus-étape-élément a un statut qui est soit * RUNNING (en cours de traitement) : le traitement est en cours (pas encore terminé) * SUCCESS (succès) : lorsque le traitement est terminé avec succès * ERROR (erreur) : lorsque le traitement est terminé avec des erreurs ou lorsqu'une exception s'est produite * CANCELLED (annulé) : lorsque l'annulation a été demandée et que l'élément ne sera pas terminé.

Voir les tâches terminées¶

Une fois qu'une tâche s'est achevée avec succès ou avec un échec à la suite d'une exception ou d'une annulation, l'état passe de l'ensemble des états d'exécution aux états des tâches achevées. Cet ensemble ne conserve que l'état d'exécution le plus récent pour chaque type de tâche. L'aperçu est disponible à l'adresse suivante :

GET /api/scheduling/completed

Des détails sur un type de tâche particulier sont donc fournis à l'adresse suivante :

GET /api/scheduling/completed/{type}

Dans le cas de la tâche ANALYTICS_TABLE, ce serait :

GET /api/scheduling/completed/ANALYTICS_TABLE

Demande d'annulation d'une tâche en cours¶

Une fois qu'une tâche est lancée, elle se déroule selon une séquence d'étapes. Chaque étape peut à son tour comporter des collections d'éléments à traiter. Bien que les tâches ne puissent généralement pas être arrêtées à tout moment, nous pouvons demander une annulation et le processus s'arrête de manière coopérative une fois qu'il a terminé un élément ou une étape et qu'il reconnaît qu'une annulation a été demandée. Cela signifie que les tâches ne s'arrêtent pas immédiatement et ne partent pas à un moment inconnu en plein milieu d'un traitement. Au contraire, elles s'arrêtent lorsqu'il est possible de passer à la fin. Cela signifie toujours que le processus global est inachevé et qu'il n'est pas annulé. Il se peut qu'il ait simplement effectué un certain nombre d'étapes et en ait sauté d'autres à la fin.

Pour annuler une tâche en cours, utilisez :

POST /api/scheduling/cancel/{type}

Par exemple, pour annuler l'exécution de la tâche ANALYTICS_TABLE :

POST /api/scheduling/cancel/ANALYTICS_TABLE

En fonction de l'étape en cours et de l'élément exécuté, l'annulation peut prendre de quelques millisecondes à quelques minutes avant d'être effective. Cependant, le statut de l'ensemble du processus sera affiché comme ANNULÉ immédiatement après avoir été vérifié à l'aide de

GET /api/scheduling/running/ANALYTICS_TABLE

Seuls les tâches qui ont été scindées en processus, étapes et éléments peuvent être annulées de manière efficace. Toutes les tâches n'ont pas encore été scindées. Celles-ci seront exécutées jusqu'à leur terme, même si l'annulation a été demandée.

Reset a Job stuck in RUNNING state¶

When a server shuts down while a job is in RUNNING state the job needs to be reverted back to its initial state manually.

To revert a job that has RUNNING state but is not running use:

POST /api/jobConfigurations/{uid}/revert

Les files d'attente¶

Des séquences de tâches (configurations) peuvent être créées à l'aide de files d'attente. La file d'attente utilise toujours un nom unique et un déclencheur d'expression CRON. Une fois qu'une file d'attente est lancée, toutes les tâches qu'elle contient sont exécutées dans l'ordre indiqué. La deuxième file d'attente démarre lorsque la première est terminée, et ainsi de suite.

Liste des noms des files d'attente¶

Pour répertorier les noms uniques des files d'attente existantes, utilisez :

GET /api/scheduler/queues

La réponse est un tableau de noms :

["queue_a", "queue_b"]

Obtenir une file d'attente de tâches¶

Pour obtenir tous les détails d'une file d'attente spécifique, utilisez :

GET /api/scheduler/queues/{name}

Les détails comprennent son nom, l'expression CRON et la séquence de la tâche :

{
  "name": "myQ",
  "cronExpression": "0 0 1 ? * *",
  "sequence": ["FgAxa6eRSzQ", "BeclVERfWbg" ]
}

Créer une nouvelle file d'attente¶

Pour créer une nouvelle file d'attente, envoyez une requête POST avec un objet de charge utile portant le nom, l'expression CRON et la séquence de tâches :

POST /api/scheduler/queues/{name}

Pour créer une file d'attente avec le nom myQ, utilisez un POST vers /api/scheduler/queues/myQ :

{
  "cronExpression": "0 0 1 ? * *",
  "sequence": ["FgAxa6eRSzQ", "BeclVERfWbg" ]
}

REMARQUE

L'expression cron de toutes les configurations de tâches, sauf la première dans une file d'attente, est effacée car elles n'ont plus de déclencheur propre. Elle doit être restaurée manuellement lorsqu'une tâche est supprimée d'une file d'attente.

Mise à jour d'une file d'attente de tâches¶

Pour mettre à jour une expression ou une séquence CRON existante, utilisez une requête PUT.

PUT /api/scheduler/queues/{name}

La charge utile doit contenir à la fois une nouvelle expression CRON et une séquence de tâches, comme dans l'exemple ci-dessus pour créer une nouvelle file d'attente.

To rename a queue the new name can be stated in the payload, while the old name is used in the URL path.

Supprimer une file d'attente¶

Pour supprimer une file d'attente, envoyez une demande de suppression (DELETE) à l'URL de sa ressource :

DELETE /api/scheduler/queues/{name}

REMARQUE

La suppression d'une file d'attente n'entraîne pas la suppression des configurations de tâches référencées. Toute configuration de tâches supprimée d'une file d'attente, soit en modifiant la séquence, soit en supprimant la file d'attente, est désactivée. Pour l'utiliser individuellement, il faut fournir une expression CRON et réactiver la configuration.

Programmateur de tâches¶

La planification au sein du programmateur est une liste basée sur les configurations et les files d'attente de tâches. Une saisie dans le calendrier est soit une simple configuration de tâches, soit une file d'attente de tâches. Les deux sont représentés par le même format de saisie.

Pour obtenir la liste du programmateur, utilisez :

GET /api/scheduler

Une configuration de tâche dans cette liste se présente comme suit :

  {
    "name": "User account expiry alert",
    "type": "ACCOUNT_EXPIRY_ALERT",
    "cronExpression": "0 0 2 ? * *",
    "nextExecutionTime": "2023-03-15T02:00:00.000",
    "status": "SCHEDULED",
    "enabled": true,
    "configurable": false,
    "sequence": [
      {
        "id": "fUWM1At1TUx",
        "name": "User account expiry alert",
        "type": "ACCOUNT_EXPIRY_ALERT",
        "cronExpression": "0 0 2 ? * *",
        "nextExecutionTime": "2023-03-15T02:00:00.000",
        "status": "SCHEDULED"
      }
    ]
  }

Une file d'attente dans la liste se présente comme suit :

  {
    "name": "myQ",
    "type": "Sequence",
    "cronExpression": "0 0 1 ? * *",
    "nextExecutionTime": "2023-03-15T01:00:00.000",
    "status": "SCHEDULED",
    "enabled": true,
    "configurable": true,
    "sequence": [
      {
        "id": "FgAxa6eRSzQ",
        "name": "test Q1",
        "type": "ANALYTICS_TABLE",
        "cronExpression": "0 0 1 ? * *",
        "nextExecutionTime": "2023-03-15T01:00:00.000",
        "status": "SCHEDULED"
      },
      {
        "id": "BeclVERfWbg",
        "name": "est Q2",
        "type": "DATA_INTEGRITY",
        "status": "SCHEDULED"
      }
    ]
  }

Liste des tâches Saisies pouvant être ajoutées à une file d'attente de tâches¶

Toutes les configurations de tâches ne peuvent pas être ajoutées à une file d'attente. Les tâches système et les tâches qui font déjà partie d'une file d'attente ne peuvent pas être utilisées dans une autre file d'attente. Pour répertorier les configurations de tâches qui peuvent faire partie de n'importe quelle file d'attente, utilisez :

GET /api/scheduler/queueable

Pour dresser la liste des configurations de tâches qui peuvent faire partie d'une file d'attente particulière, utilisez :

GET /api/scheduler/queueable?name={queue}

Cela exclura également toutes les tâches qui font déjà partie de la file d'attente nommée.