REST API Reference > Platform REST API version 2 resources > Jobs
  

Jobs

Use the job resource to start or stop a task based on ID or name, including linear taskflows. You can also get the job completion status.
To start or stop a task based on an ID, you can use the eight-character object ID for the task or the federated task ID.
To find the eight-character object ID, see Tasks. However, this resource returns a task ID that you can use only to run tasks located in the Default folder.
If your organization uses projects and folders, see Lookup or Objects to retrieve the federated task ID.
For a Data Ingestion and Replication file ingestion and replication task, use the file ingestion and replication job resource. For more information, see File Ingestion and Replication REST API.

Job Status

When you include the callbackURL in the job request, the service sends a request to the callback URL when the job completes. The service always uses a JSON request for callbacks.
A callback might be called multiple times. For example, multiple callbacks might occur in the following situations:
In any of these situations, the URL connection breaks and the service counts the break as a failed attempt. The service will make three immediate attempts to receive a successful response. Afterward, the attempts will occur in exponential increments. For example, the attempts might begin with a 30-second interval and progress up to a maximum 3-minute interval, until the total time reaches 30 minutes.
The service runs the POST request from the callback URL. The following text is a sample response:
{
@type:"callbackUrlResponse"
endTime: "2013-02-27T18:57:52.000Z",
objectId: "0034J90000000M",
objectName: "taskName",
runId: 5,
status: "COMPLETED" // or “FAILED”
}

Starting a job

Use the job resource to start a job.

POST request

Use the following URI:
/api/v2/job
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName or taskFederatedId isn't included.
Task or linear taskflow ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task isn't located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId or taskFederatedId isn't included.
Task or linear taskflow name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DMASK. Masking task.
  • - DRS. Replication task.
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
  • - WORKFLOW. Linear taskflow.
callbackURL
String
No
A valid, publicly available URL. The service posts the job status to the callbackURL.
runtime
No
Attribute that defines runtime properties.
parameterFileName
String
No
Parameter file name.
parameterFileDir
String
No
Parameter file directory on the Secure Agent machine.

POST response

The response returns the job object if the request is successful and an error object if an error occurs.
The following table describes the attributes in the job object:
Field
Type
Description
taskId
String
Task or linear taskflow ID.
taskFederatedId
String
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Task or linear taskflow name.
taskType
String
The type of task. Returns one of the following codes for Data Integration:
  • - DMASK. Masking task.
  • - DRS. Replication task.
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
  • - WORKFLOW. Linear taskflow.
runId
Long
ID of the job.
callbackURL
String
Status of the job.

POST request examples

To start a linear taskflow with ID 0034J90000000M, you might use the following request:
POST <serverUrl>/api/v2/job HTTP/1.0
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>

{
"taskId": "0034J90000000M",
"taskType": "Workflow",
"callbackURL": "https://MyIICSJobStatus.com",
}
To start a mapping task with ID 0100000Z000009, you might use the following request:
POST <serverUrl>/api/v2/job HTTP/1.0
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>

{
"@type": "job",
"taskId": "0100000Z000009",
"taskType": "MTT",
"runtime": {
"@type": "mtTaskRuntime"
}
}
Because the request includes a runtime object, you can make additional requests to run the task simultaneously in other runtime environments.
To start a mapping task using a parameter file, you might use the following request:
POST <serverUrl>/api/v2/job HTTP/1.0
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>

{
"@type": "job",
"taskId": "0116Q70Z0000000000N4",
"taskType": "MTT",
"runtime": {
"@type": "mtTaskRuntime",
"parameterFileName": "EmployeeDept.param",
"parameterFileDir": "/root/dev/FlatFiles"
}
}
You might get the following response:
{
"@type": "job",
"taskId": "0116Q70Z0000000000N4",
"taskType": "MTT",
"runId": 59,
"taskName": "mct_03126935_Oracle_FF_Parameter",
"runInParallel": false
}

Stopping a job

Use the job resource to stop a job.

POST request

Use the following URI:
/api/v2/job/stop
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName isn't included.
Task or linear taskflow ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task isn't located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId isn't included.
Task or linear taskflow name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DMASK. Masking task.
  • - DRS. Replication task.
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
  • - WORKFLOW. Linear taskflow.

POST response

The response returns the success object if the request is successful and an error object if an error occurs.

POST request example

To stop a linear taskflow with ID 0034J90000000M, you might use the following request:
POST <serverUrl>/api/v2/job/stop HTTP/1.0
Content-Type: application/json
Accept: application/json
icSessionId: <icSessionId>

{
"@type": "job",
"taskId": "0034J90000000M",
"taskType": "Workflow"
}

Cleanly stopping a job

Use the job resource to cleanly stop a job.

POST request

Use the following URI:
/api/v2/job/stop?cleanStop=true
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName not included.
Task or linear taskflow ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task is not located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId not included.
Task or linear taskflow name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DMASK. Masking task.
  • - DRS. Replication task.
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
  • - WORKFLOW. Linear taskflow.

POST response

The response returns the success object if the request is successful and an error object if an error occurs.

POST request example

To cleanly stop a mapping task named MappingTask1, you might use the following request:
POST <serverUrl>/api/v2/job/stop?cleanStop=1

{
"@type": "job",
"taskName": "MappingTask1",
"taskType": "MTT"
}