Configure user input through customer data fields
When connecting to your destination in the Experience Platform UI, you might need your users to provide specific configuration details or select specific options that you make available to them. In Destination SDK, these options are called customer data fields.
To understand where this component fits into an integration created with Destination SDK, see the diagram in the configuration options documentation or see the following destination configuration overview pages:
Use cases for customer data fields use-cases
Use customer data fields for a variety of use cases where you need users to input data into the Experience Platform UI. For example, use customer data fields when users need to provide:
- Cloud storage bucket names and paths, for file-based destinations.
- The format accepted by the customer data fields.
- Available file compression types that users can select from.
- Lists of available endpoints for real-time (streaming) integrations.
You can configure customer data fields via the /authoring/destinations endpoint. See the following API reference pages for detailed API call examples where you can configure the components shown in this page.
This article describes all the supported customer data fields configuration types that you can use for your destination, and shows what customers will see in the Experience Platform UI.
Supported integration types supported-integration-types
Refer to the table below for details on which types of integrations support the functionality described on this page.
Supported parameters supported-parameters
When creating your own customer data fields, you can use the parameters described in the table below to configure their behavior.
nametitle field is empty or missing.typeIndicates the type of the custom field you are introducing. Accepted values:
stringobjectinteger
titlename value.descriptionisRequiredpattern^[A-Za-z]+$ in this field.enumdefaultenum list.hiddenuniquereadOnlyIn the example below, the customerDataFields section defines two fields that users must input in the Platform UI when connecting to the destination:
Account ID: A user account ID for your destination platform.Endpoint region: The regional endpoint of the API they will connect to. Theenumsection creates a drop-down menu with the values defined within available for the users to select.
"customerDataFields":[
{
"name":"accountID",
"title":"User account ID",
"description":"User account ID for the destination platform.",
"type":"string",
"isRequired":true
},
{
"name":"region",
"title":"API endpoint region",
"description":"The API endpoint region that the user should connect to.",
"type":"string",
"isRequired":true,
"enum":[
"EU"
"US",
],
"readOnly":false,
"hidden":false
}
]
The resulting UI experience is shown in the image below.
Destination connection names and descriptions names-description
When creating a new destination, Destination SDK automatically adds Name and Description fields to the destination connection screen in the Platform UI. As you can see in the example above, the Name and Description fields are rendered in the UI without being included in the customer data fields configuration.
Order customer data fields ordering
The order in which you add the customer data fields in the destination configuration is reflected in the Platform UI.
For example, the configuration below is reflected accordingly in the UI, with the options showing up in the order Name, Description, Bucket name, Folder path, File Type, Compression format.
"customerDataFields":[
{
"name":"bucketName",
"title":"Bucket name",
"description":"Amazon S3 bucket name",
"type":"string",
"isRequired":true,
"pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
"readOnly":false,
"hidden":false
},
{
"name":"path",
"title":"Folder path",
"description":"Enter the path to your S3 bucket folder",
"type":"string",
"isRequired":true,
"pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
"readOnly":false,
"hidden":false
},
{
"name":"fileType",
"title":"File Type",
"description":"Select the exported file type.",
"type":"string",
"isRequired":true,
"readOnly":false,
"hidden":false,
"enum":[
"csv",
"json",
"parquet"
],
"default":"csv"
},
{
"name":"compression",
"title":"Compression format",
"description":"Select the desired file compression format.",
"type":"string",
"isRequired":true,
"readOnly":false,
"enum":[
"SNAPPY",
"GZIP",
"DEFLATE",
"NONE"
]
}
]
Group customer data fields grouping
You can group several customer data fields within one section. When setting up the connection to the destination in the UI, users can see and benefit from a visual grouping of similar fields.
To do this, use "type": "object" to create the group, and collect the desired customer data fields within a properties object, as shown in the image below, where the grouping CSV Options is highlighted.
"customerDataFields":[
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
}
]
}
]
Create dropdown selectors for customer data fields dropdown-selectors
For situations where you want to allow users to select between several options, for example which character should be used to delimit the fields in CSV files, you can add dropdown fields to the UI.
To do this, use the namedEnum object as shown below and configure a default value for the options that the user can select.
"customerDataFields":[
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
}
]
}
]
Create dynamic dropdown selectors for customer data fields dynamic-dropdown-selectors
For situations where you want to dynamically call an API and use the response to dynamically populate the options in a dropdown menu, you can use a dynamic dropdown selector.
The dynamic dropdown selectors look identical to the regular dropdown selectors in the UI. The only difference is the values are dynamically retrieved from an API.
To create a dynamic dropdown selector, you must configure two components:
Step 1. Create a destination server with a responseFields template for the dynamic API call, as shown below.
{
"name":"Server for dynamic dropdown",
"destinationServerType":"URL_BASED",
"urlBasedDestination":{
"url":{
"templatingStrategy":"PEBBLE_V1",
"value":" <--YOUR-API-ENDPOINT-PATH--> "
}
},
"httpTemplate":{
"httpMethod":"GET",
"headers":[
{
"header":"Authorization",
"value":{
"templatingStrategy":"PEBBLE_V1",
"value":"My Bearer Token"
}
},
{
"header":"x-integration",
"value":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.integrationId}}"
}
},
{
"header":"Accept",
"value":{
"templatingStrategy":"NONE",
"value":"application/json"
}
}
]
},
"responseFields":[
{
"templatingStrategy":"PEBBLE_V1",
"value":"{% set list = [] %} {% for record in response.body %} {% set list = list|merge([{'name' : record.name, 'value' : record.id }]) %} {% endfor %}{{ {'list': list} | toJson | raw }}",
"name":"list"
}
]
}
Step 2. Use the dynamicEnum object as shown below. In the example below, the User dropdown is retrieved using the dynamic server.
"customerDataFields": [
{
"name": "integrationId",
"title": "Integration ID",
"type": "string",
"isRequired": true
},
{
"name": "userId",
"title": "User",
"type": "string",
"isRequired": true,
"dynamicEnum": {
"queryParams": [
"integrationId"
],
"destinationServerId": "<~dynamic-field-server-id~>",
"authenticationRule": "CUSTOMER_AUTHENTICATION",
"value": "$.list",
"responseFormat": "NAME_VALUE"
}
}
]
Set the destinationServerId parameter to the ID of the destination server that you created at step 1. You can see the destination server ID in the response of the retrieve a destination server configuration API call.
Create nested customer data fields nested-fields
You can create nested customer data fields for complex integration patterns. This allows you to chain a series of selections for the customer.
For example, you can add nested customer data fields to require customers to select an integration type with your destination, followed immediately by another selection. The second selection is a nested field within the integration type.
To add a nested field, use the properties parameter as shown below. In the configuration example below, you can see three separate nested fields within the Yourdestination - Integration Specific Settings customer data field.
isRequired parameter on nested fields. For example, in the configuration snippet below, the first two nested fields are marked as required (highlighted line xxx) and customers cannot proceed unless they select a value for the field. Read more about required fields in the supported parameters section.
{
"name": "yourdestination",
"title": "Yourdestination - Integration Specific Settings",
"type": "object",
"properties": [
{
"name": "agreement",
"title": "Advertiser data destination terms agreement. Enter I AGREE.",
"type": "string",
"isRequired": true,
"pattern": "I AGREE",
"readOnly": false,
"hidden": false
},
{
"name": "account-name",
"title": "Account name",
"type": "string",
"isRequired": true,
"readOnly": false,
"hidden": false
},
{
"name": "email",
"title": "Email address",
"type": "string",
"isRequired": false,
"pattern": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
"readOnly": false,
"hidden": false
}
],
"isRequired": false,
"readOnly": false,
"hidden": false,
Create conditional customer data fields conditional-options
You can create conditional customer data fields, which are displayed in the activation workflow only when users select a certain option.
For example, you can create conditional file formatting options to be displayed only when users select a specific file export type.
The configuration below creates a conditional grouping for CSV file formatting options. The CSV file options are displayed only when the user selects CSV as the desired file type for export.
To set a field as conditional, use the conditional parameter as shown below:
"conditional": {
"field": "fileType",
"operator": "EQUALS",
"value": "CSV"
}
In a wider context, you can see the conditional field being used in the destination configuration below, alongside the fileType string and the csvOptions object in which it is defined. The conditional fields are defined in the properties parameter.
"customerDataFields":[
{
"name":"fileType",
"title":"File Type",
"description":"Select your file type",
"type":"string",
"isRequired":true,
"enum":[
"PARQUET",
"CSV",
"JSON"
],
"readOnly":false,
"hidden":false
},
{
"name":"csvOptions",
"title":"CSV Options",
"description":"Select your CSV options",
"type":"object",
"conditional":{
"field":"fileType",
"operator":"EQUALS",
"value":"CSV"
},
"properties":[
{
"name":"delimiter",
"title":"Delimiter",
"description":"Select your Delimiter",
"type":"string",
"isRequired":false,
"default":",",
"namedEnum":[
{
"name":"Comma (,)",
"value":","
},
{
"name":"Tab (\\t)",
"value":"\t"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"quote",
"title":"Quote Character",
"description":"Select your Quote character",
"type":"string",
"isRequired":false,
"default":"",
"namedEnum":[
{
"name":"Double Quotes (\")",
"value":"\""
},
{
"name":"Null Character (\u0000)",
"value":"\u0000"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"escape",
"title":"Escape Character",
"description":"Select your Escape character",
"type":"string",
"isRequired":false,
"default":"\\",
"namedEnum":[
{
"name":"Back Slash (\\)",
"value":"\\"
},
{
"name":"Single Quote (')",
"value":"'"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"emptyValue",
"title":"Empty Value",
"description":"Select the output value of blank fields",
"type":"string",
"isRequired":false,
"default":"",
"namedEnum":[
{
"name":"Empty String",
"value":""
},
{
"name":"\"\"",
"value":"\"\""
},
{
"name":"null",
"value":"null"
}
],
"readOnly":false,
"hidden":false
},
{
"name":"nullValue",
"title":"Null Value",
"description":"Select the output value of 'null' fields",
"type":"string",
"isRequired":false,
"default":"null",
"namedEnum":[
{
"name":"Empty String",
"value":""
},
{
"name":"\"\"",
"value":"\"\""
},
{
"name":"null",
"value":"null"
}
],
"readOnly":false,
"hidden":false
}
],
"isRequired":false,
"readOnly":false,
"hidden":false
}
]
Below, you can see the resulting UI screen, based on the configuration above. When the user selects the file type CSV, additional file formatting options referring to the CSV file type are displayed in the UI.
Accessing templatized customer data fields accessing-templatized-fields
When your destination requires user input, you must provide a selection of customer data fields to your users, which they can fill in through the Platform UI. Then, you must configure your destination server to correctly read the user input from the customer data fields. This is done through templatized fields.
Templatized fields use the format {{customerData.fieldName}}, where fieldName is the name of the customer data field that you are reading information from. All templatized customer data fields are preceded by customerData. and enclosed within double braces {{ }}.
For example, let’s consider the following Amazon S3 destination configuration:
"customerDataFields":[
{
"name":"bucketName",
"title":"Enter the name of your Amazon S3 bucket",
"description":"Amazon S3 bucket name",
"type":"string",
"isRequired":true,
"pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
"readOnly":false,
"hidden":false
},
{
"name":"path",
"title":"Enter the path to your S3 bucket folder",
"description":"Enter the path to your S3 bucket folder",
"type":"string",
"isRequired":true,
"pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
"readOnly":false,
"hidden":false
}
]
This configuration prompts your users to enter their Amazon S3 bucket name and folder path into their respective customer data fields.
For Experience Platform to correctly connect to Amazon S3, your destination server must be configured to read the values from these two customer data fields, as shown below:
"fileBasedS3Destination":{
"bucketName":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.bucketName}}"
},
"path":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.path}}"
}
}
The templatized values {{customerData.bucketName}} and {{customerData.path}} read the user-provided values so that Experience Platform can successfully connect to the destination platform.
For more information about how to configure your destination server to read templatized fields, see the documentation on hard-coded versus templatized fields.
Next steps next-steps
After reading this article, you should have a better understanding of how you can allow your users to input information in the Experience Platform UI through customer data fields. You now also know how to select the right customer data field for your use case, and configure, order, and group customer data fields in the Platform UI.
To learn more about the other destination components, see the following articles: