Jobs APIs

During the Export and Prepare phases of the Image Portability workflow, a job is created to perform the steps necessary for the requested operation. The POST response includes an id field, which contains a GUID value that is used in other API calls to refer this specific job. To assist the user in managing their jobs, the Image Portability Service provides a set of APIs that the user can interact with. These calls consist of:`

• Getting all jobs for the customer account
• Getting the details for a specific customer job
• Cancel an in progress job

The following sections provide a high level overview of each Jobs API. For a detailed description about each Jobs API, including required request headers, as well as a detailed explanation of the fields in the response, see Job Management.

GET all jobs

When you make a REST API call to the “jobs” endpoint, the service responds with a paged response that contains all your recent jobs. The completed Jobs are only kept in a database for 24 hours, so a request to this endpoint returns Jobs initiated only during that timeframe. All jobs, regardless of their status (in-progress or complete) are included in this response.

To GET all jobs, make a REST GET call to the following endpoint:

https://api-us.cloud.com/ips/jobs/
<!--NeedCopy-->

The JSON response includes an array of Jobs, where each array element represents a unique Job, identified by its ID. In the event that there are more jobs in the database than can be displayed on a single page, a ContinuationToken can be used to request the next page of results.

{
   "pageSize" : 3,
   "items" : [
      {
         "id" : "226f38a2-51dc-450c-8217-f17ac26a839c",
         ...
      },
      {
         "id" : "a126a50b-2150-4374-ae24-8e33f744d593",
         ...
      },
      {
         "id" : "08c64a40-734b-4eb5-aa0f-a30fc9400e6d",
         ...
      }
   ],
   "continuationToken" : "PT17Q2l0cml4fT09K1JJRDp+c2c1a0FQZmtOWEF1TndFQUFBQUFBQT09I1JUOjEjVFJDOjEjUlREOk05VjFtejVWb2xmTVJCd1dvdzdGQk1IWk0zdmgyQT09I0lTVjoyI0lFTzo2NTU1MSNRQ0Y6NCNGUEM6QVNnM0FRQUFBQUFBTGpjQkFBQUFBQUE9",
   "pollingToken" : null
}
<!--NeedCopy-->

Note: In the preceding output example, only the “id” field is shown. A real response might include 20 or more additional fields, depending on the job type.

If the continuationToken field is empty, this response includes all the jobs for your customer account. When this field is not empty, as shown in the preceding example, there are more jobs that might not be displayed on this page. The continuation token can be passed as a query parameter in the next request to GET the next page of jobs, as shown in the following request:`

GET https://api-us.cloud.com/ips/jobs?continuationToken=PT17Q2l0cml4fT09K1JJRDp%2Bc2c1a0FQZmtOWEF1TndFQUFBQUFBQT09I1JUOjEjVFJDOjEjUlREOk05VjFtejVWb2xmTVJCd1dvdzdGQk1IWk0zdmgyQT09I0lTVjoyI0lFTzo2NTU1MSNRQ0Y6NCNGUEM6QVNnM0FRQUFBQUFBTGpjQkFBQUFBQUE9
<!--NeedCopy-->

GET a job

When you want to verify the status of a specific job, make a REST API call to the Jobs endpoint and specify the ID of the job. The IPS returns a JSON response that contains the details of the job, as shown in the following example. Note: The following example is taken from performing a Prepare job for Google Cloud.

To GET a job, make a REST GET call to the following endpoint, replacing “GUID” with the GUID value returned when from the POST response to the job request.

https://api-us.cloud.com/ips/jobs/"GUID"
<!--NeedCopy-->

The response to the GET request is a JSON object that contains the information relative to that specific job. All IPS jobs transit through the same statuses during the lifecycle of a job. A job begins with a status of “notStarted”, before transitioning into “inProgress” as the job gets underway. While a job is in progress, the “overallProgressPercent” field indicates the progress of the job with transition 0–100. IPS jobs are long running jobs and might be at a specific percentage of completion for an extended period. For example, the Export job writes a file across the network to an SMB file share. The speed of the network between the exporting host and the file share, as well as the speed of the SMB share will determine how long the export job takes to complete. After the job completes successfully, the status changes to “complete” status. An example of a job that has completed successfully is provided here:

{
   "id" : "1dc899e8-e466-42d8-a7ba-19bad50f3374",
   "type" : "https://identifiers-api.cloud.com/applayering/prepareImage",
   "overallProgressPercent" : 100,
   "isCancellable" : true,
   "parameters" : [],
   "status" : "complete",
   "resultLocation" : null,
   "additionalInfo" : {
      "artifacts" : {
         "label" : {
            "ctx-job-id" : "1dc899e8-e466-42d8-a7ba-19bad50f3374"
         },
         "bucket" : "test-3e821d13",
         "ceImage" : "test-3e821d13",
         "outputDisk" : "test-integration-base-test-disk-9334c97b",
         "vm" : {
            "name" : "test-3e821d13",
            "ceDisk" : "test-3e821d13"
         }
      }
   },
   "warnings" : [],
   "error" : [],
   "createdAt" : "2021-11-17T14:41:31Z",
   "updatedAt" : "2021-11-17T15:10:01Z",
   "startedAt" : "2021-11-17T14:41:31Z",
   "endedAt" : "2021-11-17T15:10:01Z"
}
<!--NeedCopy-->

When an error occurs and a job fails, the job status is set to “failed”. In the event of a job failure, the reason for failure is provided in the error field as shown in the following example job. In the following example, only the fields that change between the success/failure are shown for the sake of brevity.

"status" : "failed",
"error" : [
    {
      "type" : "ce-request-failed",
      "detail" : "Job failed at step WaitForExportImage with the error: Failed to mount the file share path. Please check the file share for permission and connectivity issues, and that you have entered the correct credentials.",
      "parameters" : []
   }
]
<!--NeedCopy-->

Cancel a running job

You can cancel a job when it does not progress or there’s no chance of success. For example, you submit a job and realize that you provided a wrong value in your request. IPS allows you to cancel a job that is in the “inProgress” state. To cancel a job, make a REST POST call to the following endpoint. Replace the “GUID” value with the GUID value that is returned in the response to the POST request when the job was started.

https://api-us.cloud.com/ips/jobs/"GUID"/$cancel?async=true
<!--NeedCopy-->

After you submit the cancel request, the job status transits from “inProgress” to “cancelling”, and then ultimately reach the status of “cancelled”. The following is an example of a job that has been cancelled successfully:

{
   "id" : "9b6f472e-e2cc-4ab1-894e-faeffdaf6dde",
   "type" : "https://identifiers-api.cloud.com/applayering/prepareImage",
   "overallProgressPercent" : 100,
   "isCancellable" : true,
   "parameters" : [],
   "status" : "cancelled",
   "resultLocation" : null,
   "additionalInfo" : {},
   "warnings" : [],
   "error" : [
      {
         "type" : "cancelled",
         "detail" : "Job failed at step PrepareForCreateCeVm with the error: The job has been cancelled.",
         "parameters" : []
      }
   ],
   "createdAt" : "2021-11-19T19:29:27Z",
   "updatedAt" : "2021-11-19T19:30:04Z",
   "startedAt" : "2021-11-19T19:29:27Z",
   "endedAt" : "2021-11-19T19:30:04Z"
}
<!--NeedCopy-->