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. |
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: |
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: |
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: |
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”
}