Plánování¶

Get available job types¶

Chcete-li získat seznam všech dostupných typů úloh, můžete použít následující koncový bod:

GET /api/jobConfigurations/jobTypes

Odpověď obsahuje informace o každém typu úlohy, včetně názvu, typu úlohy, klíče, typu plánování a dostupných parametrů. Typ plánování může být buď CRON, což znamená, že úlohy lze naplánovat pomocí výrazu cron s polem cronExpression, nebo FIXED_DELAY, což znamená, že je možné naplánovat spuštění úloh s pevným zpožděním mezi polem delay. Zpoždění pole se udává v sekundách.

Odpověď bude vypadat podobně jako tato:

{
  "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¶

DHIS2 umožňuje plánování úloh různých typů. Každý typ úlohy má různé vlastnosti pro konfiguraci, což vám dává lepší kontrolu nad tím, jak jsou úlohy spouštěny. Kromě toho můžete nakonfigurovat stejnou úlohu tak, aby běžela s různými konfiguracemi a v případě potřeby v různých intervalech.

Tabulka: Hlavní vlastnosti

Parametry úlohy¶

Tabulka: Parametry úlohy DATA_INTEGRITY

Tabulka: Parametry úlohy ANALYTICS_TABLE

Tabulka: Parametry úlohy CONTINUOUS_ANALYTICS_TABLE

Tabulka: Parametry úlohy DATA_SYNC

Tabulka: Parametry úlohy META_DATA_SYNC

Tabulka: Parametry úlohy MONITOROVÁNÍ (analýza ověřovacích pravidel).

Tabulka: Parametry úlohy PUSH_ANALYSIS

Tabulka: Parametry úlohy PREDICTOR

Create a Job Configuration¶

Chcete-li konfigurovat úlohy, můžete provést požadavek POST na následující prostředek:

/api/jobConfigurations

Úloha bez parametrů ve formátu JSON vypadá takto:

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

Příklad úlohy analytické tabulky s parametry ve formátu JSON:

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

Jako příklad úlohy nabízené analýzy s parametry ve formátu JSON:

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

Příklad úlohy s typem plánování FIXED_DELAY a 120 sekundovým zpožděním:

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

Get Job Configurations¶

Seznam všech konfigurací úloh:

GET /api/jobConfigurations

Načtení úlohy:

GET /api/jobConfigurations/{id}

Datový obsah odpovědi vypadá takto:

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

Update a Job Configuration¶

Aktualizujte úlohu s parametry pomocí následujícího formátu koncového bodu a datového obsahu JSON:

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
  }
}

Delete a Job Configuration¶

Smazat úlohu pomocí:

DELETE /api/jobConfigurations/{id}

Některé úlohy s vlastními konfiguračními parametry nemusí být přidány, pokud nejsou nakonfigurována požadovaná nastavení systému. Příkladem toho je synchronizace dat, která vyžaduje konfiguraci vzdáleného serveru.

Run Jobs Manually¶

Úlohy lze spustit ručně pomocí:

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.

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}

Chcete-li například zobrazit stav použití spuštěné úlohy ANALYTICS_TABLE.

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.

Každý z uzlů ve stromu procesu-fáze-položky má stav, který je buď * RUNNING: aktuálně zpracováno (ještě nedokončeno) * SUCCESS: po úspěšném dokončení * CHYBA: po dokončení s chybami nebo když došlo k výjimce * ZRUŠENO: když bylo požadováno zrušení a položka se nedokončí

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

Podrobnosti o konkrétním typu práce jsou odpovídajícím způsobem uvedeny na:

GET /api/scheduling/completed/{type}

V případě úlohy ANALYTICS_TABLE by to bylo:

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.

Chcete-li zrušit běžící úlohu, použijte:

POST /api/scheduling/cancel/{type}

Chcete-li například zrušit spuštění úlohy ANALYTICS_TABLE, postupujte takto:

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.

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

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.

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

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.