OneTrust

The OneTrust connector enables automated interactions with OneTrust's assessment and management features, facilitating streamlined compliance and risk management processes.

OneTrust is a comprehensive platform for privacy, security, and third-party risk management. This connector enables seamless integration with OneTrust, allowing users to automate the retrieval, modification, and management of assessments directly within Swimlane Turbine. By leveraging this connector, organizations can enhance their compliance workflows, streamline risk assessments, and ensure timely responses to privacy and security issues.

Prerequisites

To effectively utilize the OneTrust connector within Swimlane Turbine, ensure you have the following prerequisites:

OAuth2 client credentials for secure authentication, which include:

URL: Endpoint for OneTrust API access

Client ID: Unique identifier for OAuth2 authentication

Client Secret: Confidential key for OAuth2 authentication

Alternatively, an API key authentication method is available, requiring:

URL: Endpoint for OneTrust API access

API Key: Secret token to authenticate API requests

Capabilities

This connector provides the following capabilities:

Get Assessment

Get List of Assessments

Get List of Assessments by Criteria

Launch Assessment

Modify Assessment

Reassign Assessment

Set Primary Record

OAuth 2.0 Scopes

Scope to API Assignments

The following table details the APIs an external system will access when the corresponding scope is defined for the respective client credential.

OAuth Scope	Action
ASSESSMENT_READ	Get Assessment
ASSESSMENT_READ	Get List of Assessments
ASSESSMENT	Launch Assessment

Notes

API Documentation

Link for Authentication

Configurations

OneTrust API Key Authentication

Authenticates using an API Key

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
x-apikey	API key	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

OneTrust Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token_url		string	Optional
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Get Assessment

Retrieve detailed information for a specific OneTrust assessment, including respondents, questions, and risks.

Endpoint

URL: /api/assessment/v2/assessments/{{assessmentId}}/export

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.assessmentId	string	Required	ID of an assessment.
parameters.ExcludeSkippedQuestions	boolean	Optional	Indicates whether skipped questions are included in the response payload. When set to True, questions on the assessment that are hidden by skip or show logic will be excluded from the response payload. When set to False, questions on the assessment that are hidden by skip or show logic will be included in the response payload with the "hidden" boolean set to True.

Input Example

{"parameters":{"ExcludeSkippedQuestions":false},"path_parameters":{"assessmentId":"f47ac10b-58cc-4372-a567-0e02b2c3d479"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
approvers	array	Output field: approvers
approvers.approvalState	string	Output field: approvers.approvalState
approvers.approvedOn	object	Output field: approvers.approvedOn
approvers.id	string	Unique identifier
approvers.name	string	Name of the resource
assessmentId	string	Unique identifier
assessmentNumber	number	Output field: assessmentNumber
completedOn	string	Output field: completedOn
createdBy	object	Output field: createdBy
createdBy.id	string	Unique identifier
createdBy.name	string	Name of the resource
createdDT	string	Output field: createdDT
description	string	Output field: description
highRisk	number	Output field: highRisk
inherentRiskScore	number	Score value
lastUpdated	string	Output field: lastUpdated
lowRisk	number	Output field: lowRisk
mediumRisk	number	Output field: mediumRisk
name	string	Name of the resource
openRiskCount	number	Count value
orgGroup	object	Output field: orgGroup
orgGroup.id	string	Unique identifier
orgGroup.name	string	Name of the resource

Output Example

{"approvers":[{"approvalState":"string","approvedOn":{},"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"}],"assessmentId":"string","assessmentNumber":123,"completedOn":"string","createdBy":{"id":"12345678-1234-1234-1234-123456789abc","name":"Example Name"},"createdDT":"string","description":"string","highRisk":123,"inherentRiskScore":123,"lastUpdated":"string","lowRisk":123,"mediumRisk":123,"name":"Example Name","openRiskCount":123,"orgGroup":{"id":"12345678-1234-1234-1234-12345...

Get List of Assessments

Retrieve a comprehensive list of all assessments with basic details from OneTrust.

Endpoint

URL: /api/assessment/v2/assessments

Method: GET

Input

Argument Name	Type	Required	Description
parameters.assessmentStatuses	array	Optional	Status of an assessment.
parameters.assessmentArchivalState	string	Optional	Parameter to retrieve a list of Active/Archived or both Active and Archived assessments.
parameters.page	number	Optional	Page number of the results list (0…N).
parameters.size	number	Optional	Number of records per page (0…N).

Input Example

{"parameters":{"assessmentStatuses":["NOT_STARTED"],"assessmentArchivalState":"ALL","page":0,"size":20}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
content	array	Response content
content.assessmentId	string	Unique identifier
content.createDt	string	Response content
content.inherentRiskScore	number	Response content
content.lastUpdated	string	Response content
content.name	string	Name of the resource
content.number	number	Response content
content.openRiskCount	number	Response content
content.orgGroupName	string	Name of the resource
content.primaryInventoryDetails	object	Response content
content.primaryInventoryDetails.primaryInventoryId	string	Unique identifier
content.primaryInventoryDetails.primaryInventoryName	string	Name of the resource
content.primaryInventoryDetails.primaryInventoryNumber	number	Response content
content.residualRiskScore	number	Unique identifier
content.result	string	Response content
content.resultId	string	Unique identifier
content.resultName	string	Name of the resource
content.state	string	Response content
content.status	string	Status value
content.tags	array	Response content
content.tags.file_name	string	Name of the resource
content.tags.file	string	Response content
content.targetRiskScore	object	Response content

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"OK","json_body":{"content":[{}],"page":{"number":0,"size":1,"totalElements":50,"totalPages":50}}}

Get List of Assessments by Criteria

Retrieve a comprehensive list of assessments from OneTrust, with optional filtering based on specific criteria.

Endpoint

URL: /api/assessment/v3/assessments/list

Method: POST

Input

Argument Name	Type	Required	Description
parameters.assessmentArchivalState	string	Optional	Assessment Archival State.
parameters.assessmentStatuses	array	Optional	Assessment Statuses.
parameters.templateTypes	array	Optional	Template Types.
parameters.page	number	Optional	Page number of the results list (0…N).
parameters.size	number	Optional	Number of records per page (0…N).
parameters.sort	string	Optional	returns the assessment list in sorted order. By default returns in descending order of Assessment number.
filterCriteria	array	Optional	Parameter for Get List of Assessments by Criteria
filterCriteria.field	string	Optional	Name of the property to be filtered on.
filterCriteria.operation	string	Optional	Parameter for Get List of Assessments by Criteria
filterCriteria.toValue	array	Optional	Used for deletedDate, deadline filters.
filterCriteria.value	array	Optional	Expected value of the provided field, can also be a list of values. For deadline and deletedDate, we can use a string (Option 1) and for rest of the parameters, use array of strings (Option 2). As an example, the value for deadline or deletedDate could be "2023-08-27T18:30:00.000Z".

Input Example

{"parameters":{"assessmentArchivalState":"ALL","page":0,"size":10,"sort":"number,desc"},"json_body":{"filterCriteria":[{"field":"respondentId","operation":"=","toValue":["aabdaf95-7eb3-4583-986e-d5d3868d4c14"],"value":["aabdaf95-7eb3-4583-986e-d5d3868d4c14"]}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
content	array	Response content
content.approvalStageName	string	Name of the resource
content.approvers	array	Response content
content.approvers.assigneeType	object	Type of the resource
content.approvers.deleted	boolean	Response content
content.approvers.email	object	Response content
content.approvers.fullName	string	Name of the resource
content.approvers.id	string	Unique identifier
content.assessmentId	string	Unique identifier
content.assessmentRiskLevelName	string	Name of the resource
content.attestationRequired	boolean	Response content
content.badgeColor	string	Response content
content.canResendLink	boolean	Response content
content.createDT	string	Response content
content.createdBy	string	Response content
content.deadline	string	Response content
content.editAllResponsesWhenInProgress	boolean	Response content
content.inherentRiskLevelName	string	Name of the resource
content.name	string	Name of the resource
content.number	number	Response content
content.openInfoRequestCount	number	Response content
content.openRiskCount	number	Response content
content.orgGroupId	string	Unique identifier

Output Example

{"status_code":200,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"OK","json_body":{"content":[{},{}],"page":{"number":0,"size":10,"totalElements":2,"totalPages":1}}}

Launch Assessment

Initiates a new assessment in OneTrust with specified details and assigns it to selected respondents.

Endpoint

URL: /api/assessment/v2/assessments

Method: POST

Input

Argument Name	Type	Required	Description
approverId	string	Optional	ID of the user/user-group who should be assigned as the Approver of the assessment.
approverName	string	Optional	Name of the user/user-group who should be assigned as the approver of the assessment.
deadline	string	Optional	Date by which the assessment should be completed. The format is YYYY-MM-DDTHH:MM:SS.FFFZ.
description	string	Optional	Description of the assessment.
inventoryDetails	object	Optional	Parameter for Launch Assessment
inventoryDetails.inventoryId	string	Required	ID of the primary record of the assessment.
inventoryDetails.inventoryName	string	Required	Name of the primary record of the assessment.
inventoryDetails.inventoryTypeId	number	Required	ID of the Primary Record Type (Assets, Processing Activities, Vendors, etc.).Values for inventoryTypeId-Assets = ''20''; Processing Activities = ''30''; Vendors = ''50''; Entities = ''60''.
name	string	Optional	Name of the assessment.
orgGroupId	string	Optional	ID of the organization group that should be assigned to the assessment.
orgGroupName	string	Optional	Name of the organization group that should be assigned to the assessment.
reminder	number	Optional	Number of days before the deadline to send an automatic reminder to the respondent.
respondentCreationType	string	Optional	Indicates whether new respondents are created as Invited Users or Project Respondents when launching an assessment.
respondents	array	Optional	List of respondents assigned to the assessment.
respondents.comment	string	Optional	Comments that will be provided to the respondent(s) in an email notification.
respondents.respondentId	string	Optional	ID of the user/user-group to assign to the assessment as a respondent.
respondents.respondentName	string	Required	Name of the user/user-group to assign as a respondent.
respondents.sectionId	string	Optional	ID of a section within the assessment.
ruleId	string	Optional	This parameter value can be null.
templateId	string	Optional	ID used to launch an assessment using a specific version of a template.
templateRootVersionId	string	Optional	ID used to launch an assessment using the latest published version of a template (recommended to use in integrations).
triggeredByAssessmentId	string	Optional	The unique identifier of the assessment that triggered this action.
triggeredByAssessmentName	string	Optional	The name of the assessment that triggered this action.

Input Example

{"json_body":{"approverId":"","approverName":"","deadline":"2024-09-30T17:00:00.000Z","description":"","inventoryDetails":{"inventoryId":"a3c5e4b1-39cd-4b2a-a8e4-1c347890c482","inventoryName":"Laptop - Dell XPS 13","inventoryTypeId":20},"name":"","orgGroupId":"","orgGroupName":"","reminder":9223372036854776000,"respondentCreationType":"","respondents":[{"comment":"","respondentId":"","respondentName":"[email protected]","sectionId":""}],"ruleId":"","templateId":"","templateRootVersionId":"","triggeredByAssessmentId":"","triggeredByAssessmentName":""}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":201,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"Created","json_body":{}}

Modify Assessment

Update an assessment's name, description, deadline, and reminder in OneTrust using the provided assessmentId.

Endpoint

URL: /api/assessment/v2/assessments/{{assessmentId}}/metadata

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.assessmentId	string	Required	Parameters for the Modify Assessment action
deadline	string	Optional	Date by which the assessment must be completed. The date format is YYYY-MM-DDTHH:MM:SS.FFFZ.
description	string	Optional	Description of the assessment.
name	string	Optional	Name of the assessment.
reminder	number	Optional	Number of days before the deadline to send an automatic reminder to the respondent.

Input Example

{"json_body":{"deadline":"2021-04-30T04:00:00:000Z","reminder":5},"path_parameters":{"assessmentId":"550e8400-e29b-41d4-a716-446655440000"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":204,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"No Content","json_body":{}}

Reassign Assessment

Reassign the organization, approvers, and respondents for a specific OneTrust assessment using the provided assessmentId.

Endpoint

URL: /api/assessment/v2/assessments/{{assessmentId}}/reassign

Method: PUT

Input

Argument Name	Type	Required	Description
path_parameters.assessmentId	string	Required	ID of an assessment.
approvers	array	Optional	The details of the user who is assigned as an approver to the assessment.
approvers.approverId	string	Optional	ID of the user to assign to the assessment as an approver.
approvers.approverName	string	Optional	Name of the user to assign to the assessment as a respondent.
approvers.comment	string	Optional	Comments that will be provided to the approver in an email notification.
approvers.workflowStageIds	array	Optional	User will be added as an approver for the workflowStageIds mentioned in the request. If the workflowStageIds is empty then the user will be added as an approver to all the stages.
orgGroupId	string	Optional	ID of the organization group that should be reassigned to the assessment.
respondentCreationType	string	Optional	Use this field to select whether new respondents are created as Invited Users or Project Respondents.
respondents	array	Optional	Used to indicate whether the new respondents are created as Invited Users or Project Respondents.
respondents.comment	string	Optional	Comments that will be provided to the respondent(s) in an email notification.
respondents.respondentId	string	Optional	ID of the user/user-group to assign to the assessment as a respondent.
respondents.respondentName	string	Required	Name of the user/user-group to assign as a respondent.
respondents.sectionId	string	Optional	ID of a section within the assessment.

Input Example

{"json_body":{"approvers":[{"approverId":"3b241101-e2bb-4255-8caf-4136c566a964"}],"respondentCreationType":"INVITED","respondents":{"respondentName":"[email protected]"}},"path_parameters":{"assessmentId":"9d0e0c1e-cb30-4a6b-95ad-0e02b2c3d479"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":204,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"No Content","json_body":{}}

Set Primary Record

Edit or assign a primary record to an assessment in OneTrust using the provided assessmentId and primary record details.

Endpoint

URL: /api/assessment/v2/assessments/{{assessmentId}}/primary-records

Method: PUT

Input

Argument Name	Type	Required	Description
path_parameters.assessmentId	string	Required	Id of an assessment.
primaryRecordIds	array	Optional	Unique ID of the primary record.
primaryRecordType	string	Optional	Type of record designated as the main purpose of an assessment.

Input Example

{"json_body":{"primaryRecordIds":["ACR-98765","ACR-65432","ACR-32109"],"primaryRecordType":"ASSETS"},"path_parameters":{"assessmentId":"123e4567-e89b-12d3-a456-426614174000"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":204,"response_headers":{"content-length":"140","content-type":"application/json","Date":"Mon, 17 Jun 2024 20:37:23 GMT"},"reason":"No Content","json_body":{}}

Response Headers

Header	Description	Example
content-length	The length of the response body in bytes	140
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Mon, 17 Jun 2024 20:37:23 GMT