Search Job by Name

Use this API to search a job in
Control Compliance Suite
by providing the exact job name in the request. Successful completion of the request returns job properties and configuration details of the following types of jobs:
  •   Collection-Evaluation-Reporting (CER) Job
  •   Data Collection Job
  • Evaluation Job
For any other type of job, successful completion of the request returns job properties only.
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 following tasks to use the Search Job by Name API:
  • View all jobs
  • View standards
  • View assets
You must have permission to access the following folders to use the Search Job by Name API:
  • Asset System
  • Standards
  Request method
To search a job by using JobID, create a
GET
request.
  HTTPS request components for Search Job by Name API
Create a GET request by using the following components:
HTTPS request components Search Job by Name API
Request component
Value
URL
https://<hostname>:<port number>/ccs/api/v1/jobs?/jobname=<JobName>
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 parameter for Search Job by Name API
The following table contains the description of the HTTPS request parameter for the Search Job by Name API:
HTTPS request parameter for Search Job by Name API
Field name
Field type
Data type
Description
JobName
Mandatory
String
This is the exact name of the
Control Compliance Suite
job that you want to search.
The value of this parameter is not case-sensitive.
Note
: If a CCS 12.5.2 user sends
JobName=
in the request, the Search Job by Name API returns an error. If a CCS 12.6 user sends the same request, the Search Job by Name API returns all the jobs in a system.
  Response body for Search Job by Name API
The GET request for the Search Job by Name API returns the response body in the following structure:
Success Response: { "JobProperties": { "IsSystemJob": {Boolean}, "JobCreationTime": {DateTime}, "JobID": {GUID}, "JobModifiedTime": {DateTime} , "JobType": {String}, "LastRunDate": {DateTime}, "LastRunStatus": {Int}, "Name": {String}, "Owner": {String} } "JobConfigDetails": { "EvaluationResultViewers": [Array], "Schedule": {...}, "JobDescription": {String}, "SuccessNotification": {...}, "FailureNotification": {...}, "ShouldSendSuccessNotification": {Boolean}, "ShouldSendFailureNotification": {Boolean}, "JobName": {String}, "AssetsResolutionInfo": [Array], "Standards": [Array] } }
Job status codes and their meanings
In response to the Search Job by Name 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 Search Job by Name API
The following is a sample HTTPS request for your reference:
GET https://<hostname>:<port number>/ccs/api/v1/jobs?jobname=CreateJob_FreshCollectionEvaluation
  Sample HTTPS response for Search Job by Name API
The sample HTTPS request that you created earlier returns the following response:
{ "JobProperties": { "IsSystemJob": false, "JobCreationTime": "2018-09-17T11:44:53", "JobID": "23c59087-f3d4-4e05-a39e-3440c58e58fb", "JobModifiedTime": "2018-09-17T11:44:53", "JobType": "CHAINED_EVALUATIONJOB", "LastRunDate": "0001-01-01T00:00:00", "LastRunStatus": 0, "Name": "CreateJob_FreshCollectionEvaluation", "Owner": <name> }, "JobConfigDetails": { "EvaluationResultViewers": [], "Schedule": { "SubScheduleRepeatDays": 0, "SubScheduleRepeatPeriodDays": 0, "EndJobRunTimeInterval": "00:00:00", "EndJobRunConfigured": false, "RepeatDays": 50, "RunEveryNDays": true, "RunOnce": false, "RunNow": false, "RunPeriodically": true, "StartDate": "2018-11-18T21:14:27.513+05:30", "RepeatMinutes": 0, "RecurrenceType": 1, "WeeklyDay": 0, "WeeklyRecurEvery": 0, "MonthlyDay": 0, "MonthlyRecurEvery": 0, "MonthlyIsByOrdinalDay": false, "MonthlyOrdinalDay": 0, "MonthlyDayOfTheWeek": 0 }, "JobDescription": "Demo Update Job", "SuccessNotification": { "ToEmailAddress": "[email protected]", "FromEmailAddress": "[email protected]", "Subject": "Collection-Evaluation-Reporting job completed successfully", "Body": "Sucess notification message" }, "FailureNotification": { "ToEmailAddress": "[email protected]", "FromEmailAddress": "[email protected]", "Subject": "Collection-Evaluation-Reporting job failed", "Body": "Failure notification message" }, "ShouldSendSuccessNotification": true, "ShouldSendFailureNotification": true, "JobName": "CreateJob_FreshCollectionEvaluation", "AssetsResolutionInfo": [{ "Id": "9C135703-B76E-4EFF-BFE2-8959D7CA4148", "Type": "symc-csm-AssetSystem-Asset-Wnt-Machine" }], "Standards": ["20ed033e-ea47-4783-ad9c-01b112733e89"] } }
HTTPS response codes for Search Job by Name API
Depending on the success or the failure of your API request, you see the following response codes for the Search Job by Name API:
HTTPS response codes for Search Job by Name API
Response Code
Response Type
Description
200
OK
The request is successfully completed. Job properties and job configuration details are available in response.
Job properties include the following details:
  • JobID
  • Name
  • Job type
  • Whether the job is a system-defined job or a custom job
  • Owner
  • Date when the job was created
  • Date when the job was modified
  • Date when the job was executed last
  • Status of the last job run
Job configuration details include the following information:
  • List of evaluation result viewers
  • Job schedule details
  • Job description
  • Success notification details
  • Failure notification details
  • ShouldSendSuccessNotification
  • ShouldSendFailureNotification
  • Name of the job
  • Asset resolution information such as ID and type
  • Standards used in the job
403
Forbidden
The following error message is displayed:
You are not authorized to perform this task. Access is denied.
401
Unauthorized
This may be because of an invalid or expired access token in an API request.
404
Not Found
The following error message is displayed:
  • Job for specified job name '#JobName' not found.
400
Bad Request
(Client Error)
The following error message is displayed:
  • Given job name is not valid. Provide valid job name.
500
Internal Server Error
(Server Error)
The following error message is displayed:
Server encountered an error while serving request. Please contact administrator if problem persists.
Sample Python script for Search Job by Name API
Click to view a sample Python script for Search Job by Name API
#Script to search job details by providing exact job name 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 #Search Job by Name API endpoint URL url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/Jobs" #Provide exact job name for searching job details querystring = {"jobname":"Online-Normal std-AL"} requests.packages.urllib3.disable_warnings(InsecureRequestWarning) bearertoken = "Bearer " + getToken() headers = {'Authorization': bearertoken,'Content-Type': "application/json"} response = requests.request("GET", url, headers=headers, params=querystring, verify=False) print(response.text) print(response.json)