Automating Assessment Requests

This page details steps to set up your assessment request integration.

Automating Assessment Requests Overview

There are multiple steps to automate your assessment request.

Create an API key - learn more here
Set up an Authentication Flow
Set up Triggers - Configure conditional rules in GRC platform controlling when to send the assessment request
Request Field Mapping - Map Required fields from GRC to API Request
Configure API Authentication - Authentication is required for all API requests
Store API response attributes in GRC platform

Create a new API Key

Navigate to the Developer Portal. For more information, see GRC Integration Overview.
Click API Key Manager.
Click Create New API Key.
Specify an API Key Name. Note: the name is not used for anything by the CORL system.
Click Create.

API Key Manager.png

Click the Actions button.
Copy the API Key value from the CORL portal to your application.

Set up Authentication

The authentication for API requests uses a JWT token as a Bearer token. To set up an authentication flow you can follow one of the 2 patterns below.

Request a Bearer Token from CORL

Email CORL Customer Support, specifying the organization you're with and the reason for the request. We will respond within 5 business days.
Confirm the API end point and domains you from CORL
Add the CORL-provided JWT token to your secret variables
Pass the JWT token to the subsequent flow executions
The JWT Token should be passed in the header format of: "Authorization Bearer {{ jwtToken }}" (note the brackets indicate a variable and are not required)

Create a Bearer Token via Workflow

Create a new workflow in your GRC platform
Connect your workflow to /v1/public/api/token
Configure your workflow to send your API key in the body of the call
```
{
    "ApiKey": "{{apiKey}}"
}
```
Pass the JWT token to the subsequent flow executions
The JWT Token should be passed in the header format of: "Authorization Bearer {{ jwtToken }}" (note the brackets indicate a variable and are not required)
NOTE: JWT tokens created in this workflow expire frequently and CORL recommends you refresh them every 60 minutes

Setting Up Triggers

Triggers are an important part of automating assessment requests. Your organization controls which assessments to send to CORL and when. The best practices for trigger set up is below.

Confirm with your stakeholders the conditions when an assessment should be sent to CORL
- a common ruleset is based off your inherit risk determined in your intake
Add a custom field on your vendor or assessment objects that indicate whether to "Send to CORL"
Create an automation that sets the "Send to CORL" based on the dependent fields changing
When adding the workflow in the next step, make sure to set up your workflow with the conditional logic based off the "Send to CORL" custom field or the rulesets you have

Request Field Mapping

The API request body is critical for both business and technical reasons. Based on your engagement with CORL, some of the fields may be defaulted or hard coded.

API Spec Business Definitions

Field Name	Schema Path	Definition
Assessment Processing Correlation Identifier	assessmentCreationProcessingCorrelationId	Correlation ID that tracks a specific assessment request while it is reviewed by a CORL team member
Assessment Category	assessmentCategory	Whether the assessment includes a pre-assessment or not
Assessment Type	assessmentType	Type of assessment requested by a client
Assessment Correlation ID	assessmentCorrelationId	Client Provided tracking ID from GRC
Vendor ID	vendor.vendorId	CORL assigned unique identifier for a vendor organization
Vendor Name	vendor.vendorName	CORL's name for a vendor organization
Vendor URL	vendor.vendorUrl	Vendor organization website domain
Client Alias	vendor.clientAlias	Client provided name of vendor
Vendor Correlation ID	vendor.vendorCorrelationId	Client provided identifier to enable correlation of a vendor from source system to CORL system
Vendor Headquarters Country	vendor.vendorHeadquartersCountry	Country where the Vendor's HQ is located
Vendor State	vendor.vendorHeadquartersState	State where the vendor's HQ is located
Vendor Contact First Name	vendor.vendorContact[].firstName	First name of the vendor's assessment contact
Vendor Contact Last Name	vendor.vendorContact[].lastName	Last name of the vendor's assessment contact
Vendor Contact Title	vendor.vendorContact[].title	Title of the vendor's assessment contact
Vendor Contact Phone Number	vendor.vendorContact[].phoneNumber	Phone number of the vendor's assessment contact
Vendor Contact Email	vendor.vendorContact[].email	Email of the vendor's assessment contact
Product Type	vendor.product.productType	Primary category of the product
Product Medical Device Indicator	vendor.product.isMedicalDevice	Whether the product is a medical device
Product Location	vendor.product.location	Client location where the product will be implemented
Product Name	vendor.product.productName	Product Name
Product Model / Version Number	vendor.product.modelOrVersionNumber	Model or version number associated to the product
Product URL	vendor.product.productUrl	Specific url associated to the product
Product Description	vendor.product.productDescription	Description of the product
Product Vendor Identifier	vendor.product.productVendorId	Vendor identifier that the product is associated to
Business Stakeholder Contact First Name	businessStakeholder[].firstName	First name of the business stakeholder in the client organization
Business Stakeholder Contact Last Name	businessStakeholder[].lastName	Last name of the business stakeholder in the client organization
Business Stakeholder Contact Department	businessStakeholder[].department	Department of the business stakeholder in the client organization
Business Stakeholder Contact Phone Number	businessStakeholder[].phoneNumber	Phone number of the business stakeholder in the client organziation
Business Stakeholder Contact Email	businessStakeholder[].email	Email of the business stakeholder in the client organization
Implementation Environment	vendorInherentRisk.implementationEnvironment[]	Environment product uses
Data Types	vendorInherentRisk.dataTypes[]	Data used by the product
Storage Location Access Types	vendorInherentRisk.storageLocationAccesssTypes[]	Storage types used by the product
Network Access Types	vendorInherentRisk.networkAccesssTypes[]	Network access types used by the product
Estimate Volume of Records	vendorInherentRisk.estimateAccessToVolumeOfRecords	Volume of records estimated to be accessed by the product
Vendor Inherent Risk Rating	vendorInherentRisk.inherentVendorRiskRating	Client provided inherent risk rating for the product
Obtain Scoping Information	scopingInformation.obtainScopingInformation	Assignment of whether CORL should reach out to the vendor to determine scoping information or if it will be provided by the client
Obtain Control Information	securityControlInformation.obtainSecurityControlInformation	Assignment of whether CORL should reach out to the vendor to gather assessment detailed information or if it will be provided by the client
Assessment Comments	comments	Free text additional context to be provided for an assessment

Assessment Request Technical Requirements

Schema Path	Required Field	Data Type	Examples (ENUMs if applicable)
assessmentCategory	Required	String - ENUM	fullAssessment, Pre-assessment, both
assessmentType	Required	String - ENUM	corlCleared, standard
assessmentCorrelationId	Optional	String - ENUM	"11182732" or "53fa467e-d25d-e711-8104-5065f38b5171"
vendor.vendorId	Optional	String - UUID	53fa467e-d25d-e711-8104-5065f38b5171
vendor.vendorName	Required	String	"CORL Technologies"
vendor.vendorUrl	Required	String	www.corltech.com
vendor.clientAlias	Optional	String
vendor.vendorCorrelationId	Optional	String
vendor.vendorHeadquartersCountry	Optional	String
vendor.vendorHeadquartersState	Optional	String
vendor.vendorContact[].firstName	Required	String
vendor.vendorContact[].lastName	Required	String
vendor.vendorContact[].title	Optional	String
vendor.vendorContact[].phoneNumber	Optional	String
vendor.vendorContact[].email	Required	String
vendor.product.productType	Required	String - ENUM	service, product
vendor.product.isMedicalDevice	Required	Boolean
vendor.product.location	Optional	String
vendor.product.productName	Required	String
vendor.product.modelOrVersionNumber	Optional	String
vendor.product.productUrl	Optional	String
vendor.product.productDescription	Optional	String
businessStakeholder[].firstName	Optional	String
businessStakeholder[].lastName	Optional	String
businessStakeholder[].department	Optional	String
businessStakeholder[].phoneNumber	Optional	String
businessStakeholder[].email	Optional	String
vendorInherentRisk.implementationEnvironment[]	Required	String - ENUM	onPrem, cloudHosted, vendorHosted, productSupport, consulting-clientManagedSystem, consulting-vendorManagedSystem
vendorInherentRisk.dataTypes[]	Optional	String - ENUM	phi, pii, pci, employeeInformation, internalProprietaryInfomation
vendorInherentRisk.storageLocationAccesssTypes[]	Optional	String - ENUM	onPrem, vendorDataCenter, thirdPartyDataCenter, workstation, mobileDevice
vendorInherentRisk.networkAccesssTypes[]	Optional	String - ENUM	onSiteAccess, infrastructureAccess, databaseOrApplicationAccess, receiptOfData, noAccessToNetwork
vendorInherentRisk.estimateAccessToVolumeOfRecords	Optional	String - ENUM	"0-1000", "1001-10000", "10001-100000", "100001-1000000", "1000000+"
vendorInherentRisk.inherentVendorRiskRating	Optional	String - ENUM	veryLow, low, medium, high, veryHigh
scopingInformation.obtainScopingInformation	Required	String - ENUM	corlContactVendor, providedSecurityInfomation
securityControlInformation.obtainSecurityControlInformation	Required	String - ENUM	corlContactVendor, providedSecurityInfomation
comments	Optional	String

{
	"assessmentCategory": "full",
	"assessmentType":"standard",
    "isAssessmentValidated":"false",
    "assessmentCorrelationId": "101929",
	"vendor": {	
		"vendorId": null,
		"vendorName": "PB Vendor Services",
		"vendorUrl": "pbvendorservices.com",
		"clientAlias": "",
		"vendorCorrelationId": "",
		"vendorHeadquartersCountry": "",
		"vendorState": "",
		"vendorContact": [
				{
				"firstName": "Paul",
				"lastName": "Buonomo",
				"title": "",
				"phoneNumber": "",
				"email": "paul.buonomo@corltech.com"
			}
		],
		"product": {
			"productType": "product",
			"isMedicalDevice": false, 
			"location": "",
			"productName":"Automation Testing Services",
			"modelOrVersionNumber": "",
			"productUrl":"",
			"productDescription":""
		}
	},
	"businessStakeholder": [
			{
			"firstName":"",
			"lastName":"",
			"department":"",
			"email":"",
			"phone":""
		}
	],
	"vendorInherentRisk": {
		"implementationEnvironment": [
			"Unknown"
		],
		"dataTypes": [
			"phi",
			"pii",
			"pci",
			"employeeInformation",
			"internalProprietaryInfomation"
		],
		"storageLocationAccessTypes":[
			"onPrem",
			"vendorDataCenter",
			"thirdPartyDataCenter",
			"workstation",
			"mobileDevice"
		],
		"networkAccessTypes": [
			"onSiteAccess",
			"infrastructureAccess",
			"databaseOrApplicationAccess",
			"receiptOfData",
			"noAccessToNetwork"
		],
		"estimatedAccessToVolumeOfRecords": "1001-10000",
		"inherentVendorRiskRating": "medium"
	},
	"scopingInformation": {
		"obtainScopingInformation": "providedScope"
	},
	"securityControlInformation": {
		"obtainSecurityControlInformation": "corlContactVendor"
	},
	"comments": ""
}

Configure API Authentication

The API authentication is JWT bearer token. In most platforms, this authentication is a header that follows the pattern below:

-h Authorization Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkJQRjQ0d2drQU5qc1E4OWZrRkJSZiJ9.eyJodHRwczovL2V4Y2hhbmdlLmNvcmx0ZWNoLmNvbS9zZXNzaW9uX2lkIjoiMWNkZDc2ZDAtYmZlNC0xMWYwLThhYjYtMDU5MzRjYjU2ODM0IiwiaXNzIjoiaHR0cHM6Ly91YXQtbG9naW4uY29ybHRlY2guY29tLyIsInN1YiI6IkRwckw2MGYxWnNxZnpSM1NUZ0dlUWt0V3lLZk1zMzJJQGNsaWVudHMiLCJhdWdGVjaC5jb20iLCJpYXQiOjE3NjI5NjQ2OTAsImV4cCI6MTc2Mjk5MzQ5MCwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwiYXpwIjoiRHByTDYwZjFac3FmelIzU1RnR2VRa3RXeUtmTXMzMkkifQ.ODj05dRWKR3_KCCQl9yJzB9VZZ-FeVdew40SEXDdj0P9Tembo2_f4TyEWTrgj_PsTAF2ZJj6YUM4NB0OQPz57GXFkiF61WExBlAxixWpjDjACdrDn6tHiXNItFAO3QFOHK3Yg4gAsc0GVYTbhqFlxtBpAEt-X7VmGN5bPTpc8sn-gaTxD58TQHCinuV-c7-nVaj5W

Store API Response Attributes in GRC Platform

CORL recommends to capture response field values within the GRC platform for additional troubleshooting as needed.

Assessment Processing Correlation Identifier (assessmentCreationProcessingCorrelationId)

Automating Assessment Requests