Update Job (for data collection and evaluation)
Use this API to update a job in which a technical standard is used for data collection and evaluation.
You can update the following jobs with this API:
- Collection-Evaluation Job
- Data Collection Job
- Evaluation 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 have permissions to execute the following tasks to use the Update Job API:
- View standards
- View assets
- Manage jobs
- Collect data
- Evaluate standards
- View evaluation results
You must have the permission to access the following folders to use the Update Job API:
- Asset System
- Standards
Request method
To update a Collection-Evaluation job, a Data Collection job, or an Evaluation job, create a
PATCH
request.HTTPS request components for Update Job API
Create a PATCH 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 Update Job API
The following table contains the description of the HTTPS request parameters for the Update Job API. You can update all or any of these parameters to update the job.
Field name | Field type | Data type | Description |
|---|---|---|---|
AssetsResolutionInfo | Optional | IList<AssetResolutionInfo> | The AssetResolutionInfo data contract
contains the asset GUID and the corresponding asset type. This is the list of assets or asset groups against which you carry out data collection or evaluation. |
JobName | Optional | String | This is the name of the job that you want to update. |
Standards | Optional | IList<Guid> | This is a list of GUIDs of standards for which you carry out data collection. |
JobID | Mandatory | GUID | You can update a job only if the specified JobID belongs to one of the following types:
|
JobDescription | Optional | String | This is the description of the job that you want to update. |
IsIncremental | Optional | Boolean | True or False value of this field denotes whether you want to enable or disable collecting data only if the available data is older than the specified number of days in a CER job.
If you include the IncrementalPeriod field in the JSON body, the IsIncremental field is set to True. If IncrementalPeriod is not included in the JSON body, the default value of IsIncremental is set to False. Irrespective of the IncrementalPeriod presence in the JSON body, set IsIncremental to False if you want to disable this function. |
IncrementalPeriod | Optional | Integer | Specify how many days older data must be ignored during asset data collection using a CER job. You can set up to 1000 days.
If this field is not included in the JSON body, and IsIncremental is set to True, IncrementalPeriod is set to 1. If this field is not included in the JSON body, the IncrementalPeriod is set to 1 ** |
CollectionOnlyTimeOutHours | Optional | Integer | Set the limit for the data collection activity of a CER job to the specified hours. You can set up to 1000 hours. |
CollectionOnlyTimeOutMins | Optional | Integer | Set the limit for the data collection activity of a CER job to the specified minutes. You can set up to 59 minutes. |
SuccessNotification | Mandatory (if the value of the ShouldSendSuccessNotification field is set to True)Optional (if the value of the ShouldSendSuccessNotification field is set to False) | NotificationData | This is the data in the NotificationData class. This notification is sent to the user if the job is executed successfully. The notification data comprises the following:
|
FailureNotification | Mandatory (if the value of the ShouldSendFailureNotification field is set to True)Optional (if the value of the ShouldSendFailureNotification field is set to False) | NotificationData | This is the data in the NotificationData data class. This notification is sent to the user if the job is not executed successfully. The notification data contains the following:
|
ShouldSendSuccessNotification | Optional | Boolean | The True or False value of this field denotes whether you want to enable notifications for job success. |
ShouldSendFailureNotification | Optional | Boolean | The True or False value of this field denotes whether you want to enable notifications for job failure. |
ShouldSynchronizeResults | Optional | Boolean | The True or False value of this field denotes whether the evaluation results should be synchronized with the reporting database.Reports are generated by using stale data if the Reporting Synchronization settings are not configured from the Settings > Application Settings > System Configuration > Reporting Synchronization . |
Schedule | Optional | IncrementalScheduleData | This field contains data related to the job schedule. |
The NotificationData class serves as an input for the APIs that require to send notification to the specified Email ID upon success or failure of the operation. The success notification and failure notification contain the following inputs:
Field name | Field type | Data type | Description |
|---|---|---|---|
ToEmailAddress | Mandatory (if the value of the ShouldSendSuccessNotification field and/or ShouldSendFailureNotification field is set to True)Optional (if the value of the ShouldSendSuccessNotification field and/or ShouldSendFailureNotification field is set to False) | String | This field comprises the email address of the intended recipient. |
FromEmailAddress | String | This field comprises the email address of the sender. | |
Subject | String | This field comprises the subject of email notification. | |
Body | String | This field comprises the body or the message text that must be sent in notification. |
Response body for Update Job API
The PATCH request for the Update Job API returns the response body in the following structure:
204 (No content)
Sample HTTPS request for Update Job API
{"JobDetails":{"AssetsResolutionInfo": [{"Id": "5ed919fd-9f70-429a-bd36-f22bcbbe8fa4","Type": "symc-csm-AssetSystem-Asset-Wnt-Machine"}],"JobName": "Example_REST"}, "JobID":"591f2322-3ba4-4626-b5d0-8028497f362f"}
Depending on the input parameters that you provide in this request, the data in the job definition is replaced.
Sample HTTPS response for Update Job API
204 (No content)
HTTPS response codes for Update Job API
Depending on the success or the failure of your API request, you see the following response codes for the Update Job API:
Response Code | Response Type | Description |
|---|---|---|
204 | No content | The request is successfully completed. However, there is no content to return. |
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. |
400 | Bad Request (Client Error) | One of the following error messages is displayed:
|
404 | Not found | The following error message is displayed:
|
500 | Internal Server Error (Server Error) | The following error message is displayed:
|
Sample Python script for Update Job API
Click to view a sample Python script for Update Job API
# Script to update any exising job details in the CCS system import requests from requests.packages.urllib3.exceptions import InsecureRequestWarning # Variable # 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'] print("bearer Token is:\n") print(token) print("\n Refresh Token is:\n") print(refreshToken) return token # CCS Job URI url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/Jobs" requests.packages.urllib3.disable_warnings(InsecureRequestWarning) # Update the job details by providing the job name and Job GUID. we can get the job GUID by using search job by name API. payload = "{\"JobDetails\":{\"JobDescription\": \"Update Job Description\",\"JobName\": \"Test_Job\"},\"JobID\":\"2a221e47-f38a-4a6b-af20-43d650e6d56b\"}" bearertoken = "Bearer " + getToken() headers = { 'Authorization': bearertoken, 'Content-Type': "application/json" } response = requests.request("PATCH", url, data=payload, headers=headers, verify=False) print(response.text) print(response.json)