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:
HTTPS request components for Update Job API
Request component
Value
URL
https://<hostname>:<port number>/ccs/api/v1/jobs/
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
{ "JobDetails": { "AssetsResolutionInfo": [{ "Id": "Asset Guid", "Type": "Asset Type" }], "JobDescription": "description", "JobName": "Job Name", "Standards": ["standard guid"], "IsIncremental":bool, "IncrementalPeriod":INT, "CollectionOnlyTimeOutMins":INT, "CollectionOnlyTimeOutHours":INT, "FailureNotification": { "FromEmailAddress": "Email Address", "Subject": "subject", "ToEmailAddress": "Email Address", "Body": "Message" }, "SuccessNotification": { "FromEmailAddress": "Email Address", "Subject": "Subject", "ToEmailAddress": "Email Address", "Body": "Message" }, "ShouldSendFailureNotification": "bool", "ShouldSendSuccessNotification": "bool", "ShouldSynchronizeResults":"bool" "Schedule": { "EndJobRunConfigured": bool, "EndJobRunTimeInterval": "00:00:00", "SubScheduleRepeatDays": INT, "SubScheduleRepeatPeriodDays": INT, "MonthlyDay": INT, "MonthlyDayOfTheWeek": INT, "MonthlyIsByOrdinalDay": bool, "MonthlyOrdinalDay": INT, "MonthlyRecurEvery": INT, "RecurrenceType": INT, "RepeatDays": INT, "RepeatMinutes": INT, "RunEveryNDays": bool, "RunNow": bool, "RunOnce": bool, "RunPeriodically": bool, "StartDate": "date", "WeeklyDay": INt, "WeeklyRecurEvery": INT } }, "JobID": "Guid" }
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.
HTTPS request parameters for Update Job API
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:
  • CollectionEvaluationJob
  • DataCollectionJob
  • EvaluationJob
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:
  • Email address of the sender
  • Subject
  • Email address of the intended recipient
  • Message
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:
  • Email address of the sender
  • Subject
  • Email address of the intended recipient
  • Message
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:
Notification fields
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:
HTTPS response codes for 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:
  • Invalid input data. Either JobID or JobDetails is null.
  • The specified name <Job Name> already exists. Create a job with a new name.
  • Exception while parsing JSON. Please check expected type of input parameter and its given value.
  • Given job type '#jobtype' not supported.
404
Not found
The following error message is displayed:
Job for specified JobID '#JobID' not found.
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 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)