Mapping Linked APIs

If an atomic operation, such as Update Consents, requires two APIs to complete that operation, then use  Linked APIs. For example, we can use the “Linked API” if the use case is to create or update data for Data Subject Types from a third party system and that third party system requires two APIs to do the create or update operation. On Linked APIs, you can use the output of the 1st API as input to the 2nd API.

To map linked APIs, select Linked APIs from the Add New Rest API dropdown list to begin adding migration criteria and setting up the integration.

Then, in the Add New Rest API window, set up the 1st and 2nd API.

Setting Up the 1st API for Linked API

1. In the 1st API Settings tab, click Add Criteria to add the criteria to be applied on the map. You can select multiple criteria as needed. Data Transfer will be carried out by running this particular REST API only if all the migration criteria are satisfied.
   
   If you selected a Single Line text form field as one of your migration criteria, you can set the condition to any of the following:

• • Equal or Not Equal - if the value is “Equal to [Form Field Value]” or “Not Equal to [Form Field Value],” then the system executes the integration if the criteria is met.
    
    
  • Null or Not Null - If the value is “Null” or “Not Null,” the input field will be disabled and will be shown as null or not null, then the system will execute the integration if the criteria is met.
    
    
    

Select whether the integration data flow is for CPM to Third Party integration or Third Party integration to CPM:

• • CPM to a Third Party system - This indicates that the Consent data is sent from CPM to the Third Party system. Create/Update REST APIs should be set accordingly for this option.
    
    You can enable the Sync back to the System of Origin checkbox to send the mapped data back to the system where the consent originally came from. This feature enables you to send tokens back to the Third Party system. Note that this feature is only applicable to CPM to Third Party Rapid API integration. In addition, enabling this feature may cause an infinite loop.

• • Third Party system to CPM - This indicates that the Consent data is brought over from the Third Party system and recorded in CPM. REST APIs to fetch the data should be set accordingly for this option.

Select a use case for API Usage from the list. Each use case can pair to any API method: 

• • Create or Update Consents - Select this to create or update Consents/Data Subjects from CPM to Third Party systems.
    
    
  • Delete Consents in systems - Select this to delete Consents/Data Subjects from CPM to Third Party systems.

NOTE: The trigger to execute any REST API in CPM to Third Party Rapid API is creation of new Consents and Data Subjects or change of details for a Data Subject record. Currently, the “Delete” operation is not executed when a Consent or Data Subject is deleted. This will be supported in the future.

Then, set the mapping to Not Required if the current API call is not required, or set it to Required to require the API calls at all times if there are updates and to record the integration logs. 

The Real-time Processing feature executes the REST API once for each Consent received and can only be enabled by the TrustArc support. Currently, only Real-time Processing feature is supported for Linked APIs. Batch Processing will be supported in the future. If this is a requirement for you, reach out to your Sales and Customer Support Contact.

2. In the 1st API URL tab, select the HTTPS Method to use in the workflow and enter the custom API URL and URL Parameters. The following HTTPS methods are supported:

• • GET - Select this to read data from the Third Party system.
  • PUT - Select this to update or create data in the Third Party system.
  • POST - Select this to create a new row in the Third Party system.
  • DELETE - Select this to delete data in the Third Party system.
  • PATCH - Select this to modify the data in the Third Party system.

Then, enter the custom API URL and Variables in the URL. To use Variables in the URL input, it must be formatted specifically as [[${variable}]]. For example, https://www.website.com/[[${variable}]] once the variable is entered in the Variables section. Note that these variables are different from URL Parameters. URL Parameters are entered in the next tab.

3. In the 1st API Params tab, enter a Key and select a Value from the dropdown list, as applicable for URL Parameters. The Key and Values defined here are added to the URL as URL Parameters. Values can be one of the Form Fields or Metadata shown in the dropdown or static strings.
   
   
   
   
4. In the 1st API Headers tab, you can add all the keys and values that need to be sent in the REST API’s header. The value for the key can be a static string such as “abc” or it can be a metadata or a consent field. If Consent data fields or Consent metadata fields are mapped, then the values for these variables are substituted at the time the REST API is executed.
   
   
   
   
5. In the 1st API Body tab, you can enter the body of the REST API. You can click {} Edit in Code to input payload as the JSON body or use the Edit in Table feature to input the body. In this case, the hierarchy inside the JSON can be added using “.”.
   
   
   
   The Change Format functionality enables you to change format if the mapped field types are Checkbox, Toggle Switch, Group Checkbox, and Group Toggle Switch to any field type. If a checkbox on the CPM form is Opt-in checkbox and the corresponding checkbox in a Third Party system is Opt-out checkbox, then “Change Format” allows mapping between these.

6. In the 1st API Output tab, input the response of the 1st REST API you just configured. This can be used later as input to the 2nd API.

Select the Enable dynamic loop checkbox to run the linked 2nd API multiple times, looping through a particular structure in the output of the 1st API. During the run time, CPM loops the 2nd API as many times as the records in the output of the 1st API. When Dynamic Looping is enabled, you are required to enter an Array Key found in the JSON added in the output tab. Array Key corresponds to where the data as an Array starts in the output of the 1st REST API.

If you delete or change the Output JSON Variable or the URL parameter, and the keys or parameters are already used in the 2nd API or mapped in the 2nd API, an error message displays in the modal and in the log when you execute the integration.



If you change the JSON variable (or URL variable) in the 1st API, CPM displays a warning that states, “Changing the JSON variable (or URL variable) will result to loss in mapping connection with the 2nd API."

Setting Up the 2nd API for Linked API

1. In the 2nd API Settings tab, note that the components such as Migration Criteria, Integration Data Flow, API Usage, Mapping, and Run Job requirement are disabled since the values are inherited and can only be set in the 1st API.
   
   
   
   
2. In the 2nd API URL tab, select the HTTPS Method to use in the workflow and enter the custom API URL and URL Variables. 

To use variables in the URL input, it must be formatted specifically as [[${variable}]]. For example, https://www.website.com/[[${variable}]] once the variable is entered in the Variables section. Note that these variables are different from URL Parameters. URL Parameters are entered in the next tab.

3. Setting up the 2nd API Params, Headers, and Body tabs, is similar to setting these up in Single API or the 1st API in Linked API. Note that the dropdown for mapping the values contains 1st API output variables in addition to the form metadata and form fields.
   
   Params Tab
   
   
   Headers Tab
   
   
   Body Tab
   
   
   If you had selected Third Party Integration to CPM as Integration Data Flow, CPM dynamically adds the Response Mapping tab, where you can map the Rapid API output to Consent Form fields. CPM uses this mapping to create the Consent data from the output of the Rapid API.
   
   In the Body or Response Mapping tab, you may see Array Key or File Key field:
   
   
   • Array Key corresponds to where the Consent data starts in the output of the REST API as an Array. 
   • File Key corresponds to where the Consent data starts in the output of the REST API as a CSV file.
   
   
4. Click Save to save the integration setup or you can also click Save & Add Another API to add more Linked APIs.

•