On this page:

27.2Batch Job Endpoint

 

The Batch Job Endpoint can be used to view the status of running background jobs.

27.2.1Fetch Batch Job Names

 
This method requires the VIEW_BATCH_JOBS permission.

This method will return the names of all batch jobs on the server for a given module.


To invoke:

GET http://localhost:9000/batch-job/{module_id}

The server will produce a response resembling the following:

{
   "jobs": [
      {
         "name": "bulkImportJob"
      }
   ]
}

27.2.2Fetch All Instances

 
This method requires the VIEW_BATCH_JOBS permission.

This method will return all instances (including running, complete, and failed) of a given batch job.


To invoke:

GET http://localhost:9000/batch-job/{module_id}/{job_name}

You may also add the following URL parameters:

  • executionUUID=[uuid] – (optional) If specified, only the execution with this UUID will be returned (if it exists).
  • start=[int] – The index of the first result to return
  • count=[int] – The number of results to return

For example, to view a list of all BulkImportJob instances on the persistence module, the following URL could be used: http://localhost:9000/batch-job/persistence/bulkImportJob?count=20&start=0

The server will produce a response resembling the following. Note that for each job instance, you will have at least one job execution. The id attribute can be used to stop and restart this job.

{
  "jobInstances" : [ {
    "jobName" : "bulkImportJob",
    "jobExecutions" : [ {
      "id" : 33,
      "moduleId" : "persistence",
      "jobName" : "bulkImportJob",
      "executionUUID" : "7cafdc19-0eeb-48d9-a0b8-edfcc0ea2cc4",
      "jobParameters" : {
        "commitInterval" : "5",
        "jobDescription" : "ETL Import Job: (unnamed)"
      },
      "createTime" : "2021-05-29T18:36:13.627-04:00",
      "startTime" : "2021-05-29T18:36:13.726-04:00",
      "lastUpdatedTime" : "2021-05-29T18:36:17.675-04:00",
      "endTime" : "2021-05-29T18:36:17.675-04:00",
      "status" : "COMPLETED",
      "exitStatus" : {
        "exitCode" : "COMPLETED",
        "running" : false
      },
      "running" : false,
      "recordWriteCount" : 200,
      "stepExecutions" : [ {
        "stepName" : "bulkImportProcessingStep",
        "exitCode" : "COMPLETED"
      }, {
        "stepName" : "bulkImportProcessingStep:FILE0:Rows 0 - 99",
        "exitCode" : "COMPLETED"
      }, {
        "stepName" : "bulkImportProcessingStep:FILE2:Rows 100 - 199",
        "exitCode" : "COMPLETED"
      }, {
        "stepName" : "bulkImportCloseJobStep",
        "exitCode" : "COMPLETED"
      } ]
    } ]
  } ]
}

27.2.3Stop Job Execution

 
This method requires the MANAGE_BATCH_JOBS permission.

This method stops a running job. It can also be used to recover a job that still reports being in a running state but no longer is (e.g. due to a server crash).


To invoke:

POST http://localhost:9000/batch-job/{module_id}/{job_execution_id}/stop?force={force}

Note the following path elements:

  • module_id – The FHIR Storage (RDBMS) module ID that the batch job is running on.
  • job_execution_id – The numeric ID of the job execution. Note that this is not the execution UUID, it is a numeric value.

You may also add the following URL parameters:

  • force=true – (optional) If specified, the job will be force-killed. Force killing a job marks it as stopped no matter what state it currently is in. This is useful for jobs that are in an inconsistent state because the server crashed during execution.

The server will produce a response resembling the following. Note that for each job instance, you will have at least one job execution. The id attribute can be used to stop and restart this job.

{
  "operation": "stop",
  "success": true,
  "message": "Batch Job 1 force-stopped."
}

27.2.4Restart Job Execution

 
This method requires the MANAGE_BATCH_JOBS permission.

This method restarts a stopped or failed job execution.


To invoke:

POST http://localhost:9000/batch-job/{module_id}/{job_execution_id}/restart

Note the following path elements:

  • module_id – The FHIR Storage (RDBMS) module ID that the batch job is running on.
  • job_execution_id – The numeric ID of the job execution. Note that this is not the execution UUID, it is a numeric value.

The server will produce a response resembling the following. Note that for each job instance, you will have at least one job execution. The id attribute can be used to stop and restart this job.

{
  "operation": "restart",
  "success": true,
  "message": "Restarted job execution with ID 1 - New execution ID is: 34"
}