Configuring Custom Evidence Integrations via APIs

Evidence integrations help to build custom integrations that feed content into evidence tasks. This can be utilized in cases where we do not provide out-of-the-box integrations with a third-party system for automated evidence collection.

The OneTrust integration ecosystem includes a catalog of pre-integrated applications that make it easy to incorporate privacy by design into your existing application workflows. Additionally, the OneTrust platform enables you to set up a custom integration with systems via APIs, system integrations, and more.

Prerequisites

  • Administrator-level access to the given third-party system console to obtain account details (e.g. Client ID, authorization keys, etc.).

  • Working knowledge or familiarity with your third-party system's supported APIs. Leverage their API or developer documentation for additional guidance.

  • Credentials set up to connect/authenticate third-party systems and OneTrust. For more information, see Configuring Integration Credentials.

To configure a custom workflow

Important:

Before creating your workflow template, you need to first configure credentials that will allow OneTrust to access the application for the integration. For more information, see Configuring Integration Credentials.

In order to begin creating a custom workflow, you will begin on the Integrations menu by clicking on Integrations. The Workflow Builder screen will appear when new workflows are created. You can also access the Workflow Builder screen by clicking on the name of the workflow on the Integrations screen.

  1. On the Workflow Builder screen, select the Evidence Collection module trigger.


  2. Select the Evidence Task Events trigger.
  3. Configure the workflow conditions. For more information, see Workflow Conditions Screen Reference.
  4. Click the Done button to save your conditions.
  5. Click the Add Action button.

    The Add Action section appears.

  6. Select the OneTrust action tab.


  7. Choose the Evidence Collection module.
  8. Select the POST Attach file(s) to an Evidence Task API.
    Note:

    This API allows you to attach files, notes, or URLs to an evidence task.

  9. Configure the action request as needed.


    Section

    Field

    Description

    PathParams

    EvidenceTaskImplementationId

    Click the Add icon and select the evidence task ID.

    Headers

    Content-Type

    Click the Add icon and select the content-type.

    Headers

    Body

    The request body is pre-configured. You can add free marker templates by clicking the Add icon.

    Note:

    If the Document Type = File, you should include the Collection Date, Document Type, Evidence Task Implementation Document Request (Attachment ID, Name). If the Document Type = URL, you should include the Document Type, URL, and Name. If the Document Type = Note, you should include the Document Type, Name, and Note.
  10. Click the Finish button.
  11. Click the Save button to save the changes made to the workflow.
  12. Add and configure additional steps as needed. The steps in a workflow are conducted sequentially.
    Tip:

    You can add multiple actions based on your organizational requirements. For example:

    • Download a file from file transfer protocol (FTP) and attach it to the evidence task.

    • Pull raw data from any system, create a file out of those data, and attach the file to evidence task.

    • Get evidence from SharePoint or any other third-party system and attach those to evidence tasks.

  13. Click the Finish button.
  14. Click the Activate button.

    The confirmation modal appears.

  15. Click the OK button to save and activate your workflow.

Workflow Conditions Screen Reference

The workflow conditions are used to initiate certain actions if any or all of the conditions are met. You can create individual conditions or combine conditions using the Add Condition button to create complex automation logic. When combining multiple conditions, you can choose whether any of the conditions can be met to initiate the rule action or if all conditions must be met to initiate the action. This section explains how to configure conditions to initiate workflow actions.



Section

Field

Description

Conditions

ANY

If you select ANY, the workflow will be initiated if any one of the conditions are met.

ALL

If you select ALL, the workflow will only be initiated if all of the conditions are met.

Condition Block

Conditions

Select the condition(s) that must be met before initiating the workflow action. Select ANY if the workflow should be initiated if any one of the conditions are met. Select ALL if the workflow should only be initiated if all of the conditions are met.

The following conditions are available to configure:

Evidence Task ID - This trigger generates an event each time a new evidence task ID is created.

Note:

The Evidence Task ID must be entered in the Value field if this condition is selected. To locate the ID, navigate to the Evidence Task Details screen and copy the ID from the URL.

Days After Evidence Interval Start Date - This trigger generates an event at the number of days defined after the evidence interval start date.

Days Before Evidence Interval End Date - This trigger generates an event at the number of days defined before the evidence interval end date.

Operator

Select the relationship that must be met between the field and value. The following operators are available:

  • Contains Any

  • Does Not Contain

  • Equal To

  • Not Equal To

  • Greater Than

  • Greater Than Or Equal To

  • Less Than

  • Less Than Or Equal To

  • Starts With

  • Ends With

Value

Select the value that applies to your condition(s).

Add Condition Block

N/A

Click the Add Condition button to add more conditions to the workflow rule.

Custom Evidence Integration Workflow Use Case

Use Case: Pull data from a third-party system, create a file out of the data, and attach the data to an evidence task when the module trigger condition satisfies.

Steps to Achieve Use Case

  1. On the Integration menu, select Integrations. The Integrations screen appears.

  2. Click the Add New button. The Create Workflow modal appears.

  3. Complete the required fields. For more information, see Create Workflow Modal Reference.

  4. Click the Create button.

  5. Configure a module trigger and trigger condition. See steps 1-4 in the To configure a custom workflow section.

  6. Click the Save button.

  7. Click the Add Action button. The Add Action section appears.

  8. On the System tab, select Download File from FTP.

  9. Select Create New Credential.

  10. Select File Share in the Connector Type field, and complete the remaining fields.



    Note:

    The Server, Port, User Name, and Password fields will be specific to each user.

  11. Click the Next button.

  12. Enter the location of the file in the Path field.



  13. Click the Finish button.

  14. Click the Save button to save your changes.

  15. Click the Edit icon next to the FTP action.



  16. Navigate to the Response tab to view the sample data.



  17. Click the Finish button.

  18. Optional: Add a new action by selecting Logic > Apply to Each. Complete the field, and click the Finish button.

    Note:

    The apply to each logic should be used if you would like to use each file retrieved from the FTP. Otherwise, you will get only one file. This can then be used in the request body.

  19. Add a new action by selecting OneTrust > Evidence Collection > POST Attach file(s) to an Evidence Task. Provide the Evidence Task Implementation ID and send the required filed (Collection Date, Document Type, Evidence Task Implementation Document Request (Attachment Id, Name)) for file upload in Request Body.



    Note:

    The document type can be File, Notes, or URL.

  20. Add a new action by selecting Logic > Create File and provide required details for the create file action. Use the free marker template for the Value field to get data from the response of the last action (ex. ${(request.http_0)!}) and the Select List Object value as step.http_0.list.



  21. To upload the file created in the previous step, use the free marker templates in place of Attachment ID and Name. This way, when the workflow gets executed sequentially at the last step of upload attachment, the created file ID and name will be replaced with the runtime value.



    Note:

    To use free marker templates in the body, click the Add icon next to the Body field. After using the free marker template, the request body looks like the image below.



  22. Click the Save and then Finish button.

  23. When the daily scheduled events are published from the control service and this trigger condition satisfies with the published evidence data, this workflow will be executed and the attachment will be uploaded for the evidence task.

Execution of Workflow

  • OneTrust has configured a scheduled job at 11:30 AM (UTC). This job will trigger control microservice to publish all evidence data with the three fields listed below to the integration-manager service.

    1. Evidence Task ID

    2. Days After Interval Start Date

    3. Days Before Interval End Date

  • After receiving the request, the integration manager will evaluate the trigger condition configured above. If any trigger condition satisfies with the evidence data, it will begin executing the integration workflow.

API Replica of Daily Scheduler

OneTrust has added an API which does the job of the daily scheduler to trigger the control service for publishing the evidence task events to the integration service.

Http Request

POST

URL

https://lkgb.1trust.app/api/control/v1/evidences/integrations/triggerEvidenceCollectionReminderEvent

Request Body

N/A

Authorization Header

Send bearer token and cookies as part of the request header.

Create Workflow Modal Reference



Field
Description
Workflow Name

Enter a workflow name.

Description

Enter a brief description that describes the workflow.

System

Select Generic.

Notification Email

Enter an email address that will receive the notification email.