Create Job (for data collection and evaluation)
Use this API to create a job in which a technical standard is used for data collection and evaluation.
You can create 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 the permissions to execute the following tasks to use the Create 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 Create Job API:
- Asset System
- Standards
Request method
To create a job by using a technical standard, create a
POST
request.HTTPS request components for Create Job API
Create a POST 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 Create Job API
The following table contains the description of the HTTPS request parameters for the Create Job API:
Field name | Field type | Data type | Description |
|---|---|---|---|
AssetsResolutionInfo | Mandatory | 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 | Mandatory | String | This is the name of the job that you want to create. |
Standards | Mandatory | IList<Guid> | This is a list of GUIDs of standards for which you carry out data collection. |
AssetTimeOut | Optional | Integer | This is the maximum time limit (in minutes) that you set for data collection on each agent-based asset. If the asset is unavailable even after this time limit, a timeout error is displayed for that asset. This option is applicable only for agent-based data collection. The value ranges from 1 to 500 minutes. |
JobType | Mandatory | String | This is the type of a job that you want to create. The type can be any of the following:
These JobType values are case-sensitive. |
JobDescription | Optional | String | This is the description of the job that you want to create. |
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 100 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:
See the Notification fields table. |
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:
See the Notification fields table. |
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. See the Schedule fields table. |
The Schedule data contract is an optional input for the Create Job API. The parameters that are used in an input request to schedule a job are listed along with their description in the following table. The
Control Compliance Suite
console UI label for each parameter is listed in the Corresponding UI label
column of the table :Schedule fields
Field name | Field type | Data type | Description | Corresponding UI element |
|---|---|---|---|---|
EndJobRunConfigured | Optional | Boolean | Set the value of this parameter to True if you want to limit job run duration by using the EndJobRunTimeInterval field. Job execution stops after the set time limit. | No corresponding UI element is available for this field. |
EndJobRunTimeInterval | Optional | String | Set the duration of a job execution in hours and minutes. | Limit run duration <number> Hrs <number> Mins |
SubScheduleRepeatDays | Optional | Integer | For an incomplete execution of a job, set the number of days after which you want to rerun the job. For example, if you want to rerun the job on a weekly basis, set the value 7. This value is considered when a job stops prematurely because of the values configured for the EndJobRunConfigured and the EndJobRunTimeInterval fields.Consider a use case where you run weekly compliance scans. You have created jobs to run for 4 hours on Friday, Saturday, and Sunday each. All the assets in your environment may not be reachable on all 3 days due to their maintenance cycles. For assets for which data is not collected on Friday, collection will be re-attempted on Saturday, and if needed, on Sunday. This provides better asset coverage. For this example of weekly compliance, the value of the SubScheduleRepeatDays field must be 1 | In the More Options section, the For incomplete execution, re-run every <number> Days field |
SubScheduleRepeatPeriodDays | Optional | Integer | Set the number of days for which you want to set the rerun schedule in case of incomplete data collection. For example, set the value 15 if you want to set the rerun schedule for a fortnight. | In the More Options section, the For incomplete execution, re-run For <number> Days field |
MonthlyDay | Optional | Integer | Set the day of the month on which you want the job to recur. This field is applicable only if you set the value of the RecurrenceType parameter to 3, which indicates Monthly recurrence. The value must be greater than or equal to 1. | In the Every list, if you select the Day option, you see a drop-down list to select the day.On the console UI, this option is visible if you select the Recurrence Type as Monthly . |
MonthlyDayOfTheWeek | Optional | Integer | The following are the possible values for the MonthlyDayOfTheWeek field:
| The weekday grid |
MonthlyIsByOrdinalDay | Optional | Boolean | To run the job on ordinal days, set the value of this parameter to True . Then, the day specified in the MonthlyOrdinalDay parameter or the MonthlyDayOfTheWeek parameter is considered for the job run. Set the value of this parameter to False , if you don't want to run the job on ordinal days. The default value is False . | This is an internal Boolean field. No corresponding UI element is available for this field. |
MonthlyOrdinalDay | Optional | Integer | The following are the possible values for the MonthlyOrdinalDay field:
| In the Every list, if you select the Week option, you see the drop-down list to select a week.On the console UI, this option is visible if you select the Recurrence Type as Monthly . |
MonthlyRecurEvery | Optional | Integer | Provide the number of months after which you want the job to recur. This field is applicable only if the RecurrenceType parameter is set to 3, which indicates Monthly recurrence. | Run every <number> Months |
RecurrenceType | Optional | Integer | The following are the possible values for the RecurrenceType field:
|
On the console UI, these radio buttons are visible if you select the Recurrence box. |
RepeatDays | Optional | Integer | Provide the number of days after which you want to re-run the job. The value for this field is considered only if you set the RunEveryNDays parameter to True . | Run every <number> Days On the console UI, this option is visible if you select the Recurrence Type as Daily . |
RunEveryNDays | Optional | Boolean | To run the job at a specified interval that is provided in the RepeatDays field, set the value of this parameter to True . | This is an internal Boolean field, which supports the RepeatDays field. No corresponding UI element is available for this field. |
RunNow | Optional | Boolean | To run the job immediately on the start date, set the value of this parameter to True . The default value is True . | Run Now |
RunOnce | Optional | Boolean | To run the job once on the StartDate, set the value of this parameter to True .The default value of this parameter is False . | Run on |
RunPeriodically | Optional | Boolean | To run the job periodically, set the value of this parameter to True . The default value of this parameter is False . If you set this parameter to True , you must set either of the following parameters to True :
| Recurrence |
StartDate | Optional | DateTime | Set the date on which you want to start the job run. If the value of the RunNow parameter is set to True , the job is run immediately after you create it.If the value of the RunPeriodically parameter is set to True , do either of the following:
| Start Date |
WeeklyDay | Optional | Integer | The following are the possible values for the DayOfWeek enumeration:
| Weekday grid below the Run every <number> Weeks listOn the console UI, this option is visible if you select the Recurrence Type as Weekly . |
WeeklyRecurEvery | Optional | Integer | The number of weeks that you want the job to recur. This field is applicable only if RecurrenceType is set as Weekly. | Run every <number> Weeks On the console UI, this option is visible if you select the Recurrence Type as Weekly . |
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 Create Job API
The POST request for the Create Job API returns the response body in the following structure:
{ "JobID": {GUID} }
Sample HTTPS request for Create Job API
The following is a sample HTTPS request for your reference.
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 |
|
Sample HTTPS response for Create Job API
{"JobID":"5ade67f0-0c93-49f3-9f2b-b8ec4beaa99c"}
HTTPS response codes for Create Job API
Depending on the success or the failure of your API request, you see the following response codes for the Create Job API:
Response Code | Response Type | Description |
|---|---|---|
200 | OK | The request is successfully completed. The Job ID is available. |
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:
|
500 | Internal Server Error (Server Error) | The following error message is displayed:
|
Sample Python script for Create Job API
Click to view a sample Python script for Create Job API
#Script to create a job of type 'Collection Evaluation', 'Data Collection' and 'Evaluation'. 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 #Create Job API endpoint URL. url = "https://" + HostName + ":" + PortNumber + "/ccs/api/v1/jobs" #Provide Asset GUID and Asset Type, ,Standard GUID, job name and Job type.Supported Job Types for job creation: CollectionEvaluationJob, CollectionJob, EvaluationJob. #Asset GUID and Asset Type can be retrieved by using SearchAsset API, Standard GUID can be retrieved by using Search Standard API. #Following is the example of creating CollectionEvaluation job with minimal required parameters. It will only create the job. payload = "{\"JobDetails\":{\"AssetsResolutionInfo\": [{\"Id\": \"d387d8b5-6278-4bcb-83c7-b55d2072d2a8\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"}],\"JobDescription\": \"Test CER Job\",\"JobName\": \"Test_Job11\",\"Standards\": [\"6b020d29-5fe8-47d0-bd89-ccd3339a5ebe\"]},\"JobType\":\"CollectionEvaluationJob\"}" #Following is the example of creating job with runnow parameter set to true. It will create the job and run the job. #In this example, 'runnow' parameter is set to true. #payload = "{\"JobDetails\":{\"AssetsResolutionInfo\": [{\"Id\": \"d387d8b5-6278-4bcb-83c7-b55d2072d2a8\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"}],\"JobDescription\": \"Demo Data Collection Job\",\"JobName\": \"A1_CollectionJob_RUNOW\",\"Standards\": [\"6B020D29-5FE8-47D0-BD89-CCD3339A5EBE\"],\"Schedule\": {\"EndJobRunConfigured\": false, \"EndJobRunTimeInterval\": \"00:00:00\",\"SubScheduleRepeatDays\": 0,\"SubScheduleRepeatPeriodDays\": 0,\"MonthlyDay\": 0,\"MonthlyDayOfTheWeek\": 0,\"MonthlyIsByOrdinalDay\": false,\"MonthlyOrdinalDay\": 0, \"MonthlyRecurEvery\": 0, \"RecurrenceType\": 0,\"RepeatDays\": 50,\"RepeatMinutes\": 0,\"RunEveryNDays\": true,\"RunNow\": true,\"RunOnce\": false,\"RunPeriodically\": false,\"StartDate\": \"2018-11-18T02:14:27.5120788-08:00\", \"WeeklyDay\": 0, \"WeeklyRecurEvery\": 0}},\"JobType\":\"CollectionJob\"}" #Following is the example of creating job and shcedule a job run. It will create the job and schedule the job run as mentioned in the input URL. #In this example, RunPeriodically parameter is set to true. #payload = "{\"JobDetails\":{\"AssetsResolutionInfo\": [{\"Id\": \"d387d8b5-6278-4bcb-83c7-b55d2072d2a8\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"}],\"JobDescription\": \"Demo Data Collection Job by scheduling it\",\"JobName\": \"A1_CollectionJob_ScheduleRun\",\"Standards\": [\"6B020D29-5FE8-47D0-BD89-CCD3339A5EBE\"],\"Schedule\": {\"EndJobRunConfigured\": false, \"EndJobRunTimeInterval\": \"00:00:00\",\"SubScheduleRepeatDays\": 0,\"SubScheduleRepeatPeriodDays\": 0,\"MonthlyDay\": 0,\"MonthlyDayOfTheWeek\": 0,\"MonthlyIsByOrdinalDay\": false,\"MonthlyOrdinalDay\": 0, \"MonthlyRecurEvery\": 0, \"RecurrenceType\": 0,\"RepeatDays\": 50,\"RepeatMinutes\": 0,\"RunEveryNDays\": true,\"RunNow\": false,\"RunOnce\": false,\"RunPeriodically\": true,\"StartDate\": \"2019-01-05T04:10:27.5120788-08:00\", \"WeeklyDay\": 0, \"WeeklyRecurEvery\": 0}},\"JobType\":\"CollectionJob\"}" #Following is the example of creating job with multiple assets. #In this example, multiple asset IDs are mentioned under AssetsResolutionInfo. #payload = "{\"JobDetails\":{\"AssetsResolutionInfo\": [{\"Id\": \"d387d8b5-6278-4bcb-83c7-b55d2072d2a8\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"},{\"Id\": \"1169462b-e9bd-46f4-827a-7ac9b1a220d1\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"}],\"JobDescription\": \"Demo Data Collection Job on muktiple assets\",\"JobName\": \"A1_CollectionJob_MultipleAssets\",\"Standards\": [\"6B020D29-5FE8-47D0-BD89-CCD3339A5EBE\"],\"Schedule\": {\"EndJobRunConfigured\": false, \"EndJobRunTimeInterval\": \"00:00:00\",\"SubScheduleRepeatDays\": 0,\"SubScheduleRepeatPeriodDays\": 0,\"MonthlyDay\": 0,\"MonthlyDayOfTheWeek\": 0,\"MonthlyIsByOrdinalDay\": false,\"MonthlyOrdinalDay\": 0, \"MonthlyRecurEvery\": 0, \"RecurrenceType\": 0,\"RepeatDays\": 50,\"RepeatMinutes\": 0,\"RunEveryNDays\": true,\"RunNow\": true,\"RunOnce\": false,\"RunPeriodically\": false,\"StartDate\": \"2018-11-18T02:14:27.5120788-08:00\", \"WeeklyDay\": 0, \"WeeklyRecurEvery\": 0}},\"JobType\":\"CollectionJob\"}" #Following is the example of creating and running job with success and failure notifications. #In this example, You need to configure your FailureNotification and SuccessNotification. #payload = "{\"JobDetails\":{\"AssetsResolutionInfo\": [{\"Id\": \"d387d8b5-6278-4bcb-83c7-b55d2072d2a8\",\"Type\": \"symc-csm-AssetSystem-Asset-Unix-Machine\"}],\"JobDescription\": \"Demo Data Collection Job with notifications\",\"JobName\": \"A1_CollectionJob_RUNOW_WithNotifications\",\"Standards\": [\"6B020D29-5FE8-47D0-BD89-CCD3339A5EBE\"],\"FailureNotification\":{\"FromEmailAddress\":\"[email protected]\",\"Subject\":\"Collection-Evaluation-Reporting job failed\",\"ToEmailAddress\":\"[email protected]\",\"Body\":\"Failure notification message\"},\"SuccessNotification\":{\"FromEmailAddress\":\"[email protected]\",\"Subject\":\"Collection-Evaluation-Reporting job completed successfully\",\"ToEmailAddress\":\"[email protected]\",\"Body\":\"Success notification message\"},\"ShouldSendFailureNotification\":\"true\",\"ShouldSendSuccessNotification\":\"true\",\"Schedule\": {\"EndJobRunConfigured\": false, \"EndJobRunTimeInterval\": \"00:00:00\",\"SubScheduleRepeatDays\": 0,\"SubScheduleRepeatPeriodDays\": 0,\"MonthlyDay\": 0,\"MonthlyDayOfTheWeek\": 0,\"MonthlyIsByOrdinalDay\": false,\"MonthlyOrdinalDay\": 0, \"MonthlyRecurEvery\": 0, \"RecurrenceType\": 0,\"RepeatDays\": 50,\"RepeatMinutes\": 0,\"RunEveryNDays\": true,\"RunNow\": true,\"RunOnce\": true,\"RunPeriodically\": false,\"StartDate\": \"2019-01-04T02:14:27.5120788-08:00\", \"WeeklyDay\": 0, \"WeeklyRecurEvery\": 0}},\"JobType\":\"CollectionJob\"}" requests.packages.urllib3.disable_warnings(InsecureRequestWarning) bearertoken = "Bearer " + getToken() headers = { 'Authorization': bearertoken , 'Content-Type': "application/json" } response = requests.request("POST", url, data=payload, headers=headers, verify=False) print(response.text) print(response.json)