symantec-logo-top
Symantec™ Control Compliance Suite

Symantec™ Control Compliance Suite

REST API Guide (version 1.0)

1. Getting Started

1.1. Introduction

Symantec Control Compliance Suite (CCS) RESTful APIs enable you to seamlessly integrate your applications with CCS and customize your code to best suit your requirements. You can also use these APIs to automate and optimize the CCS workflow. Token-based authentication is used to grant access to integrating applications to view and execute CCS RESTful APIs. These APIs use standard HTTPS features, and standard HTTPS response status codes to indicate whether a specific HTTPS request is successfully completed. The APIs return data in JSON and XML file formats.

1.2. Using token-based authentication for Control Compliance Suite RESTful APIs

To use Control Compliance Suite RESTful APIs, you must first generate an authentication token, and use it in the subsequent API calls. To generate an authentication token, you must create a POST request by using your Windows credentials. You receive an access token along with a refresh token. You must use these tokens in every subsequent API call.

The access token is valid till Application Server Service is running. If you want to restart the Application Server Service, you must regenerate an access token using the refresh token.

When the Application Server Service is running, access token is valid for 60 minutes. After the access token expires, you must use the refresh token to create another POST request to get a new access token and a new refresh token. A refresh token is valid for 90 minutes. If both the access token and the refresh token expire, you must create a POST request by using your Windows credentials again.

If you want to change the validity period of a token, you must add the following keys in the Application Settings of the AppserverService configuration file. The respective values of the keys must be added in seconds.

  • <add key="RefreshTokenExpirationTimeInSeconds" value="<value in seconds>" />

  • <add key="AccessTokenExpirationTimeInSeconds" value="<value in seconds>" />

Note

To generate a token, you must have the Log on as a batch job right on the computer on which Control Compliance Suite is installed.

1.2.1. Request method

To receive an access token and the refresh token, create a POST request.

1.2.2. URL

Use the following URL when you create a POST request to receive an access token with a refresh token:

https://<hostname>:<port number>/ccs/api/v1/oauth/tokens

1.2.3. HTTPS request body for access token

Create a POST request to receive an access token by using the following structure:

grant_type=password&username=<user name>&password=<password>
Note

Request parameters are case sensitive. Follow the exact syntax.

1.2.4. HTTPS request parameters for access token

The following table contains the description of the parameters that you use in the HTTPS request to receive an access token:

Field name

Field type

Data type

Description

grant_type

Mandatory

String

For a request for access token, the value of this parameter must be Password.

This value is not case-sensitive.

username

Mandatory

String

This is the username that you want to send to the Control Compliance Suite Application Server for authentication.

password

Mandatory

String

This is the password for the user account that needs to be authenticated.

1.2.5. HTTPS request body for refresh token

Create a POST request to receive a refresh token by using the following structure:

grant_type=refresh_token&refresh_token=<refresh token>
Note

Request parameters are case sensitive. Follow the exact syntax.

1.2.6. HTTPS request parameters for refresh token

The following table contains the description of the parameters that you use in the HTTPS request to receive a refresh token:

Field name

Field type

Data type

Description

grant_type

Mandatory

String

For a request for refresh token, the value of this parameter must be Refresh_Token.

This value is not case-sensitive.

refresh_token

Mandatory

String

This is the refresh token that you want to send to the Control Compliance Suite Application Server to receive a new access token and a refresh token.

1.2.7. HTTPS response codes

Depending on the success or the failure of your API request, you see the following response codes:

Response Code

Response Type

Description

200

OK

The token is created successfully.

403

Forbidden

This may be because the identified user does not have proper authorization to access the requested content.

401

Unauthorized

The following error message is displayed:

Invalid credentials.

This may be because of any of the following reasons:

  • User credentials are invalid.

  • User does not exist.

400

Bad Request

(Client Error)

This may be because of any of the following:

  • User credentials are invalid.

  • No token is provided in the request.

  • The token in the request is tampered.

  • Refresh token is either invalid or expired.

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.

1.2.8. Sample Python script

Refer to the sample python script, which is available at the following GitHub location:

1.3. Version information

The Control Compliance Suite RESTful API version 1.0 supports Control Compliance Suite 12.5 and later.

1.4. URL scheme

The following is the base URL for the CCS RESTful APIs:

https://<server>:<port number>/ccs/api/v1/<resource>
Note

Here <server> can be an IP address, a hostname, or an FQDN. You can configure the port number from the Integration Services Endpoint Configuration dialog box from Settings > Deployment View on the Control Compliance Suite console. If you do not configure the port, the default port is considered in the request. The default port is 12431.

The relative path prefix /v1/ indicates that the version of this set of CCS RESTful APIs is 1.0.

2. APIs for Asset Service

2.1. Create Asset (for agentless data collection only )

Use this API to create an asset (What is an asset?) or multiple assets in the Control Compliance Suite asset system. This API can be used only to create assets for agentless data collection method of Control Compliance Suite.

2.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

2.1.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Create Asset API:

  • View assets

  • Manage assets and asset groups

To use the Create Asset API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

2.1.3. Request method

To create an asset by using a technical standard, create a POST request.

2.1.4. HTTPS request components for Create Asset API

Create a POST request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/assets
Note

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

[
{
        "Type" : "symc-csm-AssetSystem-Asset-Wnt-Machine",
        "symc-csm-AssetSystem-Asset-Wnt-Machine-HostName" : "<hostname>",
        "symc-csm-AssetSystem-Asset-Wnt-Machine-DomainWorkgroupName" : "<domain name>"
}
,{
        "Type" : "symc-csm-AssetSystem-Asset-Cisco-Router",
        "symc-csm-AssetSystem-Asset-Cisco-Router-IPAddress" : "<IP>"
        }
        , {
        "Type" : "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-HOSTMACHINE" : "<hostname>",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-IPAddress" : "<IP>",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-InstancePortNumber" : "<Number>"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Unix-Machine",
        "symc-csm-AssetSystem-Asset-Unix-Machine-IPAddress" : "IP"   ,
        "symc-csm-AssetSystem-Asset-Unix-Machine-HostMachine" : "<hostname>"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Dbif-server",
        "symc-csm-AssetSystem-Asset-Dbif-server-SQLServerDomainName" : "<domain name>"   ,
        "symc-csm-AssetSystem-Asset-Dbif-server-hostName" : "<hostname>" ,
        "symc-csm-AssetSystem-Asset-Dbif-server-serverName" : "<server name>"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers",
                                "container" : "Assets\\",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-HOSTMACHINE" : "<hostname>",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-IPAddress" : "<IP>",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-InstancePortNumber" : <Number>
        }
]

2.1.5. HTTPS request parameters for Create Asset API

The following table contains the description of the HTTPS request parameters for the Create Asset API. The parameters vary depending on the platform for which you create the request.

Note

The optional fields in the following tables are marked as optional for asset creation only. They may be mandatory for data collection on assets.

HTTPS request parameters for Windows

Field name

Corresponding UI label

Field type

Data type

Description

Type

On the console, in the Add Assets wizard, on the Select Creation Option screen, the Asset Type list

Mandatory

String

The value of this parameter must be symc-csm-AssetSystem-Asset-Wnt-Machine.

symc-csm-AssetSystem-Asset-Wnt-Machine-HostName

Machine Name

Mandatory

String

The value of this parameter must be the host name of the Windows asset that you want to create.

symc-csm-AssetSystem-Asset-Wnt-Machine-DomainWorkgroupName

Domain/Workgroup Name

Mandatory

String

The value of this parameter must be the domain name or the workgroup name of the asset that you want to create.

symc-csm-AssetSystem-Asset-Wnt-Machine-OSVersionType

OS Type

Optional

String

The value of this parameter must be the Windows version of the asset that you want to create.

For example, Microsoft Windows Server 2008 Enterprise version 6.0 Service Pack 2 (Build 6002)

symc-csm-AssetSystem-Asset-Wnt-Machine-OSMajorVersionNumber

OS Major Version Number

Optional

Int

The value of this parameter must be the supported major version of the Windows operating system of the asset that you want to create.

symc-csm-AssetSystem-Asset-Wnt-Machine-OSMinorVersionNumber

OS Minor Version Number

Optional

Int

The value of this parameter must be the supported minor version of the Windows operating system of the asset that you want to create.

HTTPS request parameters for UNIX

Field name

Corresponding UI label

Field type

Data type

Description

Type

On the console, in the Add Assets wizard, on the Select Creation Option screen, the Asset Type list

Mandatory

String

The value of this parameter must be symc-csm-AssetSystem-Asset-Unix-Machine.

symc-csm-AssetSystem-Asset-Unix-Machine-HostMachine

Machine Name

Mandatory

String

Provide the host name of the UNIX asset that you want to create.

symc-csm-AssetSystem-Asset-Unix-Machine-IPAddress

IP Address

Mandatory

String

Provide the IP address of the UNIX asset that you want to create.

symc-csm-AssetSystem-Asset-Unix-Machine-OSDistributionField

Operating Distribution Field

Optional

String

Provide the distribution details of the operating system of the asset that you want to create.

For example, for an RHEL asset, the value of this field can be Red Hat Enterprise Linux Server x86_64

symc-csm-AssetSystem-Asset-Unix-Machine-OSSystem

Operating System

Optional

String

This is the name of the host operating system of the UNIX asset that you want to create.

symc-csm-AssetSystem-Asset-Unix-Machine-OSVersionString

Operating System Version

Optional

String

This is the version of the operating system of the UNIX asset that you want to create.

HTTPS request parameters for MS SQL Server

Field name

Corresponding UI Label

Field type

Data type

Description

Type

On the console, in the Add Assets wizard, on the Select Creation Option screen, the Asset Type list

Mandatory

String

The value of this parameter must be symc-csm-AssetSystem-Asset-Dbif-server.

symc-csm-AssetSystem-Asset-Dbif-server-SQLServerDomainName

Domain/Workgroup Name

Mandatory

String

The value of this parameter must be the domain name of the MS SQL Server asset that you want to create.

symc-csm-AssetSystem-Asset-Dbif-server-hostName

Host Name (Node)

Mandatory

String

The value of this parameter must be the host name of the MS SQL Server asset that you want to create.

symc-csm-AssetSystem-Asset-Dbif-server-serverName

Server Name (Instance)

Mandatory

String

The value of this parameter must be the server name of the MS SQL Server asset that you want to create.

symc-csm-AssetSystem-Asset-Dbif-server-operatingSystem

Operating System

Optional

String

The value of this parameter must be the Windows operating system version of the MS SQL Server asset that you want to create; for example, 6.3 (14393)

symc-csm-AssetSystem-Asset-Dbif-server-platform

Platform

Optional

String

The value of this parameter must be the OS architecture details of the MS SQL Server asset; for example, NT x64.

symc-csm-AssetSystem-Asset-Dbif-server-productLevel

Product Level

Optional

String

The value of this parameter must be the product level of the MS SQL Server asset; for example, RTM.

symc-csm-AssetSystem-Asset-Dbif-server-productVersion

Product Version

Optional

String

The value of this parameter must be the product version of the MS SQL Server asset; for example, 14.0.1000.169.

symc-csm-AssetSystem-Asset-Dbif-server-versionString

Version String

Optional

String

The value of this parameter must be version string of the MS SQL Server Asset; for example, Microsoft SQL Server 2017 (RTM) - 14.0.1000.169 (X64) Aug 22 2017 17:04:49 Copyright © 2017 Microsoft Corporation Standard Edition (64-bit) on Windows Server 2016 Standard 10.0 <X64> (Build 14393: ) (Hypervisor)

HTTPS request parameters for Oracle database

Field name

Corresponding UI label

Field type

Data type

Description

Type

On the console, in the Add Assets wizard, on the Select Creation Option*screen, the *Asset Type list

Mandatory

String

The value of this parameter must be symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-NetBIOSName

Server NetBIOS Name

Mandatory

String

The value of this parameter must be the NetBIOS name of the Oracle database asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-DomainOrIP

Windows Domain Name or Unix IP Address

Mandatory

String

The value of this parameter must be the IP address of the Oracle database asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-servername

FQDN

Mandatory

String

The value of this parameter must be the server name of the Oracle database asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-dbname

Database Name

Mandatory

String

The value of this parameter must be the database name of the asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-dbversion

Database Version

Optional

String

The value of this parameter must be the database version of the asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-OSTYPE

OS Type

Optional

String

The value of this parameter must be the host operating system type of the database asset that you want to create.

symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-OSVERSION

Operating System Version

Optional

String

The value of this parameter must be the version of the operating system of the database asset that you want to create.

Note

You can create an Oracle asset by using the mandatory attributes listed in the HTTPS request parameters for Oracle database table. To execute data collection on Oracle assets, you must add the optional attributes listed in the same table.

2.1.6. Sample HTTPS request for Create Asset API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/assets

Content type

application/json

JSON body

[
{
        "Type" : "symc-csm-AssetSystem-Asset-Wnt-Machine",
        "symc-csm-AssetSystem-Asset-Wnt-Machine-HostName" : "TestWinAsset",
        "symc-csm-AssetSystem-Asset-Wnt-Machine-DomainWorkgroupName" : "TestDomain"
}
,{
        "Type" : "symc-csm-AssetSystem-Asset-Cisco-Router",
        "symc-csm-AssetSystem-Asset-Cisco-Router-IPAddress" : "10.211.11.11"
        }
        , {
        "Type" : "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-HOSTMACHINE" : "testredhatx86",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-IPAddress" : "10.211.88.11",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-InstancePortNumber" : "5704"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Unix-Machine",
        "symc-csm-AssetSystem-Asset-Unix-Machine-IPAddress" : "10.211.66.140"   ,
        "symc-csm-AssetSystem-Asset-Unix-Machine-HostMachine" : "rhel6"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Dbif-server",
        "symc-csm-AssetSystem-Asset-Dbif-server-SQLServerDomainName" : "TestDomain"   ,
        "symc-csm-AssetSystem-Asset-Dbif-server-hostName" : "MySQLHost" ,
        "symc-csm-AssetSystem-Asset-Dbif-server-serverName" : "TestSQLServerAsset"
        }
        ,{
        "Type" : "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers",
                                "container" : "Assets\\",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-HOSTMACHINE" : "AKwin2012r2",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-IPAddress" : "10.211.78.98",
        "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers-InstancePortNumber" : 5701
        }
]

2.1.7. Sample HTTPS response for Create Asset API

{
    "Total assets requested": 6,
    "Total assets created": 6,
    "Details of created assets": [
        {
            "RecordID": 1,
            "DisplayName": "TestDomain\\TestWinAsset",
            "Path": "Asset System",
            "ID": "c92f6f8a-8808-4c92-ac53-6390b75c57a0",
            "Type": "symc-csm-AssetSystem-Asset-Wnt-Machine"
        },
        {
            "RecordID": 2,
            "DisplayName": "10.211.11.11",
            "Path": "Asset System",
            "ID": "e3410909-19f6-49dc-a705-039a355ce8b2",
            "Type": "symc-csm-AssetSystem-Asset-Cisco-Router"
        },
        {
            "RecordID": 3,
            "DisplayName": "testredhatx86:10.211.88.11:5704",
            "Path": "Asset System",
            "ID": "38d28bab-fcb4-43cd-bcd7-4952e8b624f1",
            "Type": "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers"
        },
        {
            "RecordID": 4,
            "DisplayName": "rhel6:10.211.66.140",
            "Path": "Asset System",
            "ID": "c8c92c7c-5f0a-493c-af7c-abf7196a7130",
            "Type": "symc-csm-AssetSystem-Asset-Unix-Machine"
        },
        {
            "RecordID": 5,
            "DisplayName": "TestSQLServerAsset",
            "Path": "Asset System",
            "ID": "9c1c82e4-83dc-4fdf-84fa-7ae06d4b1f4e",
            "Type": "symc-csm-AssetSystem-Asset-Dbif-server"
        },
        {
            "RecordID": 6,
            "DisplayName": "AKwin2012r2:10.211.78.98:5701",
            "Path": "Asset System\\Assets",
            "ID": "9b5d217e-9b78-4ecb-a154-2d87bb206844",
            "Type": "symc-csm-AssetSystem-Asset-Unix-MySQL-Servers"
        }
    ],
    "Details of failed assets": []
}

2.1.8. HTTPS response codes for Create Asset API

Depending on the success or the failure of your API request, you see the following response codes for the Create Asset API:

Response Code

Response Type

Description

201

Created

This response is returned in one of the following situations:

  • All the specified assets are created.

  • Some of the specified assets are created (partial asset creation).

200

(with Total Count: 0 in response body)

OK

The request is successfully completed. The total count of assets created in this case is zero.

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)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

2.1.9. Sample Python script for Create Asset API

Refer to the sample python script, which is available at the following GitHub location:

2.2. Search Assets

Use this API to retrieve the list of assets (What is an asset?) in the Control Compliance Suite 12.5 asset system.

2.2.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

2.2.2. Authorization requirements

To use the Search Assets API, you must have permissions to execute the following Control Compliance Suite tasks:

  • View Assets

To use the Search Assets API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

2.2.3. Request method

To retrieve the list of Control Compliance Suite assets in your environment, create a GET request.

2.2.4. HTTPS request components for Search Assets API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/
Assets?Attributes=Attrname1 OP value1, Attrname2 OP value2,
AttrnameN OP valueN)&
ContainerPath=<Asset system path value>&SearchSubTree=<True/False>&
page=X&pagesize=Y
Note

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

2.2.5. HTTPS request parameters for Search Assets API

The following table contains the description of the HTTPS request parameters for the Search Assets API:

Field name

Field type

Data type

Description

Attributes

Mandatory

String

This is a comma-separated list of asset attributes and their respective values that are joined by an operator. The ‘OP’ placeholder in the HTTPS request components for Search Assets API section indicates a query operator, which can be any of the following:

  • =

  • EqualTo

  • Contains

  • StartsWith

  • EndsWith

All these query operators are case-sensitive.

Comma in the list of attributes is treated as 'AND'.

Wildcard character asterisk (*) is supported in values to be specified.

The Search Asset API returns a list of assets along with their total count.

ContainerPath

Optional

String

This is the folder in which the search operation is executed. The default value of this parameter is Asset System, which is the default root folder in the Control Compliance Suite asset hierarchy.

SearchSubtree

Optional

Boolean

By using this parameter, you can decide whether to search for the assets in the sub-folders recursively. The default value of this parameter is ‘True’.

Page

Optional

Integer

Considering that the Search Assets API can return huge data depending on the number of assets in your asset 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.

2.2.6. Commonly used attributes in HTTPS request for Search Assets API

The following are some attributes that are commonly used in an HTTPS request for the Search Assets API. These attributes vary depending on the platform. For description of these attributes, HTTPS request parameters for Create Asset API

Platform

Supported attribute

Windows

  • DisplayName

  • symc-csm-AssetSystem-Asset-Wnt-Machine-DomainWorkgroupName

  • symc-csm-AssetSystem-Asset-Wnt-Machine-HostName

  • symc-csm-AssetSystem-Asset-Wnt-Machine-OSVersionType

  • symc-csm-AssetSystem-Asset-Wnt-Machine-OSMajorVersionNumber

  • symc-csm-AssetSystem-Asset-Wnt-Machine-OSMinorVersionNumber

UNIX

  • DisplayName

  • symc-csm-AssetSystem-Asset-Unix-Machine-HostMachine

  • symc-csm-AssetSystem-Asset-Unix-Machine-IPAddress

  • symc-csm-AssetSystem-Asset-Unix-Machine-OSDistributionField

  • symc-csm-AssetSystem-Asset-Unix-Machine-OSSystem

  • symc-csm-AssetSystem-Asset-Unix-Machine-OSVersionString

MS SQL Server

  • DisplayName

  • symc-csm-AssetSystem-Asset-Dbif-server-serverName

  • symc-csm-AssetSystem-Asset-Dbif-server-hostName

  • symc-csm-AssetSystem-Asset-Dbif-server-SQLServerDomainName

  • symc-csm-AssetSystem-Asset-Dbif-server-operatingSystem

  • symc-csm-AssetSystem-Asset-Dbif-server-platform

  • symc-csm-AssetSystem-Asset-Dbif-server-productLevel

  • symc-csm-AssetSystem-Asset-Dbif-server-productVersion

  • symc-csm-AssetSystem-Asset-Dbif-server-versionString

Oracle Server

  • DisplayName

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-NetBIOSName

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-DomainOrIP

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-servername

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-dbname

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-dbversion

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-OSTYPE

  • symc-csm-AssetSystem-Asset-ORCL-CONFIGUREDDATABASES-OSVERSION

2.2.7. Response body for Search Assets API

The GET request for the Search Assets API returns the response body in the following structure:

Success Response:
{
"TotalCount": Int,
"TotalPages": Int,
"PrevPageUrl": String,
"NextPageUrl":String,
"assetDataList":
  [
  {
     "DisplayName":    String,
     "Path": String,
     "Id": String,
     "Type": String
 }
]
}

2.2.8. Sample HTTPS request for Search Assets API

The following is a sample HTTPS request for your reference. We have used DisplayName as the attribute in the sample:

Request component

Value

URL

GET https://<hostname>:<port number>/ccs/api/v1/Assets?attributes=(displayName = <Test_asset>)&
ContainerPath=Asset system&SearchSubTree=True&page=0&pagesize=100

Content type

application/json

2.2.9. Sample HTTPS response for Search Assets API

The sample HTTPS request that you created earlier returns the following response:

{"TotalCount":1,
"TotalPages":1,
"PrevPageUrl":"",
"NextPageUrl":"",
"assetDataList":[{"DisplayName":"<display name>","Path":"Asset System","Id":"9c135703-b76e-4eff-bfe2-8959d7ca4148",
"Type":"symc-csm-AssetSystem-Asset-Wnt-Machine"}]}

2.2.10. HTTPS response codes for Search Assets API

Depending on the success or the failure of your API request, you see the following response codes for the Search Assets API:

Response Code

Response Type

Description

200

OK

The list of assets is available with the following asset details:

  • Total count of assets

  • Total pages

  • Previous page URL

  • Next page URL

  • Asset details

  • Asset details include the following information:

  • Display name

  • Path

  • ID

  • Type

200

(with Total Count: 0 in response body)

OK

The request is completed successfully. However, there are no records matching the request parameters. In this case, the following response is returned. The total count of assets in this case is zero:

{
    "TotalCount": 0,
    "TotalPages": 0,
    "PrevPageUrl": "",
    "NextPageUrl": "",
    "assetDataList": []
}

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 access token or an expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

2.2.11. Sample Python script for Search Assets API

Refer to the sample python script, which is available at the following GitHub location:

2.3. Get Asset Details by ID

Use this API to retrieve the details of an asset (What is an asset?) in the Control Compliance Suite 12.5 asset system. Provide asset GUID in input request to retrieve the asset details.

2.3.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

2.3.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Get Asset Details by ID API:

  • View Assets

To use the Get Asset Details by ID API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

2.3.3. Request method

To retrieve the details of a Control Compliance Suite asset in your environment, create a GET request.

2.3.4. HTTPS request components for Get Asset Details by ID API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Assets/{AssetID}
Note

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

2.3.5. HTTPS request parameters for Get Asset Details by ID API

The following table contains the description of the HTTPS request parameter for the Get Asset Details by ID API:

Field name

Field type

Data type

Description

AssetID

Mandatory

GUID

This is the unique identifier of the asset of which you want to retrieve the details.

2.3.6. Response body for Get Asset Details by ID API

The GET request for the Get Asset Details by ID API returns the response body in the following structure:

Success Response:
{

"DisplayName":

"ID":

"Type':

"Path":

"Attributes":

[{...}]

"symc-csm-AssetSystem-Asset-AssetBase-EvaluatedComplianceScores":

" symc-csm-AssetSystem-Asset-AssetBase-EvaluatedRiskScores":

"symc-csm-AssetSystem-Asset-AssetBase-MaxRiskScores":

}
Note

The Get Asset Details by ID API returns scores only if all the score properties are non-zero. If these properties are equal to zero, the API returns score properties with NA.

2.3.7. Sample HTTPS request for Get Asset Details by ID API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Assets/B9BE1CC2-BC95-4077-BFF1-A68DADF0B3EF

Content type

application/json

2.3.8. Sample HTTPS response for Get Asset Details by ID API

The sample HTTPS request that you created earlier returns the following response:

{
"DisplayName":"<Domain name>\\<IP Address>",
"ID":"b9be1cc2-bc95-4077-bff1-a68dadf0b3ef",
"Path":"Asset System\\Windows",
"Type":{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine","DisplayName":"Windows Machine","Description":null},
"Attributes":[{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-DomainWorkgroupName","Value":"ccsdev","Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-HostName","Value":"10.211.105.169","Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-OSMajorVersionNumber","Value":6,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-OSMinorVersionNumber","Value":3,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-OSVersionType","Value":"Windows Server 2012 R2","Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-Server","Value":true,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-BDC","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-PDC","Value":false,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-HostMachineInDomain","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-HostNameDNS","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-TCPIPAddresses","Value":null,"Values":[],"IsMultiValued":true},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-SHAREPOINTVERSION","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-IISVERSION","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-VMWAREVCENTERSERVER","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-Wnt-Machine-APACHETOMCATSEREVR","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"displayName","Value":"ccsdev\\10.211.105.169","Values":null,"IsMultiValued":false},
{"Name":"whenCreated","Value":"2018-02-13T06:25:11","Values":null,"IsMultiValued":false},
{"Name":"whenChanged","Value":"2018-06-19T10:22:08","Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Confidentiality","Value":0,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Integrity","Value":0,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Availability","Value":0,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Custodian","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Department","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Location","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Owner","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Site","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-SourceID","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AssetSystem-Asset-AssetBase-Source","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AS-CA-AF-341aa8ae-4b84-4ac9-b089-9a63413e1071","Value":null,"Values":null,"IsMultiValued":false},
{"Name":"symc-csm-AS-CA-AF-059021f9-e2e0-4a4f-ba2e-5fe8be03be43","Value":null,"Values":null,"IsMultiValued":false}],
"symc-csm-AssetSystem-Asset-AssetBase-EvaluatedComplianceScores":"100",
"symc-csm-AssetSystem-Asset-AssetBase-EvaluatedRiskScores":"0",
ymc-csm-AssetSystem-Asset-AssetBase-MaxRiskScores":"0"}

2.3.9. HTTPS response codes for Get Asset Details by ID API

Depending on the success or the failure of your API request, you see the following response codes for the Get Asset Details by ID API:

Response Code

Response Type

Description

200

OK

The following asset details are retrieved:

  • Display name

  • ID

  • Type

  • Path

  • Attributes

  • symc-csm-AssetSystem-Asset-AssetBase-EvaluatedComplianceScores

  • symc-csm-AssetSystem-Asset-AssetBase-EvaluatedRiskScores

  • symc-csm-AssetSystem-Asset-AssetBase-MaxRiskScores

403

Forbidden

The following error message is displayed:

You are not authorized to perform this operation. Access is denied.

404

Not Found

If the user has the View Assets permissions but does not have rights to view the asset for which details are retrieved, or if the specified asset does not exist in the Control Compliance Suite asset system, the following error message is displayed:

The asset details could not be obtained completely. This may be because you do not
have sufficient permissions on all the assets,
the assets are already deleted from the Directory Server,
or the asset with the specified GUID does not exist.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Asset ID is either null or invalid.

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.

2.3.10. Sample Python script for Get Asset Details by ID API

Refer to the sample python script, which is available at the following GitHub location:

2.4. Delete Asset

Use this API to delete an asset or a list of assets from the Control Compliance Suite asset system.

2.4.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

2.4.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Delete Asset API:

  • View assets

  • Manage assets and asset groups

To use the Delete Asset API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

2.4.3. Request method

To delete an asset, create a DELETE request.

2.4.4. HTTPS request components for Delete Asset API

Create a DELETE request by using any of the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/assets
Note

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

[

"<Asset GUID>",

"<Asset GUID>",

"<Asset GUID>",

"<Asset GUID>",

"<Asset GUID>",

]

2.4.5. HTTPS request parameters for Delete Asset API

The <JSONBody> request field must contain an array of asset GUIDs as shown in the Sample HTTPS request for Delete Asset API

2.4.6. Sample HTTPS request for Delete Asset API

The following is sample HTTPS request for your reference:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/assets

Content type

application/json

JSON body

[

                "db7a5e44-adc0-4664-b471-f651dfda8d7c",

                "3cbf536a-9cad-4b4f-b23b-9525beb39f6a",

                "d13e3aec-a594-4235-ae7d-51f0efb0ab99",

                "69b37500-e81f-45fb-8d44-38fbdc5013ed",

                "1310e2ad-df2a-4faa-afc1-bcb9e77b36ce",

                "e140c904-d192-4c70-a291-51066dcae8b2",

                "a6d8d3d7-44e2-4446-b8ed-5919acbab3d2",

                "0918bc28-5c7e-44bb-964d-027836b749ad"
]

2.4.7. Response body for Delete Asset API

The DELETE request for the Delete Asset API returns the response body in the following structure:

204 (No content)

2.4.8. Sample HTTPS response for Delete Asset API

The sample HTTPS request that you created earlier returns the following response:

204 (No content)

2.4.9. HTTPS response codes for Delete Asset API

Depending on the success or the failure of your API request, you see the following response codes for the Delete Asset API:

Response Code

Response Type

Description

204

No Content

All the specified assets are deleted. However, no content needs to be returned to client after the successful completion of the request.

200

OK

The request is successfully completed. However, either no assets are deleted or some of the assets are deleted.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Asset ID is invalid.

403

Forbidden

The following error message is displayed:

You are not authorized to perform this task. Access is denied.

404

NOT found

The asset ID that is specified in the request does not exist in the Control Compliance Suite system.

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.

2.4.10. Sample Python script for Delete Asset API

Refer to the sample python script, which is available at the following GitHub location:

3. APIs for Asset Group Service

3.1. Get All Assets by Asset Group ID

Use this API to retrieve the details of all the assets (What is an asset?) that belong to a specific asset group in the Control Compliance Suite 12.5 asset system. Provide asset group GUID in input request to retrieve the asset details.

3.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

3.1.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Get All Assets by Asset Group ID API:

  • View Assets

To use the Get All Assets by Asset Group ID API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

3.1.3. Request method

To retrieve the details of a Control Compliance Suite asset in an asset group, create a GET request.

3.1.4. HTTPS request components for Get All Assets by Asset Group ID API

Create a GET request by using the following components.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/AssetGroup/{AssetGroupID}/Assets?Page=X&Pagesize=Y
Note

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

3.1.5. HTTPS request parameters for Get All Assets by Asset Group ID API

The following table contains the description of the HTTPS request parameters for the Get All Assets by Asset Group API:

Field name

Field type

Data type

Description

AssetGroupID

Mandatory

GUID

This is the unique identifier of the asset group from which you want to retrieve the asset details.

Page

Optional

Integer

Considering that the Get All Assets by Asset Group ID can return huge data depending on the number of assets in an asset group, 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.

3.1.6. Response body for Get All Assets by Asset Group ID API

The GET request for the Get All Assets by Asset Group ID API returns the response body in the following structure:

Success Response:
{

TotalCount":Int,

"TotalPages":Int,

"PrevPageUrl":"URL",

"NextPageUrl":"URL",

"assetDataList":[{

"DispalyName": String

"ContainerPath":String,

"ID":Guid

"Type":String }, {..}

]

}

3.1.7. Sample HTTPS request for Get All Assets by Asset Group ID API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<host name>:<port number>/ccs/api/v1/AssetGroup/7C728AFF-3D9F-4727-B2DD-4343CBC0D232/Assets

Content type

application/json

3.1.8. Sample HTTPS response for Get All Assets by Asset Group ID API

The sample HTTPS request that you created earlier returns the following response:

{"TotalCount":4,"TotalPages":1,"PrevPageUrl":"","NextPageUrl":"",
"assetDataList":[{"DisplayName":"<domain name>\\<IP address>","ContainerPath":"Asset System\\Windows","Id":"17510f00-cc0e-437d-bd39-3122d2bb0688","Type":"symc-csm-AssetSystem-Asset-Wnt-Machine"},
{"DisplayName":"<domain name>\\<IP address>","ContainerPath":"Asset System\\Windows","Id":"1f5244db-f667-438f-b475-9fe39fb67c09","Type":"symc-csm-AssetSystem-Asset-Wnt-Machine"},
{"DisplayName":"t1\\t1","ContainerPath":"Asset System\\Windows","Id":"4421e1ec-63f9-42fa-a10d-a709eb58503e","Type":"symc-csm-AssetSystem-Asset-Wnt-Machine"},
{"DisplayName":"<domain name>\\<IP address>","ContainerPath":"Asset System\\Windows","Id":"b9be1cc2-bc95-4077-bff1-a68dadf0b3ef","Type":"symc-csm-AssetSystem-Asset-Wnt-Machine"}]}

3.1.9. HTTPS response codes for Get All Assets by Asset Group ID API

Depending on the success or the failure of your API request, you see the following response codes for the Get All Assets by Asset Group ID API:

Response Code

Response Type

Description

200

OK

The following details are retrieved:

  • Total count of assets

  • Total response pages

  • Previous page URL

  • Next page URL

  • Asset details

  • Asset details include the following information:

  • Display name

  • Type

  • Description

  • Owner

  • Modified by

  • Group type

  • Group ID

  • Container path

200

(with Total Count: 0 in response body)

OK

The request is completed successfully. However, there are no records matching the request parameters. In this case, the following response is returned. The total count of assets in this case is zero:

{
    "TotalCount": 0,
    "TotalPages": 0,
    "PrevPageUrl": "",
    "NextPageUrl": "",
    "assetDataList": []
}

403

Forbidden

The following error message is displayed:

You are not authorized to perform this operation. Access is denied.

404

Not Found

If the user does not have sufficient permissions on an asset group from which details are to be retrieved, or if the specified asset group does not exist in the Control Compliance Suite asset system, the following error message is displayed:

The group details could not be obtained completely. This may be because you do not
have sufficient permissions, the asset group is already deleted from the Directory Server,
or the asset group with the specified GUID does not exist.

401

Unauthorized

This may be because of an invalid access token or an expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Asset Group ID is either invalid or empty.

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.

3.1.10. Sample Python script for Get All Assets by Asset Group ID API

Refer to the sample python script, which is available at the following GitHub location:

3.2. Search Asset Group

Use this API to retrieve the list of asset groups (Asset Groups) in the Control Compliance Suite 12.5 asset system.

3.2.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

3.2.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Search Asset Group API:

  • View Assets

To use the Search Asset Group API, you must have permissions to access sub-folders in the Asset System folder. You may not require permissions on the entire asset system.

3.2.3. Request method

To retrieve the list of asset groups in your Control Compliance Suite environment, create a GET request.

3.2.4. HTTPS request components for Search Asset Group API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/
AssetGroup?Attributes=Attrname1 OP value1,
Attrname2 OP value2, ​AttrnameN OP valueN)​&ContainerPath=Asset system path value&
SearchSubTree=True\False
Note

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

3.2.5. HTTPS request parameters for Search Asset Group API

The following table contains the description of the HTTPS request parameters for the Search Asset Group API:

Field name

Filed type

Data type

Description

Attributes

Mandatory

String

This is a comma-separated list of asset attributes and their respective values joined by an operator. The ‘OP’ placeholder in the HTTPS request components for Search Asset Group API section indicates a query operator, which can be any of the following:

  • =

  • EqualTo

  • Contains

  • StartsWith

  • EndsWith

All these query operators are case-sensitive.

Comma used in the list of attributes is treated as 'AND.'

Wildcard character asterisk (*) is supported in values to be specified.

The Search Asset Group API returns a list of asset groups along with their total count.

The following are some attributes that are commonly used in an HTTPS request for the Search Asset Group API:

  • DisplayName

  • Symc-CSM-AssetSystem-AssetGroup-AssetTypes

  • Symc-CSM-AssetSystem-AssetGroup-Owner

  • Symc-CSM-AssetSystem-AssetGroup-Type

Container path

Optional

String

This is the folder in which the search operation is executed. The default value of this parameter is Asset System, which is the default root folder in the Control Compliance Suite asset hierarchy.

SearchSubtree

Optional

Boolean

By using this parameter, you can decide whether to search for the asset groups in the sub-folders recursively. The default value of this parameter is ‘True.’

3.2.6. Response body for Search Asset Group API

The GET request for the Search Asset Group API returns the response body in the following structure:

{

"TotalCount": {Int},
"AssetGroupType": {String},
"AssetGroup":

  [

  {
     "DisplayName": {String},

     "ID": {String},
 }

]

}

3.2.7. Sample HTTPS request for Search Asset Group API

The following is a sample HTTPS request for your reference. We have used display name of an asset group as an attribute in the sample:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/AssetGroup?attributes=
(displayname EqualTo All Windows Machines,symc-csm-AssetSystem-AssetGroup-Description Contains Windows)&
ContainerPath=asset system\unix&searchsubtree=false

Content type

application/json

3.2.8. Sample HTTPS response for Search Asset Group API

The sample HTTPS request that you created earlier returns the following response:

{"TotalCount":1,
"AssetGroupType":"symc-csm-AssetSystem-AssetGroup-Type",
"AssetGroups":[{"DisplayName":"All Windows Machines",
"Id":"8265ee65-8614-429b-bfc4-0da8224df09c"}]}

3.2.9. HTTPS response codes for Search Asset Group API

Depending on the success or the failure of your API request, you see the following response codes for the Search Asset Group API:

Response Code

Response Type

Description

200

OK

The list of asset groups with their total and asset group type is available. Asset group details include display names of asset groups and their IDs.

200

(with Total Count: 0 in response body)

OK

The request is completed successfully. However, there are no records matching the request parameters. In this case, the following response is returned. The total count of asset groups in this case is zero:

{
"TotalCount": 0,
"AssetGroupType": null,
"AssetGroup": [{}]
}

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:

Server could not understand the request due to invalid syntax.
Please check requested URL.
The parameter Attributes is null or Empty.
The parameter '#name' is invalid. The expression
'#expression' within is invalid.

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.

3.2.10. Sample Python script for Search Asset Group API

Refer to the sample python script, which is available at the following GitHub location:

3.3. Get Asset Group Details by Asset Group ID

Use this API to retrieve the details of an asset group in the Control Compliance Suite 12.5 asset system. Provide asset group GUID in input request to retrieve the asset group details.

3.3.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

3.3.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Get Asset Group Details by Asset Group ID API:

  • View Assets

You must have the permissions to access the following folders to use the Get Asset Group Details by Asset Group ID API:

  • Asset System

3.3.3. Request method

To retrieve the details of a Control Compliance Suite asset in your environment, create a GET request.

3.3.4. HTTPS request components for Get Asset Group Details by Asset Group ID API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/AssetGroup/{AssetGroupID}
Note

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

3.3.5. HTTPS request parameters for Get Asset Group Details by Asset Group ID API

The following table contains the description of the HTTPS request parameter for the Get Asset Group Details by Asset Group ID API:

Field name

Field type

Data type

Description

AssetGroupID

Mandatory

GUID

This is the unique identifier of the asset group of which you want to retrieve the details.

3.3.6. Response body for Get Asset Group Details by Asset Group ID API

The GET request for the Get Asset Group Details by Asset Group ID API returns the response body in the following structure:

Success Response:
{

"AssetGroupDetails": {

"symc-csm-AssetSystem-AssetGroup-AssetTypes:[..],

"DisplayName": {String}

"symc-csm-AssetSystem-AssetGroup-Description": {String}

"GroupID": {GUID}

"symc-csm-AssetSystem-AssetGroup-Type": {String}

"symc-csm-AssetSystem-ModifiedBy": {String}

"symc-csm-AssetSystem-AssetGroup-Owner": {String}

"ContainerPath": {String}

}

}

3.3.7. Sample HTTPS request for Get Asset Group Details by Asset Group ID API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/AssetGroup/018523a6-4771-41fb-90cb-df7ab3c23cda

Content type

application/json

3.3.8. Sample HTTPS response for Get Asset Group Details by Asset Group ID API

The sample HTTPS request that you created earlier returns the following response:

{
    "AssetGroupDetails": {
        "symc-csm-AssetSystem-AssetGroup-AssetTypes": [
            "symc-csm-AssetSystem-Asset-Unix-Machine"
        ],
        "DisplayName": "Custom Static AssetGroup",
        "symc-csm-AssetSystem-AssetGroup-Description": null,
        "GroupID": "018523a6-4771-41fb-90cb-df7ab3c23cda",
        "symc-csm-AssetSystem-AssetGroup-Type": "Static",
        "symc-csm-AssetSystem-ModifiedBy": "AUTOMATION\\administrator",
        "symc-csm-AssetSystem-AssetGroup-Owner": "AUTOMATION\\administrator",
        "ContainerPath": "Asset System"
    }
}

3.3.9. HTTPS response codes for Get Asset Group Details by Asset Group ID API

Depending on the success or the failure of your API request, you see the following response codes for the Search Assets API:

Response Code

Response Type

Description

200

OK

The following asset group details are retrieved:

  • Asset types

  • Asset group name

  • Description

  • Asset group ID

  • Asset group type

  • Modified by

  • Owner

  • Container path

403

Forbidden

The following error message is displayed:

You are not authorized to perform this operation. Access is denied.

404

Not Found

If the user has the View Assets permissions but does not have rights to view the asset for which details are retrieved, or if the specified asset does not exist in the Control Compliance Suite asset system, the following error message is displayed:

The asset group details could not be obtained completely. This may be because you do not
have sufficient permissions, or the asset group is already deleted from the Directory Server,
or the asset group with the specified GUID does not exist.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Asset group ID is either null or invalid.

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.

3.3.10. Sample Python script for Get Asset Group Details by Asset Group ID API

import requests
from requests.packages.urllib3.exceptions import InsecureRequestWarning
def getToken():
	urlToken = "https://<host name>:<port number>/ccs/api/v1/oauth/tokens"

	payload = "grant_type=password&username=<domain name>\\<user name>&password=<password>"
	headers = {
    	'Content-Type': "application/json",
    }

	responseToken = requests.request("POST", urlToken, data=payload, headers=headers, verify=False)

	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

url = "https://<host name>:<port number>/ccs/api/v1/AssetGroup/91537a11-da0a-4517-93c0-fa7a2e6c6e39"

requests.packages.urllib3.disable_warnings(InsecureRequestWarning)

bearertoken = "Bearer " + getToken()
#print("\n Bearer Token is:\n")
#print(bearertoken + "\n")

headers = {
    'Authorization': bearertoken,
    'Content-Type': "application/json"
    }

response = requests.request("GET", url, headers=headers, verify=False)

print(response.text)
print(response.json)

4. APIs for Standard Service

4.1. Search Standards

Use this API to retrieve the list of standards (See About the Technical Standards workspace) in the Control Compliance Suite 12.5 Standards Manager.

4.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

4.1.2. Authorization requirements

You must have the permission to execute the following Control Compliance Suite tasks to use the Search Standards API:

  • View standards

To use the Search Standards API, you must have permissions to access sub-folders in the Standards folder. You may not require permissions on the entire Standards hierarchy.

4.1.3. Request method

To retrieve the list of standards in the Control Compliance Suite Standards Manager, create a GET request.

4.1.4. HTTPS request components for Search Standards API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/
Standards?Attributes=Attrname1 OP value1, Attrname2 OP value2,
AttrnameN OP valueN)&
ContainerPath=<Container path value>&SearchSubTree=<True/False>
Note

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

4.1.5. HTTPS request parameters for Search Standards API

The following table contains the description of the HTTPS request parameters for the Search Standards API:

Field name

Field type

Data type

Description

Attributes

Mandatory

String

This is a comma-separated list of standard attributes and their respective values joined by an operator. The ‘OP’ placeholder in the HTTPS request components for Search Standards API section indicates a query operator, which can be any of the following:

  • =

  • EqualTo

  • Contains

  • StartsWith

  • EndsWith

All these query operators are case-sensitive.

Comma used in the list of attributes is treated as 'AND.'

Wildcard character asterisk (*) is supported in values to be specified.

The Search Standards API returns a list of standards along with their total count.

The following attributes are supported for this parameter:

  • DisplayName

  • Symc-Standard-Author

  • Symc-Standard-TargetTypeIDs

Note

These attribute names are not case-sensitive.

Container path

Optional

String

This is the folder in which the search operation is executed. The default value of this parameter is Standards, which is the default root folder in the Control Compliance Suite standards hierarchy.

SearchSubtree

Optional

Boolean

By using this parameter, you can decide whether to search for the assets in the sub-folders recursively. The default value of this parameter is ‘True.’

4.1.6. Response body for Search Standards API

The GET request for the Search Standards API returns the response body in the following structure:

Success Response:
[
{

TotalCount:{Int},

StandardDetails":[

{

"ID": {String},
"Name":{String},
"Version": {String},
"Author":{String},
"TargetTypes":[Array],
"CreationDate":{Date},
"ModifiedDate":{Date},
"IsPredefined":{Boolean}

}..


]
Note

The dates that are returned in the response are in UTC format.

4.1.7. Sample HTTPS request for Search Standards API

The following is a sample HTTPS request for your reference. We have used asset display name as an attribute in the sample:

GET https://<hostname>:<port number>/ccs/api/v1/Standards?searchCriteria=displayname=std&container=standards&Searchsubtree=true

4.1.8. Sample HTTPS response for Search Standards API

The sample HTTPS request that you created earlier returns the following response:

{"TotalCount":2,"StandardDetails":[{"ID":"c983af4c-eb09-48bd-96af-ca170a12f373","Name":"std","Version":"1.3.0",
"Author":"<domain name>\\<user name>","CreationDate":"2018-07-30T09:14:50","ModifiedDate":"2018-07-30T09:15:18","IsPredefined":false},
{"ID":"ed237ad3-c07c-42a3-abfb-dede5820a48b","Name":"std","Version":"1.0.0","Author":"<domain name>\\<user name>",
"CreationDate":"2018-09-25T13:37:34","ModifiedDate":"2018-09-25T13:37:34","IsPredefined":false}]}

4.1.9. HTTPS response codes for Search Standards API

Depending on the success or the failure of your API request, you see the following response codes for the Search Standards API:

Response Code

Response Type

Description

200

OK

The list of standards is available with the following details:

  • Total count of standards

  • Standard details

  • Standard details include the following information:

  • Standard GUID

  • Name of the standard

  • Version of the standard

  • Author of the standard

  • Whether the standard is predefined or custom

  • Date when the standard was created

  • Date when the standard was last modified

200

(with Total Count: 0 in response body)

OK

The request is completed successfully. However, there are no records matching the request parameters. In this case, the following response is returned. The total count of standards in this case is zero:

{

TotalCount:int,

StandardDetails":[{}]
}

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)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

4.1.10. Sample Python script for Search Standards API

Refer to the sample python script, which is available at the following GitHub location:

4.2. Delete Standards

Use this API to delete a specified standard or a list of standards from the Control Compliance Suite system. You can delete up to 10 standards per request.

4.2.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

4.2.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Delete Standards API:

  • View standards

  • Manage Standards

To use the Delete Standards API, you must have permissions to access sub-folders in the Standards folder. You may not require permissions on the entire Standards hierarchy.

4.2.3. Request method

To delete a standard, create a DELETE request.

4.2.4. HTTPS request components for Delete Standards API

Create a DELETE request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Standards
Note

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

 '{"StandardList":[{"Type":"ID","Standards":["<standard GUID>",
"<standard GUID>","<standard GUID>"]},
{"Type":"Name","Standards":["<Name of the standard>"]}],
"ContainerPath":"<Container path value>","DeleteFromSubfolder":"Ture/False","DeletePredefinedStandard":"True/False"}'

4.2.5. HTTPS request parameters for Delete Standards API

The following table contains the description of the HTTPS request parameters for the Delete Standards API. You must use these parameters in the StandardList array as displayed in HTTPS request components for Delete Standards API

Field name

Field type

Data type

Description

Type

Mandatory

String

These are the ways by which you want to list standards that you want to delete. The following types of standard lists are supported:

  • ID

  • If you use this field in the request, the Standards field must contain the GUIDs of the standards that you want to delete.

    *
  • Name

  • If you use this field in the request, the Standards field must contain the exact names of the standards that you want to delete.

    *

These types are not case sensitive. You can use either of or both these types in an input request.

Standards

Mandatory

GUID (if you use ID as the StandardList type)

String (if you use Name as the StandardList type)

Depending on the StandardList type, this field contains GUIDs or names of the standards that you want to delete.

ContainerPath

Optional

String

This is the folder in which the delete operation is executed. The default value of this parameter is Standards, which is the default root folder in the Control Compliance Suite standards hierarchy.

DeleteFromSubfolder

Optional

String

By using this parameter, you can decide whether to delete a standard from a subfolder in your standard. The default value of this parameter is 'False'.

DeletePredefinedStandard

Optional

String

By using this parameter, you can decide whether to a predefined standard. The default value of this parameter is 'False'.

4.2.6. Sample HTTPS request for Delete Standards API

The following is a sample HTTPS request for your reference:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Standards

Content type

application/json

JSON body

'{"StandardList":[{"Type":"ID","Standards":["54E94600-F4B0-415D-8AD0-07D99FB82808",
"F8E09999-F40B-4CA9-9C8C-160DDA0DF88D","D9944B0A-2EB9-4D15-A66F-6BC855D3593F"]},
{"Type":"Name","Standards":["Copy of File Names Standard"]}],
"ContainerPath":"standards\\std","DeleteFromSubfolder":"False","DeletePredefinedStandard":"False"}'

4.2.7. Response body for Delete Standards API

The DELETE request for the Delete Standards API returns the response body in the following structure:

{

"StandardsNotFound":[..,..,

"Remark: These standards could not be deleted because of one of the following reasons: 1. Insufficient permissions 2. Invalid ID or name 3. Invalid container path."]

"PredefinedStandards":[..,..,

"Remark: To delete a predefined standard, set the 'DeletePredefinedStandard' field to True in the JSON input.]

}

4.2.8. Sample HTTPS response for Delete Standards API

The sample HTTPS request that you created earlier returns the following response:

OK
{"PredefinedStandards":{"d9944b0a-2eb9-4d15-a66f-6bc855d3593f":"Security Essentials for Apache Tomcat Server 5.x - 8.x",
"Remark":"To delete a predefined standard, set the 'DeletePredefinedStandard' field to True in the JSON input."},
"StandardsNotFound":["Copy of File Names Standard","54E94600-F4B0-415D-8AD0-07D99FB82808","F8E09999-F40B-4CA9-9C8C-160DDA0DF88D",
"Remark: These standards could not be deleted because of one of the following reasons:
1. Insufficient permissions 2. Invalid ID or name 3. Invalid container path"]}

4.2.9. HTTPS response codes for Delete Standards API

Depending on the success or the failure of your API request, you see the following response codes for the Delete Standards API:

Response Code

Response Type

Description

200

OK

The request is successfully completed. The list of standards that are not found during the execution of the DELETE operation is displayed along with the following remark.

{

"StandardsNotFound":[..,..,

"Remark: These standards could not be deleted because of one of the following reasons:
1. Insufficient permissions 2. Invalid ID or name 3. Invalid container path."]

If you add a predefined standard in the StandardList parameter, and if the value of the DeletePredefinedStandard parameter is False, it is displayed in the PredefinedStandards list along with the following remark:

"PredefinedStandards":[..,..,

"Remark: To delete a predefined standard, set the 'DeletePredefinedStandard' field to True in the JSON input.]

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Server could not understand the request due to invalid syntax.

403

Forbidden

This may be because the identified user does not have proper authorization to delete a standard in Control Compliance Suite.

404

NOT found

The standard ID that is specified in the request does not exist in the Control Compliance Suite system.

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.

4.2.10. Sample Python script for Delete Standards API

Refer to the sample python script, which is available at the following GitHub location:

5. APIs for Job Service

5.1. 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. (See About Jobs)

You can create the following jobs with this API:

  • Collection-Evaluation Job

  • Data Collection Job

  • Evaluation Job

5.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.1.2. Authorization requirements

You must have the permissions to execute the following Control Compliance Suite tasks to use the Create Job API:

  • View standards

  • View assets

  • Manage jobs

  • Collect data

  • Evaluate standards

  • View evaluation results

You must have the permissions to access the following folders to use the Create Job API:

  • Asset System

  • Standards

5.1.3. Request method

To create a job by using a technical standard, create a POST request.

5.1.4. HTTPS request components for Create Job API

Create a POST request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/
Note

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"],
"AssetTimeOut": "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": "STRING",
"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"
}

},

"JobType": "Job Type"
}'

5.1.5. 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:

  • CollectionEvaluationJob

  • CollectionJob

  • EvaluationJob

These JobType values are case-sensitive.

JobDescription

Optional

String

This is the description of the job that you want to create.

SuccessNotification

Mandatory (if the value of the ShouldSendSuccess​Notification field is set to True)

Optional (if the value of the ShouldSendSuccess​Notification 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

See the Notification fields table.

FailureNotification

Mandatory (if the value of the ShouldSendFailure​Notification field is set to True)

Optional (if the value of the ShouldSendFailure​Notification 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

See the Notification fields table.

ShouldSendSuccess​Notification

Optional

Boolean

The True or False value of this field denotes whether you want to enable notifications for job success.

ShouldSendFailure​Notification

Optional

Boolean

The True or False value of this field denotes whether you want to enable notifications for job failure.

ShouldSynchronize​Results

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.

Note

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: * 1

  • Indicates Sunday.

  • 2

  • Indicates Monday.

  • 4

  • Indicates Tuesday.

  • 8

  • Indicates Wednesday.

  • 16

  • Indicates Thursday.

  • 32

  • Indicates Friday.

  • 64

  • Indicates Saturday.

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: * 1

  • Indicates First week of the month.

  • 2

  • Indicates Second week of the month.

  • 4

  • Indicates Third week of the month.

  • 8

  • Indicates Fourth week of the month.

  • 16

  • Indicates Last week of the month.

In the Every list, if you select the Week option, you see the drop-down list to select a week.

Note

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: * 1

  • Indicates Daily recurrence, which means you schedule a job to recur every day.

  • 2

  • Indicates Weekly recurrence, which means you schedule a job to recur once a week.

  • 3

  • Indicates Monthly recurrence, which means you schedule a job to recur once a month.

  • Daily

  • Weekly

  • Monthly

Note

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

Note

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: * RunOnce

  • RunEveryNDays

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: * Set the value of the RunOnce parameter to True. Then, the job is run only once on the start date.

  • Set the value of the RunEveryNDays parameter to True. Then, the job is repeated after every <RepeatDays> starting from the specified StartDate.

Start Date

WeeklyDay

Optional

Integer

The following are the possible values for the DayOfWeek enumeration: * 0

  • Indicates Sunday.

  • 1

  • Indicates Monday.

  • 2

  • Indicates Tuesday.

  • 3

  • Indicates Wednesday.

  • 4

  • Indicates Thursday.

  • 5

  • Indicates Friday.

  • 6

  • Indicates Saturday.

Weekday grid below the Run every <number> Weeks list

Note

On 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

Note

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 ShouldSendSuccess​Notification field and/or ShouldSendFailure​Notification field is set to True)

Optional (if the value of the ShouldSendSuccess​Notification field and/or ShouldSendFailure​Notification 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

5.1.6. Response body for Create Job API

The POST request for the Create Job API returns the response body in the following structure:

{

"JobID": {GUID}

}

5.1.7. Sample HTTPS request for Create Job API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/
Note

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": "5ed919fd-9f70-429a-bd36-f22bcbbe8fa4",
"Type": "symc-csm-AssetSystem-Asset-Wnt-Machine"}],
"JobDescription": "Demo CER Job","JobName": "A9_REST",
"Standards": ["efad0d29-b20b-45a2-a2b1-214f69826d5c"],
"AssetTimeOut": 60,
"FailureNotification":{"FromEmailAddress":"EMailID",
"Subject":"Collection-Evaluation-Reporting job failed",
"ToEmailAddress":"EMailID",
"Body":"Failure notification message"},
"SuccessNotification":{"FromEmailAddress":"EMailID",
"Subject":"Collection-Evaluation-Reporting job completed successfully",
"ToEmailAddress":"EMailID","Body":"Sucess 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": false,"RunPeriodically": true,"StartDate": "2018-11-18T02:14:27.5120788-08:00",
"WeeklyDay": 0, "WeeklyRecurEvery": 0}},"JobType":"EvaluationJob"}

5.1.8. Sample HTTPS response for Create Job API

{"JobID":"5ade67f0-0c93-49f3-9f2b-b8ec4beaa99c"}

5.1.9. 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:

Invalid input data. Either JobType or JobDetails is
null.
Invalid type.
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.
Encountered an error while parsing json input.
Please validate the JSON input.

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.

5.1.10. Sample Python script for Create Job API

Refer to the sample python script, which is available at the following GitHub location:

5.2. Job Operation

Use this API to perform any of the following job operations:

  • Executing a job immediately

  • Stopping a running job

5.2.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.2.2. Authorization requirements

You must permissions to execute the following Control Compliance Suite tasks to use the Job Operation API:

  • Manage jobs

  • Collect data

  • View all jobs

  • View assets

  • View standards

  • View evaluation results

  • Evaluate standards

You must have the permissions to access the following folders to use the Job Operation API:

  • Asset System

  • Standards

5.2.3. Request method

To use the Job Operation API, create a POST request.

5.2.4. HTTPS request components for Job Operation API

To execute job operations, create a POST request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/<JobID/JobRunID>
Note

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

'{"Operation":"<Execute/Abort>"}'

5.2.5. HTTPS request parameters for Job Operation API

The following table contains the description of the HTTPS request parameters for the Job Operation API:

Field name

Field type

Data type

Description

JobID (for executing a job immediately)

Mandatory

GUID

This is the unique identifier of the job that you want to execute.

JobRunID (for stopping a running job)

Mandatory

GUID

This is the unique identifier of the job run that you want to cancel.

Operation Type

Mandatory

String

The following values are supported for this field:

  • Execute

  • Abort

These values are not case-sensitive.

5.2.6. Response body for Job Operation API

The POST request for the Job Operation API returns the response body in the following structure:

For Execute Job Operation

{

"JobStatusInfo":

{"JobRunID":{GUID},
"JobID": {GUID},
"CustomStatusText": {String}
"Exception": {String}
"JobStartTime": {DateTime},
"JobEndTime": {DateTime},
"JobSummary": {String},
"Status": {Int},
"ActivityStatusList":[Array]

}

}

For Abort Job Operation

204 (No content)

5.2.7. Job status codes and their meanings

In response to the Execute Job Operation API, job information is returned along with job status code. The following table lists the respective meanings of each job status code:

Job status code

Meaning

0

None

1

Pending

2

Executing

3

Idle

4

Completed

5

Faulted

6

Custom

7

Aborted

<< Sample HTTPS response for Job Operation API>>

5.2.8. Sample HTTPS request for Job Operation API

The following are the sample HTTPS requests for your reference both for Execute Job Operation and Abort Job Operation:

For Execute Job Operation

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/
24f58e54-5d94-45f8-97a8-ccb6d959233a

Content type

application/json

JSON body

'{"Operation":"Execute"}'

For Abort Job Operation

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/
24f58e54-5d94-45f8-97a8-ccb6d959233a

Content type

application/json

JSON body

'{"Operation":"Abort"}'

5.2.9. Sample HTTPS response for Job Operation API

The sample HTTPS request that you created earlier returns the following response:

For Execute Job Operation

{"JobRunID":"4f7415b1-303d-42cd-8b61-485485a1cb9c",
"JobID":"24f58e54-5d94-45f8-97a8-ccb6d959233a",
"CustomStatusText":"","Exception":null,
"JobStartTime":"2018-09-14T13:07:24.3474193Z",
"JobEndTime":"0001-01-01T00:00:00",
"JobSummary":null,"Status":2,
"ActivityStatusList":[]}

For Abort Job Operation

204 (No Content)

5.2.10. HTTPS response codes for Job Operation API

Depending on the success or the failure of your API request, you see the following response codes for the Job Operation API:

Response Code

Response Type

Description

200

OK

The request is successfully completed.

The following job execution details are returned:

  • Unique identifier of a job run

  • Unique identifier of a job

  • Custom status text

  • Exception received at the start of the job execution

  • Start time of job execution

  • End time of job execution

  • Job summary

  • Job status

  • List of activity statuses

204

No content

The request is successfully completed. However, there is no content to return.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

403

Forbidden

The following error message is displayed:

You are not authorized to perform this task. Access is denied.

400

Bad Request

(Client Error)

One of the following error messages is displayed:

Job is not found or User is not authorized to run the job.
Invalid input data. Either ID or operation is null.
Could not cancel the specified job
- either the job has already finished executing or
an invalid job instance ID was specified
Requested job operation '#job type'  is not supported.

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.

5.2.11. Sample Python script for Job Operation API

Refer to the sample python script, which is available at the following GitHub location:

5.3. 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. (See About Jobs)

You can update the following jobs with this API:
  • Collection-Evaluation Job

  • Data Collection Job

  • Evaluation Job

5.3.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.3.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Update Job API:

  • View standards

  • View assets

  • Manage jobs

  • Collect data

  • Evaluate standards

  • View evaluation results

You must have the permissions to access the following folders to use the Update Job API:

  • Asset System

  • Standards

5.3.3. Request method

To update a Collection-Evaluation job, a Data Collection job, or an Evaluation job, create a PATCH request.

5.3.4. HTTPS request components for Update Job API

Create a PATCH request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/
Note

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"],
"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"
}

5.3.5. 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:

  • CollectionEvaluationJob

  • DataCollectionJob

  • EvaluationJob

JobDescription

Optional

String

This is the description of the job that you want to update.

SuccessNotification

Mandatory (if the value of the ShouldSendSuccess​Notification field is set to True)

Optional (if the value of the ShouldSendSuccess​Notification 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 ShouldSendFailure​Notification field is set to True)

Optional (if the value of the ShouldSendFailure​Notification 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

ShouldSendSuccess​Notification

Optional

Boolean

The True or False value of this field denotes whether you want to enable notifications for job success.

ShouldSendFailure​Notification

Optional

Boolean

The True or False value of this field denotes whether you want to enable notifications for job failure.

ShouldSynchronize​Results

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 ShouldSendSuccess​Notification field and/or ShouldSendFailure​Notification field is set to True)

Optional (if the value of the ShouldSendSuccess​Notification field and/or ShouldSendFailure​Notification 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

5.3.6. 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)

5.3.7. 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"}
Note

Depending on the input parameters that you provide in this request, the data in the job definition is replaced.

5.3.8. Sample HTTPS response for Update Job API

204 (No content)

5.3.9. 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:

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.

5.3.10. Sample Python script for Update Job API

Refer to the sample python script, which is available at the following GitHub location:

5.4. Delete Job

Use this API to delete a specified job and the associated job data from the SQL store or from the Control Compliance Suite directory.

5.4.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.4.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Delete Job API:

  • View standards

  • Manage jobs

  • Collect data

  • Evaluate standards

  • View evaluation results

You must have the permissions to access the following folders to use the Delete Job API:

  • Asset System

  • Standards

Note

Only a CCS user who creates a job can delete that job.

5.4.3. Request method

To delete a job, create a DELETE request.

5.4.4. HTTPS request components for Delete Job API

Create a DELETE request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Jobs?jobid={jobid}&
DeleteJob={True/False}
Note

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

5.4.5. HTTPS request parameters for Delete Job API

The following table contains the description of the HTTPS request parameters for the Delete Job API:

Field name

Field type

Data type

Description

JobID

Mandatory

GUID

This is the unique identifier of the job that you want to delete.

DeleteJob

Optional

Boolean

Set the value of this parameter to True if you want to delete the job permanently from the Control Compliance Suite directory.

Set the value of this parameter to False if you do not want to delete the job from the Control Compliance Suite directory. In this case, the historical data related to the job is deleted from the SQL store but the job is available for future job runs.

The default value of this parameter is True.

5.4.6. Sample HTTPS request for Delete Job API

The following is a sample HTTPS request for your reference:

Request component

Value

URL

https://<host name>:<port number>/ccs/api/v1/
Jobs?jobid=754F7C7E-884A-4420-AF72-1FED35D3EFC1&DeleteJob=False

Content type

application/json

5.4.7. Response body for Delete Job API

The DELETE request for the Delete Job API returns the response body in the following structure:

204 (No content)

5.4.8. Sample HTTPS response for Delete Job API

The sample HTTPS request that you created earlier returns the following response:

204 (No content)

5.4.9. HTTPS response codes for Delete Job API

Depending on the success or the failure of your API request, you see the following response codes for the Delete Job API:

Response Code

Response Type

Description

204

No content

The request is successfully completed and all the specified jobs are deleted. However, no content needs to be returned to client

200

OK

The request is successfully completed. A response message informing users about the deletion of the specified job and its runs is displayed.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

JobID is invalid.

403

Forbidden

This may be because of any of the following reasons:

  • The identified user does not have proper authorization to delete a job in Control Compliance Suite.

  • The user is trying to delete a system-defined job. A system job cannot be deleted.

404

NOT found

The JobID that is specified in the request does not exist in the Control Compliance Suite system.

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.

5.4.10. Sample Python script for Delete Job API

Refer to the sample python script, which is available at the following GitHub location:

5.5. Get Latest Job Runs

Use this API to retrieve the list of latest runs for a specified job (See About Jobs) in Control Compliance Suite 12.5.

5.5.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.5.2. Authorization requirements

You must have the permissions to execute the following Control Compliance Suite tasks to use the Get Latest Job Runs API:

  • View all jobs

  • View standards

  • View assets

You must have the permissions to access the following folders to use the Get Latest Job Runs API:

  • Asset System

  • Standards

5.5.3. Request method

To retrieve the list of latest runs for a specified job, create a GET request.

5.5.4. HTTPS request components for Get Latest Job Runs API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Jobs/<JobID>/jobruns?count=<number>&ShowMessages=true
Note

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

5.5.5. HTTPS request parameters for Get Latest Job Runs API

The following table contains the description of the HTTPS request parameters for the Get Latest Job Runs API:

Field name

Field type

Data type

Description

JobID

Mandatory

GUID

This is the unique identifier of the job of which you want to retrieve the list of latest runs.

Count

Optional

Integer

This is the count of the latest job runs that you want to retrieve. If you specify 0 in the Count field, the API returns all the job runs for the specified ID. The default value of this parameter is 1.

ShowMessages

Optional

Boolean

If you want to view the error messages along with their count for each job run, use this parameter with its value 'True' in input request. The default value of this parameter is 'False'.

5.5.6. Response body for Get Latest Job Runs API

The GET request for the Get Latest Job Runs API returns the response body in the following structure:

Success Response:
{

"TotalJobRuns": {Int},
"JobID":{Int},
"JobStatusInfo":
{
"ActivityStatusList" : {Array},
"CustomStatusText": {String},
"JobEndTime": {DateTime}
"JobStartTime": {DateTime},
"JobSummary": {String},
"Status": {Int},
"StatusDetails": {String},
"Exception": {String},
"JobRunID": {GUID},
"MessageCount": {Int},
"JobMessages": {String}

}

}

5.5.7. Job status codes and their meanings

In response to the Get Latest Job Runs 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 code

Meaning

0

None

1

Pending

2

Executing

3

Idle

4

Completed

5

Faulted

6

Custom

7

Aborted

5.5.8. Sample HTTPS request for Get Latest Job Runs API

The following is a sample HTTPS request for your reference:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/ff761384-4b49-40b4-97d8-0de38669075a/jobruns?count=2&ShowMessages=true

Content type

application/json

5.5.9. Sample HTTPS response for Get Latest Job Runs API

The sample HTTPS request that you created earlier returns the following response:

{
"TotalJobRuns":1,
"JobID":"ff761384-4b49-40b4-97d8-0de38669075a",
"JobStatusInfo":[{"Exception":null,
"ActivityStatusList":null,
"CustomStatusText":null,
"JobEndTime":"2018-09-20T05:44:42",
"JobStartTime":"2018-09-20T11:14:34+05:30",
"JobSummary":null,
"Status":5,
"JobRunID":"413e6d92-6de0-4a89-8752-149270dd4369"
"MessageCount": 3,
"JobMessages": [
                " The credentials for asset  have not been configured. Please configure credentials using platform configuration.",
                "To import the asset's common fields data, configure the common platform settings that is associated with specific data collector,
                through the Component Settings dialog box.",
                " The credentials for asset  have not been configured. Please configure credentials using platform configuration."
            ]
},
]
}

5.5.10. HTTPS response codes for Get Latest Job Runs API

Depending on the success or the failure of your API request, you see the following response codes for the Get Latest Job Runs API:

Response Code

Response Type

Description

200

OK

The request is successfully completed. The list of job runs with the following details is available:

  • Total count of job runs

  • Unique identifier of a job

  • Information about the job status

  • Exceptions received during job execution

  • List of activity statuses

  • Custom status text

  • Start time of job execution

  • End time of job execution

  • Job summary

  • Job status

  • Details about job status

  • See Job status codes and their meanings.

  • Unique identifier of the job run

  • Count of error messages for a job

  • Message text

403

Forbidden

The following error message is displayed:

You are not authorized to perform this task. Access is denied.

404

NOT FOUND

The following error message is displayed:

Job for specified JobID '#JobID' not found.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

JobID is invalid.

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.

5.5.11. Sample Python script for Get Latest Job Runs API

Refer to the sample python script, which is available at the following GitHub location:

5.6. Search Job by ID

Use this API to search a job in Control Compliance Suite by providing the JobID 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.

5.6.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.6.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Search Job API:

  • View all jobs

  • View standards

  • View assets

You must have the permissions to access the following folders to use the Search Job by ID API:

  • Asset System

  • Standards

5.6.3. Request method

To search a job by using JobID, create a GET request.

5.6.4. HTTPS request components for Search Job by ID API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs/{JobID}
Note

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

5.6.5. HTTPS request parameter for Search Job by ID API

The following table contains the description of the HTTPS request parameter for the Search Job API:

Field name

Field type

Data type

Description

JobID

Mandatory

GUID

The is the unique identifier of the Control Compliance Suite job that you want to search.

5.6.6. Response body for Search Job by ID API

The GET request for the Search Job 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]
}

}

5.6.7. Job status codes and their meanings

In response to the Search Job by ID 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 code

Meaning

0

None

1

Pending

2

Executing

3

Idle

4

Completed

5

Faulted

6

Custom

7

Aborted

5.6.8. Sample HTTPS request for Search Job by ID API

The following is a sample HTTPS request for your reference:

GET https://<hostname}:<port number>/ccs/api/v1/jobs/23c59087-f3d4-4e05-a39e-3440c58e58fb/

5.6.9. Sample HTTPS response for Search Job by ID 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": "demo@example.com",
"FromEmailAddress": "demo@example.com",
"Subject": "Collection-Evaluation-Reporting job completed successfully",
"Body": "Sucess notification message"
},
"FailureNotification": {
"ToEmailAddress": "demo@example.com",
"FromEmailAddress": "demo@example.com",
"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"]
}
}

5.6.10. HTTPS response codes for Search Job by ID API

Depending on the success or the failure of your API request, you see the following response codes for the Search Job 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 JobID  ‘#JobID’ not found.

400

Bad Request

(Client Error)

The following error message is displayed:

  • JobID is invalid.

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.

5.6.11. Sample Python script for Search Job by ID API

Refer to the sample python script, which is available at the following GitHub location:

5.7. 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.

5.7.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

5.7.2. Authorization requirements

You must have the following Control Compliance Suite tasks to use the Search Job by Name API:

  • View all jobs

  • View standards

  • View assets

You must have permissions to access the following folders to use the Search Job by Name API:

  • Asset System

  • Standards

5.7.3. Request method

To search a job by using JobID, create a GET request.

5.7.4. HTTPS request components for Search Job by Name API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/jobs?/jobname=<JobName>
Note

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

5.7.5. 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:

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.

5.7.6. 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]
}

}

5.7.7. 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 code

Meaning

0

None

1

Pending

2

Executing

3

Idle

4

Completed

5

Faulted

6

Custom

7

Aborted

5.7.8. 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

5.7.9. 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": "demo@example.com",
"FromEmailAddress": "demo@example.com",
"Subject": "Collection-Evaluation-Reporting job completed successfully",
"Body": "Sucess notification message"
},
"FailureNotification": {
"ToEmailAddress": "demo@example.com",
"FromEmailAddress": "demo@example.com",
"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"]
}
}

5.7.10. 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:

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.

5.7.11. Sample Python script for Search Job by Name API

Refer to the sample python script, which is available at the following GitHub location:

6. API for Reports Service

6.1. Get Evaluation Reports

Use this API to download a report that is generated for the evaluation of a specified standard against a specified asset in Control Compliance Suite 12.5.

6.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

6.1.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Get Reports API:

  • View evaluation results

Note

You do not require permission on any Control Compliance Suite folder to use this API.

6.1.3. Request method

To download an evaluation report, create a GET request.

6.1.4. HTTPS request components for Get Evaluation Reports API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Reports?assetid=<AssetGUID>&
standardid=<StandardGUID>&reportfiletype=<fileformat>&jobrunid=<JobRunGUID>
Note

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

6.1.5. HTTPS request parameters for Get Evaluation Reports API

The following table contains the description of the HTTPS request parameters for the Get Reports API:

Field name

Field type

Data type

Description

AssetID

Mandatory

GUID

This is a unique identifier of an evaluated Control Compliance Suite asset for which an evaluation report is downloaded.

StandardID

Mandatory

GUID

This is a unique identifier of a standard against which asset is evaluated.

ReportFileType

Optional

String

This is the file format in which you want to download the evaluation report. Currently, only Microsoft Excel file format is supported.

To download the evaluation report in Microsoft Excel file format, you must complete the following prerequisites:

  • You must install Microsoft Excel on the computer on which you execute REST APIs.

  • You must create a folder called Desktop at the following location on the computer on which Control Compliance Suite is installed. The folder location varies depending on the Windows OS architecture:

    • On a 64-bit (x64) computer*: %WINDIR%\SysWow64\Config\SystemProfile

    • On a 32-bit (x86) computer*: %WINDIR%\System32\Config\SystemProfile

JobRunID

Mandatory

GUID

This is a unique identifier of the job run which contains the specified standard and asset.

6.1.6. Sample HTTPS request for Get Evaluation Reports API

The following is a sample HTTPS request for your reference:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Reports?assetid=a0f454cd-58c9-48f1-af22-3a38674b0bde&
standardid=6B020D29-5FE8-47D0-BD89-CCD3339A5EBE&reportfiletype=excel&jobrunid=bef3270d-2079-465e-b193-07782075d473

Content type

application/json

6.1.7. Sample HTTPS response for Get Evaluation Reports API

On successful report generation, HTTPS response code 200 (OK) is returned along with a downloaded file, which has the following naming convention:

'EvaluationResultExport_YYYY.MM.DD.HH.MM.SS.MSS'.xls

6.1.8. HTTPS response codes for Get Evaluation Reports API

Depending on the success or the failure of your API request, you see the following response codes for the Get Evaluation Reports API:

Response Code

Response Type

Description

200

OK

The report file is successfully downloaded in the specified format.

404

NOT Found

This error is displayed if any of the input parameters does not exist in the Control Compliance Suite system.

403

Forbidden

This may be because the identified user does not have proper authorization to access the requested content.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

6.1.9. Sample Python script for Get Evaluation Reports API

Refer to the sample python script, which is available at the following GitHub location:

7. API for Evaluation Results Service

7.1. Get Raw Results in JSON Format

Use this API to get evaluation results in raw JSON format for a specified standard and a specified asset in Control Compliance Suite 12.5.

7.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

7.1.2. Authorization requirements

You must have permissions to execute the following Control Compliance Suite tasks to use the Get Raw Results in JSON Format API:

  • View evaluation results

Note

You do not require permission on any Control Compliance Suite folder to use this API.

7.1.3. Request method

To retrieve raw results in JSON format, create a POST request.

7.1.4. HTTPS request components for Get Raw Results in JSON Format API

Create a POST request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Results
Note

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

{
"AssetID": "<asset-GUID>",
"StandardID": "<standard-GUID>",
"StandardVersion" : "n1.n2.n3",
"JobRunID": "<job run GUID>",
"CheckIDList":["GUID1", "GUID2"]
}

7.1.5. HTTPS request parameters for Get Raw Results in JSON Format API

The following table contains the description of the HTTPS request parameters for the Get Raw Results in JSON Format:

Field name

Field type

Data type

Description

AssetID

Mandatory

GUID

This is a unique identifier of the evaluated Control Compliance Suite asset.

StandardID

Mandatory

GUID

This is a unique identifier of a standard against which asset is evaluated.

JobRunID

Optional

GUID

This is a unique identifier of the job run which contains the specified standard and asset.

If you do not use this parameter, the latest job run which contains the specified asset and standard is considered to retrieve results.

StandardVersion

Optional

Integer

This is the version of the standard against which asset is evaluated.

Note

If you provide the job run ID, the results related to the specified job run ID are displayed irrespective of the version of the standard. If you neither provide job run ID nor standard version, the default version of the standard is displayed in results.

CheckIDList

Optional

GUID

This is the list of check IDs for which you want raw results.

If you do not use this parameter, evaluation results for the entire standard are displayed.

7.1.6. Sample HTTPS request for Get Raw Results in JSON Format API

The following is a sample HTTPS request for your reference:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/Results

Content type

application/json

JSON body

{
"AssetID" : "0652284f-5c06-4b92-89b5-27e0144a700f",
"StandardID" : "DBF4BB0F-9985-4F36-9E8F-7F79AD4B05E5",
"StandardVersion" : "1.0.0",
"JobRunID" : "a384a120-3d03-47fb-ac62-d647cec3e723" ,
"CheckIDList" : ["f2907f6e-596a-474f-9535-3049d77b4e1e"]
}

7.1.7. Sample HTTPS response for Get Raw Results in JSON Format API

On successful completion of request, HTTPS response code 200 (OK) is returned along with a JSON file, which contains raw data similar to the following:

{

  "RawEvaluationResult": {

    "Passed Checks": [

      {

        "Check name": "2.2.13 Is HTTP Proxy Server disabled?",

        "Check status": "Pass",

        "CheckID": "02676232-979d-4922-896e-d3c5dc061562",

        "Risk": "N/A",

        "Confidentiality": "Partial",

        "Integrity": "Partial",

        "Availability": "Partial",

        "AccessComplexity": "Low",

        "AccessVector": "Adjacent Network Accessible",

        "Authentication": "No Authentication"

      },

...

"Failed Checks": [

      {

        "Check name": "2.2.2 Is X Windowsnot installed?",

        "Check status": "Fail",

        "CheckID": "31db209d-8709-4d75-8127-3834103b0ac5",

        "Evidence Details": [

          {

            "EntityName": "Packages",

            "Evidences": [

              {

                "EvalCheckId": "19063ed5-ddd5-e811-80d6-005056b8aad4",

                "CheckID": "31db209d-8709-4d75-8127-3834103b0ac5",

                "ObjectDisplayName": "xorg-x11-xinit",

                "ObjectTypeName": "Unix.Package",

                "ObjectTypeDisplayName": "Packages",

                "FieldName": "Unix.Package.Name",

                "FieldDisplayName": "Package Name",

                "FailedExpression": "NOT(Unix.Package.Name =~ '^xorg-x11.*')",

                "CurrentValue": "xorg-x11-xinit"

              }

            ]

          },

          {

            "EntityName": "Packages",

            "Evidences": [

              {

                "EvalCheckId": "19063ed5-ddd5-e811-80d6-005056b8aad4",

                "CheckID": "31db209d-8709-4d75-8127-3834103b0ac5",

                "ObjectDisplayName": "xorg-x11-server-common",

                "ObjectTypeName": "Unix.Package",

                "ObjectTypeDisplayName": "Packages",

                "FieldName": "Unix.Package.Name",

                "FieldDisplayName": "Package Name",

                "FailedExpression": "NOT(Unix.Package.Name =~ '^xorg-x11.*')",

                "CurrentValue": "xorg-x11-server-common"

              }

            ]

          },

...

"Exempted Checks": [


    ],

    "NotApplicable Checks": [

      {

        "Check name": "2.2.1.2 Is Network Time Protocol (NTP) service configured correctly?",

        "Check status": "NotApplicable",

        "CheckID": "104a00ff-1b28-444f-9a07-a21d2c384618",

        "Evidence Details": [

          {

            "EntityName": "TextFileContent",

            "Evidences": [

              {

                "EvalCheckId": "15063ed5-ddd5-e811-80d6-005056b8aad4",

                "CheckID": "104a00ff-1b28-444f-9a07-a21d2c384618",

                "ObjectDisplayName": "[No data available]",

                "ObjectTypeName": "Unix.TextFileContent",

                "ObjectTypeDisplayName": "TextFileContent",

                "FieldName": "Unix.TextFileContent.FullyQualifiedName",

                "FieldDisplayName": "File Name (With Path)",

                "FailedExpression": "File Name (With Path) exact '/etc/ntp.conf'|File Name (With Path) exact '/etc/sysconfig/ntpd'",

                "CurrentValue": "[No data available]"

              }

            ]

          }

        ],

        "Risk": "N/A",

        "Confidentiality": "Partial",

        "Integrity": "Complete",

        "Availability": "Complete",

        "AccessComplexity": "High",

        "AccessVector": "Adjacent Network Accessible",

        "Authentication": "No Authentication"

      },

...

    "Check(s) to be manually reviewed": [

      {

        "Check name": "6.2.3 Is it ensured that no legacy entries exist in the shadow file?",

        "Check status": "Unknown",

        "CheckID": "142942bd-d44f-47e6-b602-e329536c8a3e",

        "Evidence Details": [

          {

            "EntityName": "Files",

            "Evidences": [

              {

                "EvalCheckId": "e3063ed5-ddd5-e811-80d6-005056b8aad4",

                "CheckID": "142942bd-d44f-47e6-b602-e329536c8a3e",

                "ObjectDisplayName": "/etc/shadow",

                "ObjectTypeName": "Unix.File",

                "ObjectTypeDisplayName": "Files",

                "FieldName": "Unix.File.Content",

                "FieldDisplayName": "Content",

                "FailedExpression": "NOT(Content %~ '/^[ \\t]*\\+[ \\t]*/m')",

                "CurrentValue": "{Blocked File} ;"

              }

            ]

          }

        ],

        "Risk": "N/A",

        "Confidentiality": "Partial",

        "Integrity": "Partial",

        "Availability": "Partial",

        "AccessComplexity": "Low",

        "AccessVector": "Adjacent Network Accessible",

        "Authentication": "Single Instance"

      },

...

    "Asset Name": "rhel7x64mysql:10.211.105.134",

    "Standard Name": "CIS-RHEL-6x",

    "Compliance  Statistics": {

      "Check(s) Passed": "80",

      "Check(s) Error": "97",

      "Check(s) Failed": "0",

      "Check(s) Total": "177",

      "Data collected on date": "22-10-2018 11:34:20",

      "Compliance Score": "44.69",

      "Risk Score": "5.6"

    }

  }

}

7.1.8. HTTPS response codes for Get Raw Results in JSON Format API

Depending on the success or the failure of your API request, you see the following response codes for the Get Raw Results in JSON Format API:

Response Code

Response Type

Description

200

OK

Raw results are retrieved successfully in JSON format.

404

NOT Found

This error is displayed if any of the input parameters does not exist in the Control Compliance Suite system.

403

Forbidden

This may be because the identified user does not have proper authorization to access the requested content.

401

Unauthorized

This may be because of an invalid or expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

7.1.9. Sample Python script for Get Raw Results in JSON Format API

Refer to the sample python script, which is available at the following GitHub location:

8. APIs for Remediation Service

8.1. Get Remediation Ticket Details by Ticket Number

Use this API to retrieve the details of a Control Compliance Suite remediation ticket. To retrieve ticket details, provide the display number of the ticket in input request.

8.1.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

8.1.2. Authorization requirements

You must be in the Remediation Administrator role to use the Get Remediation Ticket Details by Ticket Number API.

You must have permissions on the standard and the assets that are mentioned in the ticket to use the Get Remediation Ticket Details by Ticket Number API:

8.1.3. Request method

To retrieve the details of a Control Compliance Suite remediation ticket, create a GET request.

8.1.4. HTTPS request components for Get Remediation Ticket Details by Ticket Number API

Create a GET request by using the following components:

Request component

Value

URL

https://<host name>:<port number>/ccs/api/v1/RemediationTickets?TicketNumber={TicketNumber}
Note

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

8.1.5. HTTPS request parameters for Get Remediation Ticket Details by Ticket Number API

The following table contains the description of the HTTPS request parameter for the Get Remediation Ticket Details by Ticket Number API:

Field name

Field type

Data type

Description

TicketNumber

Mandatory

String

This is the unique identifier of a Control Compliance Suite ticket of which you want to retrieve the details. This number is displayed in the Ticket Number column in the Remediation workspace.

8.1.6. Response body for Get Remediation Ticket Details by Ticket Number API

The GET request for the Get Remediation Ticket Details by Ticket Number API returns the response body in the following structure:

Success Response:
{
"RemediationTicket":
{"CreatedBy":,
"CreatorAdamJobID":,
"AssignedTo":,
"CreatedOn":,
"ModifiedOn":,
"Priority":,
"Status":,
"TicketNumber":,
"ticketDescription":,
"ticketID":,
"TicketImpact":,
"ticketState":,
"TicketUrgency":,
"AdditionalDataAsXML":
}
}
Note

In the response body, the AdditionalDataAsXML field contains remediation context details.

8.1.7. Sample HTTPS request for Get Remediation Ticket Details by Ticket Number API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/RemediationTickets?TicketNumber=INCA0000001

Content type

application/json

8.1.8. Sample HTTPS response for Get Remediation Ticket Details by Ticket Number API

The sample HTTPS request that you created earlier returns the following response:

{"RemediationTicket":
{"CreatedBy":"<domain name>\\<user name>","JobID":"1f3f0678-2c9a-46af-9530-40789f72ed97","AssignedTo":"",
"CreatedOn":"2018-11-14T05:51:12.59","ModifiedOn":null,"Priority":"High","Status":"Open","TicketNumber":"INCA0000001",
"ticketDescription":"","ticketID":"a5e911a4-0b13-45a2-b472-82fa1c655d0f","TicketImpact":2,"ticketState":1,"TicketUrgency":1,
"AdditionalDataAsXML":"<RemediationContextDetails xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<RemediationTicketSummary><Description>This is a remediation ticket created for the standard CIS Microsoft Windows Server 2012 R2 v2.2.1 in Control Compliance Suite.</Description>
<Standard name=\"CIS Microsoft Windows Server 2012 R2 v2.2.1\" version=\"1.2.0\">
<StandardID>96025bd1-0e6f-4ac3-9e1f-8715f7739f02</StandardID><TotalChecks>329</TotalChecks></Standard><TotalFailedChecksInThisStandard>210</TotalFailedChecksInThisStandard>
<TotalFailedChecksInThisTicket>18</TotalFailedChecksInThisTicket></RemediationTicketSummary>
<FailedCheckDetails><Check name=\"18.9.24.2 Is the 'Default Action and Mitigation Settings' parameter set to 'Enabled' (plus subsettings)?\" version=\"1.0.0\">
<CheckId>06e603b7-5ef7-4e8e-bb8c-a3cbecb83fea</CheckId>
<RemediationDetails>To establish the recommended configuration via GP,
set the following UI path to Enabled: Computer Configuration\\Policies\\Administrative Templates\\Windows Components\\EMET\\Default Action and
Mitigation SettingsNOTE: This Group Policy path does not exist by default. An additional Group Policy template
(EMET.admx/adml) is required - it is included with Microsoft Enhanced Mitigation Experience Toolkit (EMET).
Impact:</RemediationDetails>
<AssetDetails><Asset name=\"<domain name>\\<IP address>\"><AssetId>e696a8e0-623f-4585-aceb-1f3c8ecc2779</AssetId></Asset></AssetDetails></Check>
<Check name=\"18.9.61.1 Is the 'Turn off Automatic Download and Install of updates' parameter set to 'Disabled'?\" version=\"1.0.0\">
<CheckId>0fc6c986-1f16-4bb6-b06c-0630ac5fbe75</CheckId>
<RemediationDetails>To establish the recommended configuration via GP,
set the following UI path to Disabled:Computer Configuration\\Policies\\Administrative Templates\\Windows Components\\Store\\Turn off Automatic Download and
Install of updates Impact:If you disable this setting, the automatic download and installation of app updates is turned on.
</RemediationDetails><AssetDetails><Asset name=\"<domain name>\\<IP address>\"><AssetId>e696a8e0-623f-4585-aceb-1f3c8ecc2779</AssetId></Asset></AssetDetails>
</Check><Check name=\"18.9.24.8 Is the 'System SEHOP' parameter set to 'Enabled: Application Opt-Out'?\" version=\"1.0.0\">
<CheckId>18d8a97a-c11a-4fe6-ada6-f6f07c006662</CheckId>
<RemediationDetails>To establish the recommended configuration via GP, set the following UI path to Enabled:
Application Opt-Out: Computer Configuration\\Policies\\Administrative Templates\\Windows Components\\EMET\\System SEHOPNOTE:
This Group Policy path does not exist by default. An additional Group Policy template (EMET.admx/adml) is required -
it is included with Microsoft Enhanced Mitigation Experience Toolkit (EMET). Impact:</RemediationDetails>
<AssetDetails><Asset name=\"<domain name>\\<IP address>\"><AssetId>e696a8e0-623f-4585-aceb-1f3c8ecc2779</AssetId></Asset>
</AssetDetails></Check><Check name=\"18.9.24.1 Is the 'EMET 5.51' or later installed?\" version=\"1.0.0\">
<CheckId>1efcfb85-a62b-44ae-97e3-1df62f2915bb</CheckId><RemediationDetails>Install EMET 5.51 or higher. Impact:</RemediationDetails>
<AssetDetails><Asset name=\"ccsdev\\10.211.105.4\"><AssetId>e696a8e0-623f-4585-aceb-1f3c8ecc2779</AssetId>
</Asset></AssetDetails></Check><Check name=\"18.9.24.7 Is...}

8.1.9. HTTPS response codes for Get Remediation Ticket Details by Ticket Number API

Depending on the success or the failure of your API request, you see the following response codes for the Get Remediation Ticket Details by Ticket Number API:

Response Code

Response Type

Description

200

OK

The following remediation ticket details are retrieved:

  • User name of user who creates the ticket

  • Unique identifier of the job from which the ticket is created

  • Details of user to whom the ticket is assigned for remediation

  • Date and time when the ticket is created

  • Date and time when the ticket is modified

  • Priority of the ticket

  • Ticket status

  • Display number of the ticket

  • Description

  • Ticket GUID

  • Ticket impact level

  • Ticket state

  • Ticket urgency

  • Additional data in XML format

403

Forbidden

The following error message is displayed:

You are not authorized to perform this operation. Access is denied.

404

Not Found

This code is returned because of one of the following reasons:

  • If the ticket number that is provided in the input request does not exist in Control Compliance Suite, the following error message is displayed:

    Ticket not found. Provide valid ticket number.
  • If the user in the Remediation Administrator role does not have permissions on the assets that are mentioned in the ticket, the following error message is displayed:

    The asset details could not be obtained completely.
    This may be because you do not have sufficient permissions on all the assets,
    or the assets are already deleted.
  • If the user in the Remediation Administrator role does not have permissions on the standard that is mentioned in the ticket, the following error message is displayed:

    The standard details could not be obtained.
    This may be because you do not have sufficient permissions on the standard,
    or the standard is already deleted.

401

Unauthorized

This may be because of one of the following reasons:

  • Invalid or expired access token in an API request

      *
    <<Using token-based authentication for Control Compliance Suite RESTful APIs>>
  • User does not have the Remediation Administrator role.

  • See About roles.

400

Bad Request

(Client Error)

This may be because of one of the following reasons:

  • If the ticket number in the request is null or invalid, the following error message is displayed:

    Ticket number is invalid or empty.
  • If the ticket number is valid but the ticket details are invalid, the following error message is displayed:

    Provide valid ticket details.
  • If you do not provide ticket details to update, the following error message is displayed:

    Provide ticket details to update.
  • If the ticket state that is mentioned in the request is invalid, the following error message is displayed:

    Provide valid ticket state.

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.

8.1.10. Sample Python script for Get Remediation Ticket Details by Ticket Number API

Refer to the sample python script, which is available at the following GitHub location:

8.2. Search Remediation Tickets

Use this API to retrieve the list of remediation tickets in Control Compliance Suite (CCS) 12.5.

8.2.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

8.2.2. Authorization requirements

You must be in the Remediation Administrator role to use the Search Remediation Tickets API.

You must have permissions on the standard and the assets that are mentioned in the ticket to use the Search Remediation Tickets API:

8.2.3. Request method

To retrieve the list of Control Compliance Suite assets in your environment, create a GET request.

8.2.4. HTTPS request components for Search Remediation Tickets API

Create a GET request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/
RemediationTickets?Fields=(FieldName1 OP value1, FieldName2 OP value2, FieldNameN OP valueN) & Page=X & PageSize=Y
Note

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

8.2.5. HTTPS request parameters for Search Remediation Tickets API

The following table contains the description of the HTTPS request parameters for the Search Remediation Tickets API:

Field name

Field type

Data type

Description

Fields

Mandatory

String

This is a comma-separated list of ticket fields and their respective values that are joined by an operator. The ‘OP’ placeholder in the HTTPS request components for Search Remediation Tickets API section indicates the '=' query operator.

See the Remediation Ticket Fields table.

Comma in the list of field names is treated as 'AND'.

The Search Remediation Tickets API returns a list of remediation tickets along with their total count.

Page

Optional

Integer

Considering that the Search Remediation Tickets API can return huge data depending on the number of tickets 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.

You can use all or any of the following remediation ticket fields in input request:

Remediation Ticket Fields

Field

Data type

Description

TicketNumber

String

This is the ticket number which is displayed in the Ticket Number column in the Remediation workspace.

TicketID

GUID

This is the unique identifier of a remediation ticket. You can obtain this ID by using the Get Remediation Ticket Details by Ticket Number API.

CreatedBy

String

This is the user name of user who creates the ticket.

JobID

GUID

This is the unique identifier of the job from which the ticket is created.

AssignedTo

String

These are the details of user to whom the ticket is assigned for remediation.

CreatedOn

String

This is the date when the ticket is created. Use any of the following date formats in input request:

  • DD/MM/YYYY

  • DD-MM-YYYY

If you use this parameter, remediation tickets that are created only on the specified date are returned in response.

CreatedDateStarts

String

Use the CreatedDateStarts parameter to get the list of tickets that are created on and after the specified date.

Use the CreatedDateEnds parameter to get the list of tickets that are created on and before the specified date.

The permissible date formats are same as the CreatedOn parameter.

CreatedDateEnds

String

ModifiedOn

String

This is the date when the ticket is modified. The permissible date formats are same as the CreatedOn parameter.

ModifiedDateStarts

String

Use the ModifiedDateStarts parameter to get the list of tickets that are modified on and after the specified date.

Use the ModifiedDateEnds parameter to get the list of tickets that are modified on and before the specified date.

The permissible date formats are same as the CreatedOn parameter.

ModifiedDateEnds

String

Priority

String

This is the priority that is set by the user.

TicketState

Integer

This is the number that denotes state of the ticket. Each integer value of this parameter represents a ticket status.

TicketUrgency

Integer

This is the number that denotes urgency of the ticket.

TicketProviderType

Integer

8.2.6. Response body for Search Remediation Tickets API

The GET request for the Search Remediation Tickets API returns the response body in the following structure:

Success Response:
{

"TotalCount": Int,

"TotalPages": Int,

"PrevPageUrl": String,

"NextPageUrl":String,

"TicketList":

  [

  {

"TicketNumber": String

"TicketID": String

"CreatedBy": Domain\User Name

"JobID":String

"AssignedTo":String

"CreatedOn": Date(DD/MM/YYYY OR DD-MM-YYYY)

"CreatedDateStarts":Date(DD/MM/YYYY OR DD-MM-YYYY)

"CreatedDateEnds":Date(DD/MM/YYYY OR DD-MM-YYYY)

"ModifiedOn":Date(DD/MM/YYYY OR DD-MM-YYYY)

"ModifiedDateStarts":Date(DD/MM/YYYY OR DD-MM-YYYY)

"ModifiedDateEnds":Date(DD/MM/YYYY OR DD-MM-YYYY)

"Priority ":String

"TicketImpact"" Int

"TicketState": Int

"TicketUrgency ": Int

"TicketProviderType ": Int

}

]

}

8.2.7. Sample HTTPS request for Search Remediation Tickets API

The following is a sample HTTPS request for your reference. We have used DisplayName as the attribute in the sample:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/
RemediationTickets?fields=fields=(TicketState=1,TicketProviderType=2)&page=0&pagesize=2

Content type

application/json

8.2.8. Sample HTTPS response for Search Remediation Tickets API

The sample HTTPS request that you created earlier returns the following response:

{

"TotalCount":4,
"TotalPages":2,
"PrevPageUrl":"",
"NextPageUrl":"https://<host name>:<port number>/ccs/api/v1/remediationtickets?Fields=%28TicketState%3D1%2CTicketProviderType%3D2%29&page=1&pagesize=2",
"TicketList":[{"TicketNumber":"INCA0000003","TicketID":"2e1fba4d-3d76-42ba-9fc4-52c4a1923b56",
"CreatedBy":"<domian name>\\<user name>",
"JobID":"1f0ee8cb-d843-48a6-b7b1-f36f0c4e658d",
"AssignedTo":"","CreatedOn":"2018-11-23T08:43:17.913","ModifiedOn":"2018-11-23T08:43:17.913",
"Priority":"Moderate","Status":"Open","TicketImpact":2,"TicketState":1,"TicketUrgency":2,
"TicketProviderType":2},
{"TicketNumber":"INCA0000004","TicketID":"72e644c9-1a3b-465d-8119-c268b56ca474",
"CreatedBy":"<domian name>\\<user name>",
"JobID":"1f0ee8cb-d843-48a6-b7b1-f36f0c4e658d",
"AssignedTo":"","CreatedOn":"2018-11-23T08:43:19.85","ModifiedOn":"2018-11-23T08:43:19.85",
"Priority":"Moderate","Status":"Open","TicketImpact":2,"TicketState":1,"TicketUrgency":2,
"TicketProviderType":2}]

}

8.2.9. HTTPS response codes for Search Remediation Tickets API

Depending on the success or the failure of your API request, you see the following response codes for the Search Remediation Tickets API:

Response Code

Response Type

Description

200

OK

The list of remediation tickets is available with the following asset details:

  • Total count of tickets

  • Total pages

  • Previous page URL

  • Next page URL

  • Ticket details

  • Ticket details include the following information:

  • Display number

  • Ticket GUID

  • User who creates the ticket

  • Unique identifier of the job from which the ticket is created

  • User to whom the ticket is assigned for remediation

  • Dates when the ticket is created and modified

  • Ticket priority

  • Ticket status

  • Ticket impact

  • Ticket state

  • Ticket urgency

  • Ticket type (ServiceNow or Control Compliance Suite)

200

(with Total Count: 0 in response body)

OK

The request is completed successfully. However, there are no records matching the request parameters. In this case, the following response is returned. The total count of tickets in this case is zero:

{
    "TotalCount": 0,
    "TotalPages": 0,
    "PrevPageUrl": "",
    "NextPageUrl": "",
    "TicketList": []
}

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 access token or an expired access token in an API request.

400

Bad Request

(Client Error)

The following error message is displayed:

Server could not understand the request due to invalid syntax.
Please check requested URL.

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.

8.2.10. Sample Python script for Search Remediation Tickets API

Refer to the sample python script, which is available at the following GitHub location:

8.3. Update Remediation Ticket Details

Use this API to update Control Compliance Suite remediation ticket details.

You can update any of or all the following details in an input request for a single ticket at a time:
  • Ticket state (from 1 to 5)

  • Description

  • Ticket priority

  • Details of user to whom the ticket is assigned for remediation

8.3.1. Authentication

To grant access to users to view or execute Control Compliance Suite RESTful APIs, you must generate an authentication token.

8.3.2. Authorization requirements

You must be in the Remediation Administrator role to use the Update Remediation Ticket Details API.

You must have permissions on the standard and the assets that are mentioned in the ticket to use the Update Remediation Ticket Details API.

8.3.3. Request method for Update Remediation Ticket Details API

To update remediation ticket details, create a PATCH request.

8.3.4. HTTPS request components for Update Remediation Ticket Details API

Create a PATCH request by using the following components:

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/RemediationTickets/
Note

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

{"TicketNumber":<ticket_number>,
"TicketState":<ticket_state>,
"TicketDescription": <Ticket_Description>,
"Priority":<Ticket_Priority>,
"AssignedTo":<user ID or email ID or user name>}

8.3.5. HTTPS request parameters for Update Remediation Ticket Details API

The following table contains the description of the HTTPS request parameters for the Update Remediation Ticket Details API. You can update all or any of these parameters to update the ticket details.

Field name

Field type

Data type

Description

TicketNumber

Optional

String

This is the ticket number which is displayed in the Ticket Number column in the Remediation workspace.

TicketState

Optional

Integer

This is the number that denotes state of the ticket. Each integer value of this parameter represents a ticket status.

TicketDescription

Optional

String

This is the ticket description.

Priority

Mandatory

Integer

You can set the ticket priority level.

AssignedTo

Optional

String

This is the user ID, email ID, or user name of the user to whom the ticket is assigned for remediation.

8.3.6. Control Compliance Suite ticket statuses

You can update the status of a Control Compliance Suite remediation ticket by updating the value of the TicketState parameter in an input request. The ticket states and the corresponding statuses that they represent are listed in the following table:

State

Status

1

Open

2

Remediation Performed

3

Verified

4

Failed

5

Not Applicable

Control Compliance Suite processes remediation tickets only for the ticket statuses that are mentioned in this table.

Note

The Remediation Verification job is run only after you update the ticket state to 2, which means Remediation Performed.

8.3.7. Response body for Update Remediation Ticket Details API

The PATCH request for the Update Remediation Ticket Details API returns the response body in the following structure:

204 (No content)

8.3.8. Sample HTTPS request for Update Remediation Ticket Details API

The following is a sample HTTPS request for your reference.

Request component

Value

URL

https://<hostname>:<port number>/ccs/api/v1/RemediationTickets/
Note

You can also use the Fully Qualified Domain Name (FQDN) as the hostname. You can configure the port number in the configuration file of the Application Server by adding the REST_API_PORT key. 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

{"TicketNumber":"INCA0000009",
"TicketState":"2",
"ticketDescription":"Description text",
"Priority":"Medium",
"AssignedTo":"example domain\sysadmin"}

8.3.9. Sample HTTPS response for Update Remediation Ticket Details API

204 (No content)

8.3.10. HTTPS response codes for Update Remediation Ticket Details API

Depending on the success or the failure of your API request, you see the following response codes for the Update Remediation Ticket Details API:

Response Code

Response Type

Description

204

No content

Remediation ticket details are updated successfully. 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 one of the following reasons:

  • Invalid or expired access token in an API request

      *
    <<Using token-based authentication for Control Compliance Suite RESTful APIs>>
  • User does not have the Remediation Administrator role.

  • See About roles.

400

Bad Request

(Client Error)

This may be because of one of the following reasons:

  • If input request contains an invalid ticket number, the following error message is displayed:

    Ticket number is invalid or empty.
  • If input request contains an invalid ticket state, the following error message is displayed:

    Provide valid ticket state.
  • If input request contains no ticket details to update, the following error message is displayed:

    Provide ticket details to update.
  • If input request contains invalid ticket details, the following error message is displayed:

    Provide valid ticket details.

404

Not found

The following error message is displayed:

Ticket not found. Provide valid ticket number.

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.

8.3.11. Sample Python script for Update Remediation Ticket Details API

Refer to the sample python script, which is available at the following GitHub location: