Introduction to the OneTrust Integrations Platform

OneTrust's Integrations Platform is a very powerful and flexible tool which can be used to extend the capabilities that OneTrust provides, interoperate with third-party systems, and run scheduled tasks.

This article is intended for a technical audience who is readily familiar with integration concepts.

Note:

For additional content on OneTrust Integrations, see Getting Started with OneTrust Integrations.

What is Low/No-Code?

Low/No-Code environments, are programming environments that leverage pre-built building blocks that allow you to glue together predefined behaviors to achieve a desired result. OneTrust's Integrations Platform is a Low-Code environment.

OneTrust Integrations Platform

In OneTrust's Integrations Platform we have a combination of a block builder interface and the capability to also write code using a templating language called Apache FreeMarker to process and transform data in certain contexts.

Building an integration in OneTrust can be described in two parts:

Trigger
Behavior

Integration Triggers

The trigger is what initiates the integration workflow, these can be system events, a request from an external system, a request from another integration workflow, or a regularly scheduled operation.

System Events

System events include triggers such as:

Assessment Launched, Assessment Submitted, Assessment Completed
Inventory Record Created, Updated, or Deleted
Data Subject Request Created
Consent Profile Updated

These system events do not have the ability to customize the information received from the event, but do provide the ability to filter events based on the information provided by the specific trigger. For example:

Filter Assessment Completed events for a specific Template, when the Assessment Result is Approved
Filter Data Subject Consent updates for a specific Collection Point
Filter DSAR cases from Brazil

Scheduled Trigger

One of the available triggers is to set a specific cadence of the integration running. This can be set to:

Hourly
Daily
Weekly
Monthly
Yearly

Once the cadence is set, you can define additional parameters, such as time and day of execution.

Webhook

A webhook is an externally callable endpoint, for which you can configure an expected payload to then use as input throughout the integration workflow. The URL provided on the trigger needs to be used to make an HTTP POST request against this workflow. An OAuth Token with the INTEGRATION scope is required to authenticate against this endpoint.

Subflow

Similar to webhooks described above, but internal to the OneTrust integration platform. Any OneTrust integration workflow can invoke an activated Subflow and provide a payload to it.

Behavior - Available Building Blocks

To actually perform operations, either within OneTrust, or externally, you need to define the behavior through the combination of the available actions the platform provides. The following are an exhaustive list of the available blocks, their usage and capabilities.

OneTrust Module-Specific Actions

Our builder provides access to a significant portion of our Public APIs as pre-seeded actions.While not every endpoint is included on these actions, the vast majority of the commonly used operations are included.

The advantage of using pre-seeded actions, is that Authentication against the API is already covered, and it provides, most of the times, a simple form to insert the relevant for each of the available parameters of the API request.In cases in which the payloads required for the endpoints are more complicated, a pre-seeded payload body will be included, and you can modify it to your specific needs.

In cases in which the required OneTrust API is not available, a custom HTTP request must be defined, these are covered in the next section.

Detailed documentation regarding OneTrust's API can be found in our Developer Portal.

System-Specific Actions

While creating integrations in OneTrust, you have the ability to select a System you're going to be integrating against.

In some cases, specific systems have already pre-seeded actions, similar to the ones described for OneTrust, which serve for the most relevant use cases for integrating OneTrust with that particular platform. By using these, you'll get a simplified form to input the necessary information for interacting with the specific system.

However, in some cases, integration workflows require a bit more flexibility. When flexibility is required, there is a Generic system available. This system includes the ability to perform HTTP requests, handle files, and perform database requests.

Logic Actions

Apart from requests to external systems and OneTrust itself, there is the possibility to control the flow of your integrations with Logic Actions. These include:

Conditionals
Loops (Apply to Each, Pagination, and Do/While)

You can also define fully custom behavior in code blocks with Data Transformations.

Additionally, there some extra capabilities:

Send Email
Create File
Read File into List
Invoke a Subflow

Customizing Data and Reusing Responses from Prior Actions

In our Integrations platform, while there's a lot that's doable without customization, any complex workflow will require some degrees of customization. To achieve this, we need to look into how we can embed FreeMarker into actions. While the dedicated action to perform FreeMarker transformations are the Data Transformation actions, FreeMarker can actually be embedded in any text input for any action. The most common embed will be for referencing data from the Event Trigger or from a previous action. This can be done like follows:

Note:

You may notice in the snippet above the ! at the end of the attribute names. What this operator does is to provide a default value when none is available for this attribute. This is necessary due to FreeMarker failing out in case of encountering a null value at any point of the execution.

PYTHON

${event.payload.someAttributeInThePayload!} <#-- An Attribute from the Event -->

${step.http_0.someAttributeFromThePriorHttpRequest!} <#-- An Attribute from the first HTTP action -->

${step.applyEach_0.someAttributeFromASingleElement!} <#-- An Attribute from the curernt element in an Apply To Each loop --> 

${step.applyEach_0['some field with irregular naming']!} <#-- In cases where the name contains invalid characters for a direct accessor, it can be accessed with the same syntax to access a dict key in Python -->

${event.payload.someAttributeInThePayload!} <#-- An Attribute from the Event -->

${step.http_0.someAttributeFromThePriorHttpRequest!} <#-- An Attribute from the first HTTP action -->

${step.applyEach_0.someAttributeFromASingleElement!} <#-- An Attribute from the curernt element in an Apply To Each loop --> 

${step.applyEach_0['some field with irregular naming']!} <#-- In cases where the name contains invalid characters for a direct accessor, it can be accessed with the same syntax to access a dict key in Python -->

Setting Up Requests for Data Transformations

In order for data to be correctly usable through embedded Data Transformations (any text field in any action), or the explicit Data Transformation actions, you need to provide sample responses for each action. By doing this, you allow OneTrust Integrations' auto-complete engine to index the available attributes. While it is not necessary, integrations will work regardless, it removes a lot of effort when figuring out how to fetch a specific attribute from a prior action.

Loops

JSON

<#list step.http_0.someList as someItem> 
	<#-- Here you can process each individual item within the list -->
</#list>

<#-- most common loop use case is to refine a list of items into a simpler list --> 
{
	"items": [ 
	<#list step.http_0.someList as someItem>
	{
		"name": "${someItem.name}",
		"id": "${someItem.id}" 
	}<#sep>, <#-- #sep is a FreeMarker directive which in case of a next item available, will add the separator, otherwise not --> 
	</#list>
	]
}

<#list step.http_0.someList as someItem> 
	<#-- Here you can process each individual item within the list -->
</#list>

<#-- most common loop use case is to refine a list of items into a simpler list --> 
{
	"items": [ 
	<#list step.http_0.someList as someItem>
	{
		"name": "${someItem.name}",
		"id": "${someItem.id}" 
	}<#sep>, <#-- #sep is a FreeMarker directive which in case of a next item available, will add the separator, otherwise not --> 
	</#list>
	]
}

Conditionals

CODE

<#if step.http_0.someBoolean>
	<#-- Condition --> 
<#elseif step.http_0.someValue == "something" && !step.http_1.anotherThing>
	<#-- Another Condition -->
<#else>
	<#-- Conditions not matched -->
</#if>

<#if step.http_0.someBoolean>
	<#-- Condition --> 
<#elseif step.http_0.someValue == "something" && !step.http_1.anotherThing>
	<#-- Another Condition -->
<#else>
	<#-- Conditions not matched -->
</#if>

Of course, these can be used in conjunction, and conditions can be more complicated.

Operators in Conditionals

In cases where you need to perform comparisons such as < (lower than), <= (lower than or equal to), > (greater than), and >= (greater than or equal to). Due to restrictions in HTML processing, these operators need to be replaced with lt, lte, gt, and gte respectively. For example:

CODE

<#if foo gte 5>

<#if foo gte 5>

Variables in FreeMarker

There are two different ways of creating variables in FreeMarker, one that is provided by FreeMarker, and one that is OneTrust specific.

FreeMarker

JSON

<#assign foo = "some value">

<#-- The variable can later be used as: --> 
Foo's value: ${foo}

<#if foo == "some value">

<#assign foo = "some value">

<#-- The variable can later be used as: --> 
Foo's value: ${foo}

<#if foo == "some value">

The FreeMarker assignment is extremely useful for variables that are only required within the current action, and will not be necessary in a subsequent action. Examples of these can be intermediary values, such as those needed to perform a calculation or as a step in a larger operation.

OneTrust

JSON

${set('foo', "someValue")}

<#-- This can then be used as: -->
Foo's value: ${get('foo')}

<#if get('foo') == "some value">

${set('foo', "someValue")}

<#-- This can then be used as: -->
Foo's value: ${get('foo')}

<#if get('foo') == "some value">

OneTrust's assignment is available to share data across actions, as these can be assigned and accessed across multiple actions. This assignment is extremely useful in cases in which the data requires to be used across different steps of your integration. In cases of working with lists or dictionaries as the values, there are additional operations available, which you can reference here.