Agendamento¶

Get available job types¶

Para obter uma lista de todos os tipos de trabalho disponíveis, você pode usar o seguinte endpoint:

GET /api/jobConfigurations/jobTypes

A resposta contém informações sobre cada tipo de trabalho, incluindo nome, tipo de trabalho, chave, tipo de agendamento e parâmetros disponíveis. O tipo de agendamento pode ser CRON, o que significa que as tarefas podem ser agendadas usando uma expressão cron com o campocronExpression, ou FIXED_DELAY, o que significa que as tarefas podem ser agendadas para serem executadas com um atraso fixo entre o campodelay . O atraso do campo é dado em segundos.

Uma resposta será semelhante a esta:

{
  "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"
    }
  ]
}

Job Configurations¶

O DHIS2 permite o agendamento de trabalhos de vários tipos. Cada tipo de trabalho possui propriedades diferentes para configuração, oferecendo um controle mais preciso sobre como os trabalhos são executados. Além disso, você pode configurar o mesmo trabalho para ser executado com configurações diferentes e em intervalos diferentes, se necessário.

Job Parameters¶

Create a Job Configuration¶

Para configurar trabalhos, você pode fazer uma solicitação POST para o seguinte recurso:

/ api / jobConfigurations

Um trabalho sem parâmetros no formato JSON se parece com isto:

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

Um exemplo de trabalho de tabela analítica com parâmetros no formato JSON:

`json { "name": "Tabelas analíticas nos últimos dois anos", "jobType": "ANALYTICS_TABLE", "cronExpression": "0 * *? * *", "jobParameters": { "lastYears": "2", "skipTableTypes": [], "skipResourceTables": false } } `

Como exemplo de um trabalho de análise push com parâmetros no formato JSON:

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

Um exemplo de trabalho com tipo de programação FIXED_DELAY e 120 segundos de atraso:

`json { "nome": "Tabela de análise contínua", "jobType": "CONTINUOUS_ANALYTICS_TABLE", "atraso": "120", "jobParameters": { "fullUpdateHourOfDay": 4 } } `

Get Job Configurations¶

Liste todas as configurações de trabalho:

GET /api/jobConfigurations

Recupere um trabalho:

GET /api/jobConfigurations/{id}

A carga útil da resposta é semelhante a esta:

`json { "lastUpdated": "2018-02-22T15: 15: 34.067", "id": "KBcP6Qw37gT", "href": "http: // localhost: 8080 / api / jobConfigurations / KBcP6Qw37gT", "criado": "22-02-2018T15: 15: 34.067", "nome": "análise dos últimos dois anos", "jobStatus": "SCHEDULED", "displayName": "análises nos últimos dois anos", "ativado": verdadeiro, "externalAccess": falso, "jobType": "ANALYTICS_TABLE", "nextExecutionTime": "26/02/2018T03: 00: 00.000", "cronExpression": "0 0 3? * MON", "jobParameters": { "lastYears": 2, "skipTableTypes": [], "skipResourceTables": false }, "favorito": falso, "configurável": verdadeiro, "Acesso": { "ler": verdadeiro, "update": verdadeiro, "externalizar": verdadeiro, "delete": verdadeiro, "verdade Branca, "gerenciar": verdadeiro }, "lastUpdatedBy": { "id": "GOLswS44mh8" }, "favoritos": [], "traduções": [], "userGroupAccesses": [], "attributeValues": [], "userAccesses": [] } `

Update a Job Configuration¶

Atualizar um trabalho com parâmetros usando o seguinte endpoint e formato de carga útil JSON:

PUT /api/jobConfiguration/{id}

`json { "nome": "análise dos últimos dois anos", "ativado": verdadeiro, "cronExpression": "0 0 3? * MON", "jobType": "ANALYTICS_TABLE", "jobParameters": { "lastYears": "3", "skipTableTypes": [], "skipResourceTables": false } } `

Delete a Job Configuration¶

Exclua um trabalho usando:

DELETE / api / jobConfiguration / {id}

Note that some jobs with custom configuration parameters may not be added if the required system settings are not configured. An example of this is data synchronization, which requires remote server configuration.

Run Jobs Manually¶

Jobs can be run manually using:

POST /api/jobConfiguration/{id}/execute

Scheduler API¶

While /api/jobConfigurations is centered around the job configuration objects the /api/scheduler API reflects the state of the scheduler and the /api/scheduling API provides job progress tracking information.

Observe Running Jobs¶

The execution steps and state can be observed while the job is running. A list of all types of jobs that are currently running is provided by:

GET /api/scheduling/running/types

To get an overview of all running jobs by job type use:

GET /api/scheduling/running

As there only can be one job running for each type at a time the status of a running job can be viewed in details using:

GET /api/scheduling/running/{type}

For example, to see status of a running ANALYTICS_TABLE job use

GET /api/scheduling/running/ANALYTICS_TABLE

A job is a sequence of processes. Each process has a sequence of stages. Within each stage there might be zero, one or many items. Items could be processed strictly sequential or parallel, n items at a time. Often the number of totalItems is known up-front.

In general the stages in a process and the items in a stage are "discovered" as a "side effect" of processing the data. While most processes have a fixed sequence of stages some processed might have varying stages depending on the data processed. Items are usually data dependent. Most jobs just include a single process.

Each of the nodes in the process-stage-item tree has a status that is either * RUNNING: is currently processed (not yet finished) * SUCCESS: when completed successful * ERROR: when completed with errors or when an exception has occurred * CANCELLED: when cancellation was requested and the item will not complete

See Completed Job Runs¶

Once a job has completed successful or with a failure as a consequence of an exception or cancellation the status moves from the set of running states to the completed job states. This set keeps only the most recent execution state for each job type. The overview is available at:

GET /api/scheduling/completed

Details on a particular job type are accordingly provided at:

GET /api/scheduling/completed/{type}

In case of the ANALYTICS_TABLE job this would be:

GET /api/scheduling/completed/ANALYTICS_TABLE

Request Cancelling a Running Jobs¶

Once a job is started it works through a sequence of steps. Each step might in turn have collections of items that are processed. While jobs usually cannot be stopped at any point in time we can request cancellation and the process gives up cooperatively once it has completed an item or step and recognises that a cancellation was requested. This means jobs do not stop immediately and leave at an unknown point right in the middle of some processing. Instead, they give up when there is an opportunity to skip to the end. This still means that the overall process is unfinished and is not rolled back. It might just have done a number of steps and skipped others at the end.

To cancel a running job use:

POST /api/scheduling/cancel/{type}

For example, to cancel the ANALYTICS_TABLE job run:

POST /api/scheduling/cancel/ANALYTICS_TABLE

Depending on the current step and item performed this can take from milliseconds to minutes before the cancellation becomes effective. However, the status of the overall process will be shown as CANCELLED immediately when check using

GET /api/scheduling/running/ANALYTICS_TABLE

Only jobs that have been split into processes, stages and items can be cancelled effectively. Not all jobs have been split yet. These will run till completion even if cancellation has been requested.

Job Queues¶

Sequences of jobs (configurations) can be created using job queues. The queue always uses a unique name and a CRON expression trigger. Once a queue is started it runs all jobs in the queue in the given sequence. The second in sequence starts when the first is finished and so forth.

List Names of Job Queues¶

To list the unique names of existing queues use:

GET /api/scheduler/queues

The response is a array of the names:

["queue_a", "queue_b"]

Get A Job Queue¶

To get all details of a specific queue use:

GET /api/scheduler/queues/{name}

The details include its name, CRON expression and job sequence:

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

Create a new Job Queue¶

To create a new queue send a POST request with a payload object having name, CRON expression and the job sequence:

POST /api/scheduler/queues/{name}

To create a queue with name myQ use a POST to /api/scheduler/queues/myQ:

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

NOTE

The cron expression of all job configurations but the first in a queue is cleared as they do not have a trigger on their own any longer. It needs to be restored manually once a job is removed from a queue.

Update a Job Queue¶

To update an existing queue CRON expression or sequence use a PUT request

PUT /api/scheduler/queues/{name}

The payload has to state both new CRON expression and job sequence like in the example above to create a new queue.

Delete a Job Queue¶

To delete a job queue send a DELETE request to its resource URL:

DELETE /api/scheduler/queues/{name}

NOTE

Deleting a queue does not delete any referenced job configurations. Any job configuration that is removed from a queue either by changing the sequence or deleting the queue is disabled. To use it individually supply a CRON expression and enable the configuration again.

Job Scheduler¶

The schedule within the scheduler is a list that is based on job configurations and job queues. Either an entry in the schedule is a simple job configuration, or it is a job queue. Both are represented using the same entry format.

To get the scheduler listing use:

GET /api/scheduler

A job configuration in this list looks like this:

  {
    "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"
      }
    ]
  }

A job queue in the list looks like this:

  {
    "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"
      }
    ]
  }

List Jobs Entries addable to a Job Queue¶

Not all jon configurations can be added to a queue. System jobs and jobs that are already part of a queue cannot be used in another queue. To list job configurations that can be part of any queue use:

GET /api/scheduler/queueable

To list job configurations that can be part of a particular queue use:

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

This will also exclude all jobs that are already part the named queue.