Get Latest Job Runs

Use this API to retrieve the list of latest runs for a specified job in
Control Compliance Suite
.
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 have the permissions to execute the following tasks to use the Get Latest Job Runs API:
  • View all jobs
  • View standards
  • View assets
You must have permission to access the following folders to use the Get Latest Job Runs API:
  • Asset System
  • Standards
  Request method
To retrieve the list of latest runs for a specified job, create a
GET
request.
  HTTPS request components for Get Latest Job Runs API
Create a GET request by using the following components:
HTTPS request components for Get Latest Job Runs API
Request component
Value
URL
https://<hostname>:<port number>/ccs/api/v1/Jobs/<JobID>/jobruns?count=<number>&showmessages=true
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
  HTTPS request parameters for Get Latest Job Runs API
The following table contains the description of the HTTPS request parameters for the Get Latest Job Runs API:
HTTPS request parameters for Get Latest Job Runs API
Field name
Field type
Data type
Description
JobID
Mandatory
GUID
This is the unique identifier of the job of which you want to retrieve the list of latest runs.
Count
Optional
Integer
This is the count of the latest job runs that you want to retrieve. If you specify 0 in the
Count
field, the API returns all the job runs for the specified ID. The default value of this parameter is 1.
showmessages
Optional
Boolean
If you want to view the error messages along with their count for each job run, date and time, error message details, error message category, the asset and type of asset in which the error is reported, and asset owner, use this parameter with its value 'True' in input request. The default value of this parameter is 'False'.
  Response body for Get Latest Job Runs API
The GET request for the Get Latest Job Runs API returns the response body in the following structure:
Success Response: { "TotalJobRuns": {Int}, "JobID":{String}, "JobStatusInfo":[ { "ActivityStatusList" : {Array}, "CustomStatusText": {String}, "JobEndTime": {DateTime} "JobStartTime": {DateTime}, "JobSummary": {String}, "Status": {Int}, "StatusDetails": {String}, "Exception": {String}, "JobRunID": {GUID}, "MessageCount": {Int}, "JobMessages": [ { "DateTime": {DateTime} "Message": "String", "MessageDetails": " String", "Category": "String", "Asset": "String", "AssetType": "String", "AssetOwner": "String" } ] } }
Job status codes and their meanings
In response to the Get Latest Job Runs API, job information is returned along with last job run status code. The following table lists the respective meanings of each job status code:
Job status codes and their meanings
Job status code
Meaning
0
None
1
Pending
2
Executing
3
Idle
4
Completed
5
Faulted
6
Custom
7
Aborted
Sample HTTPS request for Get Latest Job Runs API
The following is a sample HTTPS request for your reference:
HTTPS request components for Get Latest Job Runs API
Request component
Value
URL
https://<hostname>:<port number>/ccs/api/v1/jobs/ff761384-4b49-40b4-97d8-0de38669075a/jobruns?count=2&showmessages=true
Content type
application/json
  Sample HTTPS response for Get Latest Job Runs API
The sample HTTPS request that you created earlier returns the following response:
{ "TotalJobRuns":1, "JobID":"ff761384-4b49-40b4-97d8-0de38669075a", "JobStatusInfo":[{"Exception":null, "ActivityStatusList":null, "CustomStatusText":null, "JobEndTime":"2018-09-20T05:44:42", "JobStartTime":"2018-09-20T11:14:34+05:30", "JobSummary":null, "Status":5, "JobRunID":"413e6d92-6de0-4a89-8752-149270dd4369" "MessageCount": 1, "JobMessages": [ { "DateTime": "2021-10-19T17:31:14+05:30 "Message": "Windows Data Collector: query returned with message(s)." "MessageDetails":"The credentials for asset have not been configured. Please configure credentials using platform configuration." "Category": "Error" "Asset":"<Domain name>\<IP Address>" "AssetType": "Windows Machine" "AssetOwner": "<UserName>" } ] }, ] }
HTTPS response codes for Get Latest Job Runs API
Depending on the success or the failure of your API request, you see the following response codes for the Get Latest Job Runs API:
HTTPS response codes for Get Latest Job Runs API
Response Code
Response Type
Description
200
OK
The request is successfully completed. The list of job runs with the following details is available:
  • Total count of job runs
  • Unique identifier of a job
  • Information about the job status
  • Exceptions received during job execution
  • List of activity statuses
  • Custom status text
  • Start time of job execution
  • End time of job execution
  • Job summary
  • Job status
  • Details about job status
  • Unique identifier of the job run
  • Count of error messages for a job
  • Message text
    For example:
    "JobMessages": [
    {
    "DateTime": "2021-10-19T17:31:14+05:30",
    "Message": "Windows Data Collector: query returned with message(s).",
    "MessageDetails": " The credentials for the asset have not been configured. Please configure credentials using platform configuration.",
    "Category": "Error",
    "Asset": "DomainName\IP Address",
    "AssetType": "Windows Machine",
    "AssetOwner": "username"
    }
403
Forbidden
The following error message is displayed:
You are not authorized to perform this task. Access is denied.
404
NOT FOUND
The following error message is displayed:
Job for specified JobID '#JobID' not found.
401
Unauthorized
This may be because of an invalid or expired access token in an API request.
400
Bad Request
(Client Error)
The following error message is displayed:
JobID is invalid.
500
Internal Server Error
(Server Error)
The following error message is displayed:
The server encountered an error while serving the request. Please contact the administrator if the problem persists.
Sample Python script for Get Latest Job Runs API
Click to view a sample Python script for Get Latest Job Runs API
#Script to retrieve the list of latest runs for a specified job by providing job GUID in the request. 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 #Get Latest Job Runs API endpoint URL. Provide a job GUID to retrieve the job run details as per the job run count mentioned. url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/Jobs/a282d163-2248-4904-8135-0eaf08be8e55/jobruns" requests.packages.urllib3.disable_warnings(InsecureRequestWarning) #Provide a count of the latest job runs that you want to retrieve. The default value of this parameter is 1. querystring = {"count":"1"} #Provide a count of the latest job runs that you want to retrieve. If you specify 0 in the Count field, the API returns all the job runs for the specified job GUID. #querystring = {"count":"0"} bearertoken = "Bearer " + getToken() headers = { 'Authorization': bearertoken } response = requests.request("GET", url, headers=headers, params=querystring, verify=False) print(response.text) print(response.json)