Checking Job Status: How to Poll the Right Way

Part 9 of 12 in the Oracle EPM Cloud REST API series.

The previous post ended with a job ID and a status of negative one, meaning still in progress. This post covers what to do with that ID: how to check on a running job, read the response correctly, and know when it is safe to move on to the next step in a script.

The status check call

Take the ID from the job submission response and GET the same resource, now with that ID appended to the URL:

curl -X GET \
  "https://epm-xyz.epm.us-phoenix-1.ocs.oraclecloud.com/HyperionPlanning/rest/v3/applications/Vision/jobs/145" \
  -H "Authorization: Basic <base64 encoded credentials>"

A completed, successful job returns something like this:

{
    "status": 0,
    "details": "Metadata import was successful",
    "jobId": 145,
    "detailedStatus": 2,
    "jobName": "Operating Expense Adj Plan",
    "descriptiveStatus": "Completed",
    "links": [{
        "rel": "self",
        "href": "https://epm-xyz.epm.us-phoenix-1.ocs.oraclecloud.com/HyperionPlanning/rest/v3/applications/Vision/jobs/145",
        "action": "GET"
    }, {
        "rel": "job-details",
        "href": "https://epm-xyz.epm.us-phoenix-1.ocs.oraclecloud.com/HyperionPlanning/rest/v3/applications/Vision/jobs/145/details",
        "action": "GET"
    }]
}

A failed job returns the same shape, but with the useful information sitting in details, which is exactly where to look first when something breaks:

{
    "status": 1,
    "details": "An error occurred while updating the relational database.",
    "jobStatus": "Error",
    "detailedStatus": 3,
    "jobId": 145,
    "jobName": "Operating Expense Adj Plan"
}

Building a polling loop

A production script wraps this call in a loop: GET the job, check whether status is still negative one, and if so, wait a few seconds and check again, repeating until the status lands on success, error, or cancellation. A short pause between checks, a few seconds, is usually enough. Checking too aggressively adds load for no benefit, since most jobs take at least a handful of seconds to finish.

With the submit-then-poll pattern complete, the series applies it to a second job type next: loading data into Planning.