Troubleshooting Common Issues in OneTrust Integrations

This article is intended to educate users on how to troubleshoot basic to intricate integrations and address production issues commonly reported by other OneTrust customers. If you have further questions that are not answered here or in other myOneTrust articles, please contact your account executive or OneTrust Support to start a new case.

Reading Error Messages

Header Logs

When reading detailed logs, the first sign of an issue appears highlighted in red. If further troubleshooting is needed, refer to the following sections about requests, responses, and other technical areas.

For more information about access logs, see Using Integration Logs.



Request Actions

The first portion of the log represents the step or action name shown in the Integration Builder. The second is the URL or the request details contains additional details on the executed action. The third is the body, a.k.a. a payload, provided for the action that may contain one or more functions.

Use this section to identify issues with the URL, either from an OneTrust API or from a third-party system, as well as check for discrepancies in the expected payload by comparing with the Body field in the Request tab of the action. After resolving these you can reprocess the failure log.



Responses

Beyond the request portion of the log, the response includes the outcome and status of the action that is executed. The body will contains the details of the action's outcome or output. Compare this section against the expected response sample seen in the action's Response tab.



Error Codes

The error codes for OneTrust public API endpoints along with the call's included body params are available on the Developer Portal.



Code

Description

2XX

Success. Request was successful.

3XX

Redirection. Requires additional action to complete the request.

400

Bad Request. Due to incorrect syntax or deceptive routing practices.

401

Unauthorized. Validate your credentials to ensure they are correct and not expired.

403

Forbidden. Request received but not authorized.

404

Not Found or Invalid URL. Validate the URL and check for any changes or availability issues.

408

Timed Out. Due to temporary outage or large payload sizes. Ensure payload is does not exceed and reprocess.

410

Not Found/Gone. Target resource is not available.

429

Rate Limiting. For more information, see API Rate Limits on the Developer Portal.

500

Internal Gateway. Reprocess to account for intermittent issues.

Nulls

Sometimes input for the specific action could be originating from previous action that's producing the null. In the error log locate the previous step to perform troubleshooting steps. It is possible that the desired payload for which the data-type is not support for the given integration. You can use freemarker variables to include null data-type in the given action body.

Workflow Logic

Incorrect Freemarker

One of the most common and continual issues faced will be freemarker errors resulting from syntax issues.

  1. Obtain workflow JSON and logs of the failed issue.

  2. Refer to failed responses to inspect syntax issues.

  3. Use Online Freemarker Template Tester to debug syntax issues.

  4. Import workflow into control environment to attempt end-to-end flow.

  5. Obtain provided payload from logs or sample response to use as test payload for verification and transformation.

Note:

For more information on this topic, see Using Integration Logs and Testing Workflow Actions and Saving Sample Payloads.

Invalid References to Previous Actions

Commons issues here will be incorrectly referring to certain fields as well as Apply to Each references.

  1. Obtain workflow JSON and logs of the failed issue.

  2. Determine which payload is causing the issue.

    Tip:

    With DSAR and Consent info used in other systems; references will pertain to the data subject details.

  3. If the issue is not clear from the error logs, visually inspect each action to verify references. See the following bolded code as an example:

    JSON 
    {
"http_0:Https POST request": {
"messageStatus": "FAILURE",
"request": {
"url": "demo_url.com",
"body": "IntegrationEventData(integrationId=null, workflowId=ebe00fa1-b321-4fec-b4bf-230a1a527562, messageKey=1ead5a4c-f986-463a-9e1a-9d8c99aa8d13, messageSequenceNumber=null, deDuplicationStrategy=PROCESS_ALL, reprocessCount=0, isBulk=false, headers=null, parentWorkflowId=677de650-b4a0-4fd0-bd0c-dfef38252ad7, throttlingDelayMillis=null, blobStoreLocation=19157/ebe00fa1-b321-4fec-b4bf-230a1a527562/1ead5a4c-f986-463a-9e1a-9d8c99aa8d13, blobStoreFileSize=0, isCompressed=false, referenceMessage=false, isManualProcess=true, validationErrors=null)",
"statusCode": null,
"statusText": null,
"failureCause": null,
"headers": {},
"properties": {
"oc_node_label": "start",
"x_oc_tenantId": "4129",
"x_oc_traceSequence": "2",
"x_oc_processType": "TRANSFORM",
"x_oc_graphVertex": "com.onetrust.integrationmanager.domain.graph.GraphVertex@631b6788",
"x_oc_continueOnError": "NONE",
"x_oc_wf_start_time": "2022-06-14T17:08:06.725436Z",
"x_oc_isManualProcess": "true",
"x_oc_workflowId": "ebe00fa1-b321-4fec-b4bf-230a1a527562",
"x_oc_total_routes": "3",
"x_oc_wf_timeout": "2022-06-14T17:33:06.725430Z",
"x_oc_isReprocessed": "false",
"x_oc_isDLQEnabled": "true",
"x_oc_defaultDlqAction": "REPROCESS"
}
}
}
}
    Note:

    For more information on reading integration logs and detailed logs, see Using Integration Logs.

  4. Import workflow into control environment to test and supply sample payloads to run against.

  5. Change references or ensure references exist in previous actions.

    Note:

    Sometimes an action is added then deleted and someone manually types in the referenced action without accounting for that action having a difference action number now.

    Apply to Each issues will mainly require just saving and reloading the apply to each action as well as making sure it references an object that is a list. For more information, see Transforming Responses for Use in Apply to Each Logic.

Multiple Apply to Each Loops

Integration workflows can only have one Apply to Each logic action per workflow. This is designed to avoid excessive processing time, as workflows processing for more than 25 minutes will fail. OneTrust recommends to send a second Apply To Each loop to process in a subflow workflow.

Incorrectly Transforming/Handling Payloads

  1. Obtain workflow JSON and logs of the failed issue.

  2. Identify the payload format that are being transformed and sent.

  3. Inspect the payload and sample responses to verify the payload structure.

    Important:

    This will be the main source of the issues as many times the structure will not match the response provided

    If these don’t match when used with subflows, you may encounter an issue where a subflow will queue and not give any hint of the error.

  4. Either change in your environment, providing a sample workflow or instruct the user to change the structure of the payload created and response gained.

Unable to Send Content-Type and/or Body with GET and DELETE Requests

The camel component does not natively support sending the Content Type and a body with GET and DELETE requests. To send this, you need to add an extra parameter to your request URL. It should resemble the following:

CODE 
https://www.your_request_url.com/api/v1/endpoint?getWithBody=true

https://www.your_request_url.com/api/v1/endpoint?deleteWithBody=true

#The default is set to ?getWithBody=false and ?deleteWithBody=false
Note:

When the param is set, the content-type will default to application/json.

When the param is not set, for GET and DELETE requests, a content-type is not passed. Users may need to add a header with content-type if needed.

Sending HTTP Request with No Body Using Integrations

When configuring an Integration, specifically using the JSON response to fulfillment HTTP action, some downstream APIs (for example, Apigee endpoints) require no request body at all. These endpoints strictly enforce Content-Length: 0 and reject requests with even an empty or placeholder payload.Today, leaving the request body blank or providing {} still results in a non-zero payload being sent, causing the request to fail with errors such as:

CODE 
400 Bad Request
Content Length Should be Zero

To emit a true zero-length request body, the request body must be explicitly set to null, not an empty string. This can be accomplished using a Freemarker comment, which produces no output at runtime.

  1. In the Request Body field of the Integration HTTP action, set:

    CODE 
    <#-- no output -->

    This causes the body to resolve to null, allowing the platform to send the request with:

    CODE 
    Content-Length: 0

    and no body, which satisfies APIs that enforce strict zero-length payload requirements.

Special & Unicode Characters in HTTPS Payloads

When attempting to make a REST API call that contains special or unicode characters, the JSON will become invalid. To resolve this, set the content type in the header to the following:

Key

Value

Content-Type

application/json; charset=utf-8

Escape String Literals for Special Characters in HTTPS Payload

When attempting to make a REST API call that contains special characters as a string with Freemarker, the JSON will become invalid. To resolve this, append ?json_string to your Freemarker value. For more information, see Built-ins for strings by Apache

JSON 
Example: ${(event.payload.description!)?json_string}

Credentials Support

Incorrectly Configured Credentials For Target System

With the range of credentials supported by OneTrust Integrations, there are bound to be intricacies and specifics to each system. Many seen are simply incorrectly configured credentials for the target system needs. Some systems will require specific headers to be added in addition to the OAuth or JWT fields needed.

  1. Understand the fields already configured, get access to credentials or have consultant screenshot credential.

  2. Understand what type it falls under: API Keys, Client Credentials, Access Token, JWT for example.

  3. See the headers that are required for the credential in the documentation.

  4. Use cURL command given to identify any extra fields needed.

Note:

For more information on this topic, see Configuring Integration Credentials.

mTLS

mutual Transport Layer Security (mTLS) setup for OneTrust Integrations is only for outbound purposes in order to connect with external systems. Often confused for two-way SSL, mTLS requires a private key for authentication.

  1. Obtain keys from the client in .pem format or a format we can convert to .pem.

  2. Next thing to troubleshoot is whether the keys are being accepted in OneTrust mTLS credentials.

    CODE 
    Getting an error like “key pair not accepted” means that the key format is incorrect or put in the incorrect fields.

  3. Ensure that the certificates being entered into OneTrust include the headers piece:

    CODE 
    -----BEGIN ENCRYPTED PRIVATE KEY-----
-----BEGIN CERTIFICATE-----

#Do not include the other info above it for mTLS specifically.

Required Formats:

  • RSA Public keys (the certificate) - 2048 or 4096 bits in X.509 v2/v3. DER Encoded as PEM

  • RSA Private Keys - PKCS8 (with or without Encryption)

  • Signature algorithms can be SHA256 or SHA512

Note:

For more information on this topic, see Setting Up Mutual Transport Layer Security.

SFTP

Path specification

Ensure the provided SFTP credentials aren’t specific to a certain path. If they are, be sure to specify only that path in the given workflow.

Convert SSH to RSA (PEM)

OneTrust Integrations only supports RSA format (RSA Private Keys - PKCS8).

To convert SSH to RSA pem use the following command:

CODE 
ssh-keygen -p -m pem -f /path/to/file

Environment & Account Issue

To resolve access issues with Integrations, please ensure the logged in user as the necessary roles and permissions assigned under global settings.

Note:

For more information, see Adding and Editing Users.

Common Configuration Issues

Many times clients will need to safelist the IPs of their target OT environment in order to actually communicate with the system. For more information, see About OneTrust Hosting Options, Locations, and Backup.

For dedicated environments, OneTrust holds those IP addresses. Contact a member of your OneTrust Team for additional support.