Job Operation
Use this API to perform any of the following job operations:
- Executing a job immediately
- Stopping a running job
Authentication
To grant access to users to view or execute
Control Compliance Suite
RESTful APIs, you must generate an authentication token.Authorization requirements
You must permissions to execute the following tasks to use the Job Operation API:
- Manage jobs
- Collect data
- View all jobs
- View assets
- View standards
- View evaluation results
- Evaluate standards
You must have the permission to access the following folders to use the Job Operation API:
- Asset System
- Standards
Request method
To use the Job Operation API, create a
POST
request.HTTPS request components for Job Operation API
To execute job operations, create a POST request by using the following components:
Request component | Value |
|---|---|
URL |
You can also use the Fully Qualified Domain Name (FQDN) as the hostname. You can configure the port number from the Integration Services Endpoint Configuration dialog box from Settings > Deployment View on the Control Compliance Suite console. You must restart the Symantec Application Server Service after you configure the port. If you do not configure the port, the default port is considered in the request. The default port is 12431. |
Content type | application/json |
JSON body |
|
HTTPS request parameters for Job Operation API
The following table contains the description of the HTTPS request parameters for the Job Operation API:
Field name | Field type | Data type | Description |
|---|---|---|---|
JobID (for executing a job immediately) | Mandatory | GUID | This is the unique identifier of the job that you want to execute. |
JobRunID (for stopping a running job) | Mandatory | GUID | This is the unique identifier of the job run that you want to cancel. |
Operation Type | Mandatory | String | The following values are supported for this field:
These values are not case-sensitive. |
Response body for Job Operation API
The POST request for the Job Operation API returns the response body in the following structure:
For Execute Job Operation
{ "JobStatusInfo": {"JobRunID":{GUID}, "JobID": {GUID}, "CustomStatusText": {String} "Exception": {String} "JobStartTime": {DateTime}, "JobEndTime": {DateTime}, "JobSummary": {String}, "Status": {Int}, "ActivityStatusList":[Array] } }
For Abort Job Operation
204 (No content)
Job status codes and their meanings
In response to the Execute Job Operation API, job information is returned along with job status code. The following table lists the respective meanings of each job status code:
Job status code | Meaning |
|---|---|
0 | None |
1 | Pending |
2 | Executing |
3 | Idle |
4 | Completed |
5 | Faulted |
6 | Custom |
7 | Aborted |
Sample HTTPS request for Job Operation API
The following are the sample HTTPS requests for your reference both for Execute Job Operation and Abort Job Operation:
For Execute Job Operation
Request component | Value |
|---|---|
URL |
|
Content type | application/json |
JSON body |
|
For Abort Job Operation
Request component | Value |
|---|---|
URL |
|
Content type | application/json |
JSON body |
|
Sample HTTPS response for Job Operation API
The sample HTTPS request that you created earlier returns the following response:
For Execute Job Operation
{"JobRunID":"4f7415b1-303d-42cd-8b61-485485a1cb9c", "JobID":"24f58e54-5d94-45f8-97a8-ccb6d959233a", "CustomStatusText":"","Exception":null, "JobStartTime":"2018-09-14T13:07:24.3474193Z", "JobEndTime":"0001-01-01T00:00:00", "JobSummary":null,"Status":2, "ActivityStatusList":[]}
For Abort Job Operation
204 (No Content)
HTTPS response codes for Job Operation API
Depending on the success or the failure of your API request, you see the following response codes for the Job Operation API:
Response Code | Response Type | Description |
|---|---|---|
200 | OK | The request is successfully completed. The following job execution details are returned:
|
204 | No content | The request is successfully completed. However, there is no content to return. |
401 | Unauthorized | This may be because of an invalid or expired access token in an API request. |
403 | Forbidden | The following error message is displayed: You are not authorized to perform this task. Access is denied. |
400 | Bad Request (Client Error) | One of the following error messages is displayed:
|
500 | Internal Server Error (Server Error) | The following error message is displayed:
|
Sample Python script for Job Operation API
Click to view a sample Python script for Job Operation API
# Script to perform the job operations. 'execute' and 'abort' operations are supported. Provide job GUID if you want to execute the job and provide job run ID if you want to abort the job. import requests from requests.packages.urllib3.exceptions import InsecureRequestWarning # Declare Variables # Replace the <hostname> with CCS application server host name # Replace the <port number> with the configured port number for REST API, Default Port Number : 12431 # Replace the <user name> and <password> with valid CCS user name and password for example: UserName = domain1\\administrator, password = <Base64 encoded> HostName = '<hostname>' PortNumber = '<port number>' UserName = '<user name>' Password = '<password>' #<Base64 encoded> # Function to generate CCS REST API access token def getToken(): urlToken = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/oauth/tokens" payload = "grant_type=password&username=" + UserName + "&password=" + Password +"" headers = {'Content-Type': "application/json"} responseToken = requests.request("POST", urlToken, data=payload, headers=headers, verify=False) autheticationresult = responseToken.status_code if (autheticationresult!=200) : print("\nToken Generation Failed. Please check if the REST API is enabled and User name and password is correct\n") exit() tokenDict = responseToken.json() token = tokenDict['access_token'] refreshToken = tokenDict['refresh_token'] return token # Job Operation API endpoint URL. Provide Job GUID if you need to run the job. url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/jobs/0b3b6ac7-acc9-42f1-9db9-bf89d7bd6e16" payload = "{\r\n\"Operation\":\"execute\"\r\n}\r\n" # Provide Jobrun ID if you need to cancel/abort the job. #url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/jobs/a348fb16-6d5b-4de3-bfd3-13f214a01538" #payload = "{\r\n\"Operation\":\"abort\"\r\n}\r\n" requests.packages.urllib3.disable_warnings(InsecureRequestWarning) bearertoken = "Bearer " + getToken() headers = { 'Authorization': bearertoken , 'Content-Type': "application/json" } response = requests.request("POST", url, data=payload, headers=headers, verify=False) print(response.text) print(response.json)