Job

Use this resource to start or stop a task based on ID or name. You can also retrieve job completion status.

Start POST Request

If your organization uses projects and folders, use the version 3 REST API lookup resource to retrieve the task ID. This ID is the federated task ID, which you must include in the POST request.
Alternatively, you can use the task resource to retrieve the task ID. However, the task resource returns a task ID that you can only use to run tasks located in the Default folder.
Do not use this resource for a Data Integration mass ingestion task. Instead, use the mass ingestion job resource. For more information, see the Data Integration API.
To start a task, use the following URI:

/api/v2/job

With this URI, use the following attributes in a job object:

Field

Type

Required

Description

taskId

String

Required if taskName or taskFederatedId is 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.

Task ID that includes the folder path to the task

taskName

String

Required if taskId or taskFederatedId is not included.

Task or linear taskflow name. Use taskId or taskName in the URI.

type

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

A valid, publicly available URL. The service posts the job status to the callbackURL

Start POST Response

Returns the job object if the request is successful. Returns an error object if errors occur.
The job object includes the following attributes

Field

Type

Description

taskId

String

Task or linear taskflow ID.

taskName

String

Task or linear taskflow name.

type

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

String

ID of the job.

callbackURL

String

Status of the job.

Start POST Request Example

To start a linear taskflow with an ID of 0034J90000000M in JSON, 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",
}

Stop POST Request

To stop a task or linear taskflow, use the following URI:

/api/v2/job/stop

With this URI, use the following attributes 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.

taskName

String

Required if taskId not included.

Task or linear taskflow name. Use taskId or taskName in the URI.

type

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.

Stop POST Response

Returns the success object if the request is successful. Returns the error object if errors occur

Stop POST Example

To stop a linear taskflow with an ID of 0034J90000000M in JSON, 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"
}

Job Status Example

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 because of a system failure or incorrect server response. When the service sends a request to the callback URL, the endpoint on your server must return a 200 HTTP code within 30 seconds. Otherwise, the URL connection breaks and the service counts the break as a failed attempt. The server will make a total of three attempts.
The service executes the POST request from the callback URL. The following text is a sample return:

{
    @type:"callbackUrlResponse"
    endTime: "2013-02-27T18:57:52.000Z",
    objectId: "0034J90000000M",
    objectName: "taskName",
    runId: 5,
    status: "COMPLETED" // or “FAILED”
}