Search Jobs

Use this API to retrieve the list of jobs in the
Control Compliance Suite
by providing one or more of the following job properties in the request:
  • JobName
  • JobID
  • JobCategory
  • JobType
  • JobCreationTime
  • JobModifiedTime
  • LastRunStatus
  • LastRunDate
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 only job properties.
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 Jobs API:
  • View All Jobs
  • View Standards
  • View Assets
You must have permission to access the following folders to use the Search Jobs API:
  • Asset System
  • Standards
Request method
To retrieve the list of
Control Compliance Suite
jobs in your environment, create a
GET
request.
HTTPS request components for Search Jobs API
Create a GET request by using the following components:
Request component
Value
URL
https://<hostname>:<port number>/ccs/api/v1/ Jobs?(Attributes=Attribute1 = value1)&page=<number>&pagesize=<number>
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 Search Jobs API
The following table descibes the supported HTTPS request parameters that can be used in the Search Jobs API:
Field name
Field type
Data type
Description
Attributes
Mandatory
String
The following job parameters are supported as attributes:
  • JobName
  • JobID
  • JobCategory
  • JobType
  • JobCreationTime
  • JobModifiedTime
  • LastRunStatus
  • LastRunDate
For information about these parameters and their supported operators, see Supported Job Parameters.
Multiple attributes can be separated by a comma. Comma in the list of attributes can be the 'AND' logical operator that is represented by ',' or the "OR' logical operator that is represented by "|'. Note the following conditions to use these logical operators in a request:
  • A request can include either AND or OR within a parentheses set but not both within the same parentheses set.
    • Valid request example
      : attributes=(JobName Contains Health | JobCategory=Userdefined | LastRunstatus=Completed) , (LastRunDate=2020-08-11 10:52:46 , JobType=NOTIFICATION_CONSOLIDATION_JOB)
    • Invalid request example
      : attributes=(JobName Contains Health | JobCategory=Userdefined , LastRunstatus=Completed) , (LastRunDate=2020-08-11 10:52:46 , JobType=NOTIFICATION_CONSOLIDATION_JOB)
  • A request can include only up to two sets of parentheses.
    • Valid request
      example
      : attributes=(JobName Contains Health | JobCategory=Userdefined) , (LastRunDate=2020-08-11 10:52:46 , JobType=NOTIFICATION_CONSOLIDATION_JOB)
    • Invalid request example
      : attributes= (JobName Contains Health | JobCategory=Userdefined | LastRunstatus=Completed) , (LastRunDate=2020-08-11 10:52:46 , JobType=NOTIFICATION_CONSOLIDATION_JOB) , (LastRunDate=2021-08-11 10:52:46 , JobType=NOTIFICATION_CONSOLIDATION_JOB)
The
Search Jobs
API returns a list of jobs along with their total count.
Page
Optional
Integer
Considering that the Search Jobs API can return huge data depending on the number of jobs in your system, pagination support is added. By using the
Page
parameter, you can specify the page number to retrieve in response to the API call. The default value of this parameter is 0.
PageSize
Optional
Integer
By using this parameter, you can decide how many result entries should be displayed on a single page. The default value of this parameter is 1000.
Supported Job Parameters
The following table describes the supported job parameters in detail:
Job Parameter
Description
JobName
Allows searching for all the jobs in the system, or for a specific job using its exact or partial name.
  • To search for a job using its exact name, use the
    =
    operator and enter the complete job name as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobName=HealthStatus)
  • To search for a job using its partial name, use the
    Contains
    operator and enter a part of the job name as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobName Contains Health)
  • To search for all the jobs in the system, use the
    =
    operator and enter
    *
    as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobName=*)
JobID
Allows searching for a job using its exact ID.
To search using this parameter, use the
=
operator and enter the complete job ID as the parameter value.
Example
: https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=(JobID=013e0081-80ed-4bae-b1d9-cb8554d4f3b4)
JobCategory
Allows searching for a job using its category.
To search using this parameter, use the
=
operator and enter
SystemJob
or
Userdefined
as the parameter value.
Example
: https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=(JobCategory=Userdefined)
JobType
Allows searching for a job using its type.
To search using this parameter, use the
=
operator and enter any of the supported job types as the parameter value.
Example
: https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=(JobType=NOTIFICATION_CONSOLIDATION_JOB)
JobCreationTime
Allows searching for a job using its creation date and time.
  • To search for a job that is created before a specific date and time, use the
    Before
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobCreationTime before 2020-08-11 10:52:46)
  • To search for a job that is created after a specific date and time, use the
    After
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobCreationTime after 2020-08-11 10:52:46)
  • To search for a job that is created within a time period, use the
    Between
    operator, and enter both the dates and times in the
    YYYY-MM-DD HH:MM:SS
    format, separated by a tilde (~), as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobCreationTime between 2020-08-11 10:52:46 ~ 2022-02-11 10:52:46)
  • To search for a job that is created at a specific date and time, use the
    =
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobCreationTime=2020-08-11 10:52:46)
JobModifiedTime
Allows searching for a job using its modified date and time.
  • To search for a job that is modified before a specific date and time, use the
    Before
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobModifiedTime before 2020-08-11 10:52:46)
  • To search for a job that is modified after a specific date and time, use the
    After
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobModifiedTime after 2020-08-11 10:52:46)
  • To search for a job that is modified within a time period, use the
    Between
    operator, and enter both the dates and times in the
    YYYY-MM-DD HH:MM:SS
    format, separated by a tilde (~), as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobModifiedTime between 2020-08-11 10:52:46 ~ 2022-02-11 10:52:46)
  • To search for a job that is modified at a specific date and time, use the
    =
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(JobModifiedTime=2020-08-11 10:52:46)
LastRunStatus
Allows searching for a job using its last run status.
To search using this parameter, use the = operator and enter one of the following values as the parameter value:
  • None
  • Pending
  • Executing
  • Idle
  • Completed
  • Faulted
  • Custom
  • Aborted
Example
: https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=(LastRunstatus=Completed)
LastRunDate
Allows searching for a job using its last run date and time.
  • To search for a job that is last run before a specific date and time, use the
    Before
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(LastRunDate before 2020-08-11 10:52:46)
  • To search for a job that is last run after a specific date and time, use the
    After
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(LastRunDate after 2020-08-11 10:52:46)
  • To search for a job that is last run within a time period, use the
    Between
    operator, and enter both the dates and times in the
    YYYY-MM-DD HH:MM:SS
    format, separated by a tilde (~), as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(LastRunDate between 2020-08-11 10:52:46 ~ 2022-02-11 10:52:46)
  • To search for a job that is last run at a specific date and time, use the
    =
    operator, and enter the date and time in the
    YYYY-MM-DD HH:MM:SS
    format as the parameter value.
    Example
    : https://
    <hostname>
    :
    <port-number>
    /ccs/api/v1/jobs?Attributes=(LastRunDate=2020-08-11 10:52:46)
Sample HTTPS request for Search Jobs API
The following is a sample HTTPS request:
Request component
Value
URL
GET https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=(JobName Contains demo | LastRunStatus = Completed)&page=8&pagesize=2
Content type
application/json
Sample HTTPS response for Search Jobs API
The sample HTTPS request that you created earlier returns the following response:
{ "TotalCount": 20, "TotalPages": 10, "PrevPageUrl": "https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=%28%20jobname%20contains%20demo%20%7C%20lastrunstatus%20%3D%20completed%29&page=7&pagesize=2", "NextPageUrl": "https://
<hostname>
:
<port-number>
/ccs/api/v1/jobs?Attributes=%28%20jobname%20contains%20demo%20%7C%20lastrunstatus%20%3D%20completed%29&page=9&pagesize=2", "jobdata": [ { "JobProperties": { "IsSystemJob": false, "JobCreationTime": "2022-03-28T10:52:44", "JobID": "bacbc533-b146-41e8-b6f0-023461cbcd73", "JobModifiedTime": "2022-03-28T10:52:44", "JobType": "DATA_COLLECTION", "LastRunDate": "2022-03-28T10:52:46", "LastRunStatus": 5, "Name": "demo4", "Owner": "CCS\\keiko" }, "JobConfigDetails": { "Schedule": { "SubScheduleRepeatDays": 0, "SubScheduleRepeatPeriodDays": 0, "EndJobRunTimeInterval": "00:00:00", "EndJobRunConfigured": false, "RepeatDays": 1, "RunEveryNDays": false, "RunOnce": false, "RunNow": false, "RunPeriodically": false, "StartDate": "2022-03-28T03:55:05.6556333-07:00", "RepeatMinutes": 0, "RecurrenceType": 0, "WeeklyDay": 0, "WeeklyRecurEvery": 0, "MonthlyDay": 0, "MonthlyRecurEvery": 0, "MonthlyIsByOrdinalDay": false, "MonthlyOrdinalDay": 0, "MonthlyDayOfTheWeek": 0 }, "DataCollectionCriteria": 1, "JobDescription": "", "SuccessNotification": { "ToEmailAddress": null, "FromEmailAddress": null, "Subject": null, "Body": null }, "FailureNotification": { "ToEmailAddress": null, "FromEmailAddress": null, "Subject": null, "Body": null }, "IsIncremental": false, "IncrementalPeriod": "01:00:00", "AssetTypes": [], "JobName": "demo4", "AssetsResolutionInfo": [ { "Id": "b3a8cca5-d7f0-4a56-b6de-311cb2507c46", "Type": "symc-ContainerNode" } ], "Standards": [ "db2400ba-2c57-4db0-b789-9127b83042f4" ], "AssetTimeOut": 0 } }, { "JobProperties": { "IsSystemJob": true, "JobCreationTime": "2022-03-09T06:24:23", "JobID": "bc1a753f-7126-43cb-b1a8-62d39cb9cd46", "JobModifiedTime": "2022-03-09T06:24:24", "JobType": "DOWNLOAD_LU_JOB", "LastRunDate": "2022-03-28T10:33:50", "LastRunStatus": 4, "Name": "Download Live Updates", "Owner": "CCS\\keiko" }, "JobConfigDetails": null } ] }
HTTPS response codes for Search Jobs API
Depending on the success or the failure of your API request, you see the following response codes for the Search Jobs 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 example error message is displayed:
  • Job for specified job name '#JobName' not found.
400
Bad Request
(Client Error)
The following example 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 Jobs API
Click to view a sample Python script for Search Jobs API
#Script to search job details by providing the 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 requests.packages.urllib3.disable_warnings(InsecureRequestWarning) bearertoken = "Bearer " + getToken() headers = {'Authorization': bearertoken,'Content-Type': "application/json"} response = requests.request("GET", url, headers=headers, verify=False) print(response.text) print(response.json)