Partner schema configuration
Experience Platform uses schemas to describe the structure of data in a consistent and reusable way. When data is ingested into Platform, it is structured according to an XDM schema. For more information on the schema composition model, including design principles and best practices, see the basics of schema composition.
When building a destination with Destination SDK, you can define your own partner schema to be used by your destination platform. This gives users the ability to map profile attributes from Platform to specific fields that your destination platform recognizes, all within the Platform UI.
When configuring the partner schema for your destination, you can fine tune the field mapping supported by your destination platform, such as:
- Allow users to map a
phoneNumber
XDM attribute to aphone
attribute supported by your destination platform. - Create dynamic partner schemas that Experience Platform can dynamically call to retrieve a list of all supported attributes within your destination.
- Define mandatory field mappings that your destination platform requires.
To understand where this component fits into an integration created with Destination SDK, see the diagram in the configuration options documentation or see the guide on how to use Destination SDK to configure a file-based destination.
You can configure your schema settings 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 schema configuration options that you can use for your destination, and shows what customers will see in the 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 schema configuration supported-schema-types
Destination SDK supports multiple schema configurations:
- Static schemas are defined through the
profileFields
array in theschemaConfig
section. In a static schema, you define every target attribute that should be shown in the Experience Platform UI in theprofileFields
array. If you need to update your schema, you must update the destination configuration. - Dynamic schemas use an additional destination server type, called a dynamic schema server, to dynamically retrieve the supported target attributes and generate schemas based on your own API. Dynamic schemas do not use the
profileFields
array. If you need to update your schema, there is no need to update the destination configuration. Instead, the dynamic schema server retrieves the updated schema from your API. - Within the schema configuration, you have the option of adding required (or predefined) mappings. These are mappings that users are able to view in the Platform UI, but they cannot modify them when setting up a connection to your destination. For example, you can enforce the email address field to always be sent to the destination.
The schemaConfig
section uses multiple configuration parameters, depending on the type of schema that you need, as shown in the sections below.
Create a static schema attributes-schema
To create a static schema with profile attributes, define the target attributes in the profileFields
array as shown below.
"schemaConfig":{
"profileFields":[
{
"name":"phoneNo",
"title":"phoneNo",
"description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the mobilePhone.number value in Experience Platform could be phoneNo on your side.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"firstName",
"title":"firstName",
"description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.firstName value in Experience Platform could be firstName on your side.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"lastName",
"title":"lastName",
"description":"This is a fixed attribute on your destination side that customers can map profile attributes to. For example, the person.name.lastName value in Experience Platform could be phoneNo on your side.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
}
],
"useCustomerSchemaForAttributeMapping":false,
"profileRequired":true,
"segmentRequired":true,
"identityRequired":true,
"segmentNamespaceAllowList": ["someNamespace"],
"segmentNamespaceDenyList": ["someOtherNamespace"]
}
profileFields
profileFields
array, you can omit the useCustomerSchemaForAttributeMapping
parameter entirely.useCustomerSchemaForAttributeMapping
Enables or disables the mapping of attributes from the customer schema to the attributes that you define in the profileFields
array.
- If set to
true
, users only see the source column in the mapping field.profileFields
are not applicable in this case. - If set to
false
, users can map source attributes from their schema to the attributes you defined in theprofileFields
array.
The default value is false
.
profileRequired
true
if users should be able to map profile attributes from Experience Platform to custom attributes on your destination platform.segmentRequired
true
.identityRequired
true
if users should be able to map identity types from Experience Platform to the attributes you defined in the profileFields
array .segmentNamespaceAllowList
segmentNamespaceDenyList
.Example:
"segmentNamespaceAllowList": ["AudienceManager"]
will allow users to map only audiences from the AudienceManager
namespace to this destination.To allow users to export any audience to your destination, you can ignore this parameter.
If both
segmentNamespaceAllowList
and segmentNamespaceDenyList
are missing from your configuration, users will only be able to export audiences originating from the Segmentation Service.segmentNamespaceDenyList
segmentNamespaceAllowed
.Example:
"segmentNamespaceDenyList": ["AudienceManager"]
will block users from mapping audiences from the AudienceManager
namespace to this destination.To allow users to export any audience to your destination, you can ignore this parameter.
If both
segmentNamespaceAllowed
and segmentNamespaceDenyList
are missing from your configuration, users will only be able to export audiences originating from the Segmentation Service.To allow the export of all audiences, regardless of the origin, set
"segmentNamespaceDenyList":[]
.The resulting UI experience is shown in the images below.
When users select the target mapping, they can see the fields defined in the profileFields
array.
After selecting the attributes, they can see them in the target field column.
Create a dynamic schema dynamic-schema-configuration
Destination SDK supports the creation of dynamic partner schemas. As opposed to a static schema, a dynamic schema does not use a profileFields
array. Instead, dynamic schemas use a dynamic schema server which connects to your own API from where it retrieves the schema configuration.
In a dynamic schema configuration, the profileFields
array is replaced by the dynamicSchemaConfig
section, as shown below.
"schemaConfig":{
"dynamicSchemaConfig":{
"dynamicEnum": {
"authenticationRule":"CUSTOMER_AUTHENTICATION",
"destinationServerId":"DYNAMIC_SCHEMA_SERVER_ID",
"value": "Schema Name",
"responseFormat": "SCHEMA"
}
},
"profileRequired":true,
"segmentRequired":true,
"identityRequired":true
}
dynamicEnum.authenticationRule
Indicates how Platform customers connect to your destination. Accepted values are CUSTOMER_AUTHENTICATION
, PLATFORM_AUTHENTICATION
, NONE
.
- Use
CUSTOMER_AUTHENTICATION
if Platform customers log into your system via any of the authentication methods described here. - Use
PLATFORM_AUTHENTICATION
if there is a global authentication system between Adobe and your destination and the Platform customer does not need to provide any authentication credentials to connect to your destination. In this case, you must create a credentials object using the Credentials API. - Use
NONE
if no authentication is required to send data to your destination platform.
dynamicEnum.destinationServerId
instanceId
of your dynamic schema server. This destination server includes the API endpoint which Experience Platform will call to retrieve the dynamic schema.dynamicEnum.value
dynamicEnum.responseFormat
SCHEMA
when defining a dynamic schema.profileRequired
true
if users should be able to map profile attributes from Experience Platform to custom attributes on your destination platform.segmentRequired
true
.identityRequired
true
if users should be able to map identity types from Experience Platform to the attributes you defined in the profileFields
array .Required mappings required-mappings
Within the schema configuration, in addition to your static or dynamic schema, you have the option of adding required (or predefined) mappings. These are mappings that users are able to view in the Platform UI, but they cannot modify them when setting up a connection to your destination.
For example, you can enforce the email address field to always be sent to the destination.
- You can configure a required source field and a required destination field. In this case, users cannot edit or select any of the two fields and can only view the selection.
- You can configure a required destination field only. In this case, users will be allowed to select a source field to map to the destination.
See below two examples of a schema configuration with required mappings and what these look like in the mapping step of the activate data to batch destinations workflow.
The example below shows both required source and destination mappings. When both source and destination fields are specified as required mappings, users cannot select or edit any of the two fields, and can only view the predefined selection.
code language-json |
---|
|
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto | |||
---|---|---|---|
Parameter | Type | Required/Optional | Description |
requiredMappingsOnly |
Boolean | Optional | When this is set to true , users cannot map other attributes and identities in the activation flow, apart from the required mappings that you define in the requiredMappings array. |
requiredMappings.sourceType |
String | Required |
Indicates the type of the
|
requiredMappings.source |
String | Required |
Indicates the value of the source field. Supported value types:
|
requiredMappings.destination |
String | Required | Indicates the value of the target field. When both source and destination fields are specified as required mappings, users cannot select or edit any of the two fields and can only view the selection. |
As a result, both the Source field and Target field sections in the Platform UI are greyed out.
The example below shows a required destination mapping. If only the destination field is specified as required, users can select what source field to map to it.
code language-json |
---|
|
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 layout-auto | |||
---|---|---|---|
Parameter | Type | Required/Optional | Description |
requiredMappingsOnly |
Boolean | Optional | When this is set to true , users cannot map other attributes and identities in the activation flow, apart from the required mappings that you define in the requiredMappings array. |
requiredMappings.destination |
String | Required | Indicates the value of the target field. When only the destination field is specified, users can select a source field to map to the destination. |
mandatoryRequired |
Boolean | Optional | Indicates whether the mapping should be marked as a mandatory attribute. |
primaryKeyRequired |
Boolean | Optional | Indicates whether the mapping should be marked as a deduplication key. |
As a result, the Target field section in the Platform UI is greyed out, while the Source field section is active and users can interact with it. The Mandatory key and Deduplication key options are active, and users cannot change them.
Next steps next-steps
After reading this article, you should have a better understanding of what schema types are supported by Destination SDK and how you can configure your schema.
To learn more about the other destination components, see the following articles: