Jobs Resource (Data API 17.2)

Summary

Http Method	Resource	Description
GET	/Jobs/{Job_id}/Executions	Reads job executions for the job with the specified job ID.
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.
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.

Read Job Executions

Reads job executions for the job with the specified job ID.

Url

GET https://hostname:port/dw/data/v17_2/jobs/{job_id}/executions?start={Integer}&count={Integer}

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

Response Document

JobExecutionResult

Path Parameters

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

Query Parameters

Parameter	Type	Description	Constraints
count	Integer		maxIntegerValue=200, minIntegerValue=1
start	Integer		minIntegerValue=0

Sample

REQUEST:
GET /dw/data/v17_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" : "17.2",
   "_type" : "job_execution_result",
   "count" : 1,
   "data" :
   [

      {
         "_v" : "17.2",
         "_type" : "job_execution",
         "client_id" : "af7f5c90-ffc1-4ea4-9613-f5b375b7dc19",
         "duration" : 2247,
         "end_time" : "2016-03-03T09:46:06.357Z",
         "execution_scopes" :
         [
            "SiteGenesis"
         ],
         "exit_status" :
         {
            "_type" : "status",
            "code" : "OK",
            "status" : "ok"
         },
         "id" : "85",
         "is_restart" : false,
         "job_id" : "CustomerImportJob",
         "log_file_name" : "Job-CustomerImportJob-20160303094604093.log",
         "is_log_file_existing" : true,
         "modification_time" : "2016-03-03T09:46:06.360Z",
         "start_time" : "2016-03-03T09:46:04.110Z",
         "status" : "finished",
         "step_executions" :
         [
            {
               "_type" : "job_step_execution",
               "duration" : 21,
               "end_time" : "2016-03-03T09:46:04.164Z",
               "execution_scope" : "SiteGenesis",
               "exit_status" :
               {
                  "_type" : "status",
                  "code" : "OK",
                  "message" : "",
                  "status" : "ok"
               },
               "id" : "364",
               "modification_time" : "2016-03-03T09:46:04.164Z",
               "start_time" : "2016-03-03T09:46:04.143Z",
               "status" : "finished",
               "step_description" : "Imports customers",
               "step_id" : "ImportCustomers",
               "step_type_id" : "ExecutePipeline",
               "step_type_info" : "CustomerImport-Start"
            }
         ]
      }
   ],
   "total" : 1
}

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.

Url

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

Formats

json, xml

Authentication

Name	Description
OAuth	Authentication via OAuth token.

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/v17_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" : "17.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" : "17.2",
   "fault" : 
   {
      "arguments" : 
      {
         "jobId" : "CustomerImportJob"
      },
      "type" : "JobNotFoundException",
      "message" : "No job with ID 'CustomerImportJob' 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" : "17.2",
   "fault" : 
   {
      "arguments" : 
      {
         "jobId" : "CustomerImportJob"
      },
      "type" : "JobExecutionException",
      "message" : "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/v17_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/v17_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" : "17.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" : "17.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/v17_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/v17_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" : "17.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.