Jobs resource (Data API 23.2)

Summary

Http Method Resource Description
POST /jobs/{job_id}/executions Executes the job with the given job ID by creating and returning a job execution for it. The job might still be executed when the job execution is returned. Note that this resource is also intended for running system jobs.

See Global Jobs for information on available system jobs.

GET /jobs/{job_id}/executions/{id} Returns job execution information using the specified ID for the job having the specified job ID.
DELETE /jobs/{job_id}/executions/{id} Deletes job execution information using the specified ID for the job having the specified job ID.

Create job execution

Executes the job with the given job ID by creating and returning a job execution for it. The job might still be executed when the job execution is returned. Note that this resource is also intended for running system jobs.

See Global Jobs for information on available system jobs.

Url

POST https://hostname:port/dw/data/v23_2/jobs/{job_id}/executions

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

JobExecutionRequest

Response Document

JobExecution

Path Parameters

Parameter Type Description Constraints
job_id String The ID of the job to execute. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 JobAlreadyRunningException

jobId (String)

if the job is already running.
400 JobInvalidException

jobId (String)

cause (Throwable)

if the job is invalid and is therefore not executable.
400 JobRestartException

jobId (String)

if the job could not be restarted.
400 JobNotRestartableException

jobId (String)

if the job does not support restarting.
400 JobExecutionException

jobId (String)

if the job could not be executed.
404 JobNotFoundException

jobId (String)

if the job with the given job ID doesn't exist.

Sample

REQUEST:
POST /dw/data/v23_2/jobs/CustomerImportJob/executions
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control:no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_type" : "job_execution",
   "_resource_state" : "485715bae6023b28b849273a517f1f538d3c6290c70018e9afcaac767b9f513f",
   "client_id" : "af7f5c90-ffc1-4ea4-9613-f5b375b7dc19",
   "duration" : 0,
   "execution_status" : "running",
   "id" : "40605",
   "is_log_file_existing" : false,
   "is_restart" : false,
   "job_id" : "CustomerImportJob",
   "log_file_name" : "Job-JobExecutionTestJob1-20160520120033101.log",
   "modification_time" : "2016-05-20T12:00:33.117Z",
   "start_time" : "2016-05-20T12:00:33.117Z",
   "status" : "RUNNING"
}

# in case the job to be executed doesn't exist

RESPONSE:
HTTP/1.1 404 NOT FOUND
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "jobId" : "CustomerImportJob"
      },
      "type" : "JobNotFoundException",
      "message" : "No job with ID 'CustomerImportJob' was found."
   }
}

# in case when job could not be executed (e.g. because it is invalid, step types not found, etc.) 

RESPONSE:
HTTP/1.1 409 CONFLICT
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "jobId" : "CustomerImportJob"
      },
      "type" : "JobExecutionException",
      "message" : "The job with ID 'CustomerImportJob' could not be executed."
   }
}

Read job execution

Returns job execution information using the specified ID for the job having the specified job ID.

Url

GET https://hostname:port/dw/data/v23_2/jobs/{job_id}/executions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

JobExecution

Path Parameters

Parameter Type Description Constraints
id String the ID of the job execution  
job_id String the ID of the job. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 JobExecutionNotFoundException

executionId (String)

for an unknown job ID or job execution ID

Sample

REQUEST:
GET /dw/data/v23_2/jobs/CustomerImportJob/executions/90
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control:no-cache,no-store,must-revalidate
Expires: Thu, 01-Jan-1970 00:00:00 GMT
{
   "_v" : "23.2",
   "_type" : "job_execution",
   "_resource_state" : "ac83c2e1ff3129ed6579c5fa95f746047d7db6867dd26da78dc89d23083127a3",
   "client_id" : "af7f5c90-ffc1-4ea4-9613-f5b375b7dc19",
   "duration" : 185,
   "end_time" : "2016-05-20T11:54:46.220Z",
   "execution_scopes" :
   [
      "SiteGenesis",
      "SiteGenesis-US",
      "SiteGenesis-DE"
   ],
   "execution_status" : "finished",
   "exit_status" :
   {
      "_type" : "status",
      "code" : "OK",
      "status" : "ok"
   },
   "id" : "90",
   "is_log_file_existing" : true,
   "is_restart" : false,
   "job_id" : "CustomerImportJob",
   "log_file_name" : "Job-JobExecutionTestJob1-20160520115446018.log",
   "modification_time" : "2016-05-20T11:54:46.224Z",
   "start_time" : "2016-05-20T11:54:46.035Z",
   "status" : "OK",
   "step_executions" :
   [
      {
         "_type" : "job_step_execution",
         "duration" : 16,
         "end_time" : "2016-05-20T11:54:46.075Z",
         "execution_scope" : "Organization",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "OK",
            "message" : "",
            "status" : "ok"
         },
         "id" : "41265",
         "modification_time" : "2016-05-20T11:54:46.075Z",
         "start_time" : "2016-05-20T11:54:46.059Z",
         "status" : "OK",
         "step_description" : "A step that executes a pipeline that can be configured via a parameter",
         "step_id" : "Step1",
         "step_type_id" : "ExecutePipeline",
         "step_type_info" : "TestScheduleJobProcessPipeline-StartEnd"
      },

      {
         "_type" : "job_step_execution",
         "duration" : 12,
         "end_time" : "2016-05-20T11:54:46.102Z",
         "execution_scope" : "Organization",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "OK",
            "message" : "",
            "status" : "ok"
         },
         "id" : "41266",
         "modification_time" : "2016-05-20T11:54:46.103Z",
         "start_time" : "2016-05-20T11:54:46.090Z",
         "status" : "OK",
         "step_description" : "A step that executes a script module function that can be configured via a parameter",
         "step_id" : "Step2",
         "step_type_id" : "ExecuteScriptModule",
         "step_type_info" : "testScriptModuleStep.ds#execute"
      },

      {
         "_type" : "job_step_execution",
         "duration" : 16,
         "end_time" : "2016-05-20T11:54:46.132Z",
         "execution_scope" : "SiteGenesis-DE",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "OK",
            "message" : "",
            "status" : "ok"
         },
         "id" : "41267",
         "include_steps_from_job_id" : "JobExecutionTestJob2",
         "modification_time" : "2016-05-20T11:54:46.132Z",
         "start_time" : "2016-05-20T11:54:46.116Z",
         "status" : "OK",
         "step_description" : "A step that executes a pipeline that can be configured via a parameter",
         "step_id" : "Step3 - Step1",
         "step_type_id" : "ExecutePipeline",
         "step_type_info" : "TestScheduleJobProcessPipeline-StartEnd"
      },

      {
         "_type" : "job_step_execution",
         "duration" : 14,
         "end_time" : "2016-05-20T11:54:46.159Z",
         "execution_scope" : "SiteGenesis-DE",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "SUCCESS",
            "message" : "Step was successful!",
            "status" : "ok"
         },
         "id" : "41268",
         "include_steps_from_job_id" : "JobExecutionTestJob2",
         "modification_time" : "2016-05-20T11:54:46.159Z",
         "start_time" : "2016-05-20T11:54:46.145Z",
         "status" : "SUCCESS",
         "step_description" : "",
         "step_id" : "Step3 - Step2",
         "step_type_id" : "ExecuteScriptModule",
         "step_type_info" : "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
      },

      {
         "_type" : "job_step_execution",
         "duration" : 15,
         "end_time" : "2016-05-20T11:54:46.189Z",
         "execution_scope" : "SiteGenesis",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "OK",
            "message" : "",
            "status" : "ok"
         },
         "id" : "41269",
         "include_steps_from_job_id" : "JobExecutionTestJob2",
         "modification_time" : "2016-05-20T11:54:46.189Z",
         "start_time" : "2016-05-20T11:54:46.174Z",
         "status" : "OK",
         "step_description" : "A step that executes a pipeline that can be configured via a parameter",
         "step_id" : "Step3 - Step1",
         "step_type_id" : "ExecutePipeline",
         "step_type_info" : "TestScheduleJobProcessPipeline-StartEnd"
      },

      {
         "_type" : "job_step_execution",
         "duration" : 13,
         "end_time" : "2016-05-20T11:54:46.216Z",
         "execution_scope" : "SiteGenesis",
         "execution_status" : "finished",
         "exit_status" :
         {
            "_type" : "status",
            "code" : "SUCCESS",
            "message" : "Step was successful!",
            "status" : "ok"
         },
         "id" : "41270",
         "include_steps_from_job_id" : "JobExecutionTestJob2",
         "modification_time" : "2016-05-20T11:54:46.216Z",
         "start_time" : "2016-05-20T11:54:46.203Z",
         "status" : "SUCCESS",
         "step_description" : "",
         "step_id" : "Step3 - Step2",
         "step_type_id" : "ExecuteScriptModule",
         "step_type_info" : "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
      }
   ]
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" :
   {
      "arguments" :
      {
         "executionId" : "90"
      },
      "type" : "JobExecutionNotFoundException",
      "message" : "No Job execution with ID '90' was found."
   }
}

Delete job execution

Deletes job execution information using the specified ID for the job having the specified job ID.

Url

DELETE https://hostname:port/dw/data/v23_2/jobs/{job_id}/executions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
id String the ID of the job execution  
job_id String the ID of the job. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
403 JobExecutionNotFinishedException

executionId (String)

if the job execution is not finished.
404 JobExecutionNotFoundException

executionId (String)

for an unknown job ID or job execution ID

Sample

REQUEST:
DELETE /dw/data/v23_2/jobs/CustomerImportJob/executions/85 HTTP/1.1
Host: example.com
Authorization:Bearer d5c7be15-9f0e-4b70-b6b9-0fbfc558bd6a
Content-Type:application/json;charset=UTF-8


# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# in case of failure:

RESPONSE:
HTTP/1.1 404 Requested resource not found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
{
   "_v" : "23.2",
   "fault" : 
   {
      "arguments" : 
      {
         "executionId" : "85"
      },
      "type" : "JobExecutionNotFoundException",
      "message" : "No Job execution with ID '85' was found."
   }
}
X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.