DocumentationExperience PlatformDestinations Guide

Server specs for destinations created with Destination SDK

Last update: Fri Sep 29 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • User
  • Admin
  • Leader

Destination server specs define the type of destination platform that will receive the data from Adobe Experience Platform, and the communication parameters between Platform and your destination. For instance:

  • A streaming destination server spec defines the HTTP server endpoint that will receive the HTTP messages from Platform. To learn to configure how the HTTP calls to the endpoint are formatted, read the templating specs page.
  • An Amazon S3 destination server spec defines the S3 bucket name and path where Platform will export the files.
  • An SFTP destination server spec defines the host name, root directory, communication port, and encryption type of the SFTP server where Platform will export the files.

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:

You can configure the destination server specs via the /authoring/destination-servers endpoint. See the following API reference pages for detailed API call examples where you can configure the components shown in this page.

This page shows all the destination server types supported by Destination SDK, with all their configuration parameters. When creating your destination, replace the parameter values with your own.

IMPORTANT
All parameter names and values supported by Destination SDK are case sensitive. To avoid case sensitivity errors, please use the parameters names and values exactly as shown in the documentation.

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.

Integration type
Supports functionality
Real-time (streaming) integrations
Yes
File-based (batch) integrations
Yes

When creating or updating a destination server, use one of the server type configurations described in this page. Depending on your integration requirements, make sure to replace the sample parameter values from these examples with your own.

Hard-coded versus templatized fields templatized-fields

When creating a destination server through Destination SDK, you can define configuration parameter values either by hard-coding them into the configuration, or by using templatized fields. Templatized fields allow you to read user-provided values from the Platform UI.

Destination server parameters have two configurable fields. These options dictate whether you are using hard-coded or templatized values.

Parameter
Type
Description
templatingStrategy
String

Required. Defines whether there is a hard-coded value provided via the value field, or a user-configurable value in the UI. Supported values:

  • NONE: Use this value when you are hard-coding the parameter value via the value parameter (see the next row). Example:"value": "my-storage-bucket".
  • PEBBLE_V1: Use this value when you want your users to provide a parameter value in the UI. Example: "value": "{{customerData.bucket}}".
value
String

Required. Defines the parameter value. Supported value types:

  • Hard-coded value: Use a hard-coded value (such as "value": "my-storage-bucket") when you do not need users to enter a parameter value in the UI. When hard-coding a value, templatingStrategy should always be set to NONE.
  • Templatized value: Use a templatized value (such as "value": "{{customerData.bucket}}") when you want your users to provide a parameter value in the UI. When using templatized values, templatingStrategy should always be set to PEBBLE_V1.

When to use hard-coded versus templatized fields

Both hard-coded and templatized fields have their own uses in Destination SDK, depending on what type of integration you are creating.

Connecting to your destination without user input

When users connect to your destination in the Platform UI, you might want to handle the destination connection process without their input.

To do this, you can hard-code the destination platform connection parameters in the server spec. When you use hard-coded parameter values in your destination server configuration, the connection between Adobe Experience Platform and your destination platform is handled without any input from the user.

In the example below, a partner creates a Data Landing Zone destination server with the path.value field being hardcoded.

{
   "name":"Data Landing Zone destination server",
   "destinationServerType":"FILE_BASED_DLZ",
   "fileBasedDlzDestination":{
      "path":{
         "templatingStrategy":"NONE",
         "value":"Your/hardcoded/path/here"
      },
      "useCase": "Your use case"
   }
}

As a result, when users go through the destination connection tutorial, they will not see an authentication step. Instead, the authentication is handled by Platform, as shown in the image below.

Ui image showing the authentication screen between Platform and a DLZ destination.

Connecting to your destination with user input

When the connection between Platform and your destination should be established following a specific user input in the Platform UI, such as selecting an API endpoint or providing a field value, you can use templatized fields in the server spec to read the user input and connect to your destination platform.

In the example below, a partner creates a real-time (streaming) integration and the url.value field uses the templatized parameter {{customerData.region}} to personalize part of the API endpoint based on user input.

{
   "name":"Templatized API endpoint example",
   "destinationServerType":"URL_BASED",
   "urlBasedDestination":{
      "url":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"https://api.yourcompany.com/data/{{customerData.region}}/items"
      }
   }
}

To give users the option of selecting a value from the Platform UI, the region parameter must also be defined in the destination configuration as a customer data field, as shown below:

"customerDataFields":[
   {
      "name":"region",
      "title":"Region",
      "description":"Select an option",
      "type":"string",
      "isRequired":true,
      "readOnly":false,
      "enum":[
         "US",
         "EU"
      ]
   }

As a result, when users go through the destination connection tutorial, they must select a region before they can connect to the destination platform. When they connect to the destination, the templatized field {{customerData.region}} is replaced with the value that the user has selected in the UI, as shown in the image below.

Ui image showing the destination connection screen with a region selector.

Real-time (streaming) destination server streaming-example

This destination server type allows you export data from Adobe Experience Platform to your destination via HTTP requests. The server configuration contains information about the server receiving the messages (the server on your side).

This process delivers user data as a series of HTTP messages to your destination platform. The parameters below form the HTTP server specs template.

The sample below shows an example of a destination server configuration for a real-time (streaming) destination.

{
   "name":"Your destination server name",
   "destinationServerType":"URL_BASED",
   "urlBasedDestination":{
      "url":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{YOUR_API_ENDPOINT}"
      }
   }
}
Parameter
Type
Description
name
String
Required. Represents a friendly name of your server, visible only to Adobe. This name is not visible to partners or customers. Example: Moviestar destination server.
destinationServerType
String
Required. Set this to URL_BASED for streaming destinations.
templatingStrategy
String

Required.

  • Use PEBBLE_V1 if you are using a templatized field instead of a hard-coded value in the value field. Use this option if you have an endpoint like: https://api.moviestar.com/data/{{customerData.region}}/items, where users must select the endpoint region from the Platform UI.
  • Use NONE if no temmplatized transformation is needed on the Adobe side, for example if you have an endpoint like: https://api.moviestar.com/data/items
value
String
Required. Fill in the address of the API endpoint that Experience Platform should connect to.

Amazon S3 destination server s3-example

This destination server allows you to export files containing Adobe Experience Platform data to your Amazon S3 storage.

The sample below shows an example of a destination server configuration for an Amazon S3 destination.

{
   "name":"Amazon S3 destination",
   "destinationServerType":"FILE_BASED_S3",
   "fileBasedS3Destination":{
      "bucket":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.bucket}}"
      },
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      }
   }
}
Parameter
Type
Description
name
String
The name of your destination server.
destinationServerType
String
Set this value according to your destination platform. To export files to an Amazon S3 bucket, set this to FILE_BASED_S3.
fileBasedS3Destination.bucket.templatingStrategy
String

Required. Set this value according to the type of value used in the bucket.value field.

  • If you want your users to input their own bucket name in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded bucket name for your integration, such as "bucket.value":"MyBucket", then set this value to NONE.
fileBasedS3Destination.bucket.value
String
The name of the Amazon S3 bucket to be used by this destination. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "value":"MyBucket".
fileBasedS3Destination.path.templatingStrategy
String

Required. Set this value according to the type of value used in the path.value field.

  • If you want your users to input their own path in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the path.value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded path for your integration, such as "bucket.value":"/path/to/MyBucket", then set this value to NONE.
fileBasedS3Destination.path.value
String
The path to the Amazon S3 bucket to be used by this destination. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "value":"/path/to/MyBucket".

SFTP destination server sftp-example

This destination server allows you to export files containing Adobe Experience Platform data to your SFTP storage server.

The sample below shows an example of a destination server configuration for an SFTP destination.

{
   "name":"File-based SFTP destination server",
   "destinationServerType":"FILE_BASED_SFTP",
   "fileBasedSFTPDestination":{
      "rootDirectory":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.rootDirectory}}"
      },
      "hostName":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.hostName}}"
      },
      "port":22,
      "encryptionMode":"PGP"
   }
}
Parameter
Type
Description
name
String
The name of your destination server.
destinationServerType
String
Set this value according to your destination platform. To export files to an SFTP destination, set this to FILE_BASED_SFTP.
fileBasedSFTPDestination.rootDirectory.templatingStrategy
String

Required. Set this value according to the type of value used in the rootDirectory.value field.

  • If you want your users to input their own root directory path in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the rootDirectory.value field to read a user-provided value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded root directory path for your integration, such as "rootDirectory.value":"Storage/MyDirectory", then set this value to NONE.
fileBasedSFTPDestination.rootDirectory.value
String
The path to the directory that will host the exported files. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "value":"Storage/MyDirectory"
fileBasedSFTPDestination.hostName.templatingStrategy
String

Required. Set this value according to the type of value used in the hostName.value field.

  • If you want your users to input their own host name in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the hostName.value field to read a user-provided value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded host name for your integration, such as "hostName.value":"my.hostname.com", then set this value to NONE.
fileBasedSFTPDestination.hostName.value
String
The host name of your SFTP server. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "hostName.value":"my.hostname.com".
port
Integer
The SFTP file server port.
encryptionMode
String

Indicates whether to use file encryption. Supported values:

  • PGP
  • None

Azure Data Lake Storage (ADLS) destination server adls-example

This destination server allows you to export files containing Adobe Experience Platform data to your Azure Data Lake Storage account.

The sample below shows an example of a destination server configuration for an Azure Data Lake Storage destination.

{
   "name":"ADLS destination server",
   "destinationServerType":"FILE_BASED_ADLS_GEN2",
   "fileBasedAdlsGen2Destination":{
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      }
   }
}
Parameter
Type
Description
name
String
The name of your destination connection.
destinationServerType
String
Set this value according to your destination platform. For Azure Data Lake Storage destinations, set this to FILE_BASED_ADLS_GEN2.
fileBasedAdlsGen2Destination.path.templatingStrategy
String

Required. Set this value according to the type of value used in the path.value field.

  • If you want your users to input their ADLS folder path in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the path.value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded path for your integration, such as "abfs://<file_system>@<account_name>.dfs.core.windows.net/<path>/", then set this value to NONE.
fileBasedAdlsGen2Destination.path.value
String
The path to your ADLS storage folder. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as abfs://<file_system>@<account_name>.dfs.core.windows.net/<path>/.

Azure Blob Storage destination server blob-example

This destination server allows you to export files containing Adobe Experience Platform data to your Azure Blob Storage container.

The sample below shows an example of a destination server configuration for an Azure Blob Storage destination.

{
   "name":"Blob destination server",
   "destinationServerType":"FILE_BASED_AZURE_BLOB",
   "fileBasedAzureBlobDestination":{
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      },
      "container":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.container}}"
      }
   }
}
Parameter
Type
Description
name
String
The name of your destination connection.
destinationServerType
String
Set this value according to your destination platform. For Azure Blob Storage destinations, set this to FILE_BASED_AZURE_BLOB.
fileBasedAzureBlobDestination.path.templatingStrategy
String

Required. Set this value according to the type of value used in the path.value field.

  • If you want your users to input their own Azure Blob storage account URI in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the path.value field to read the value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded path for your integration, such as "path.value": "https://myaccount.blob.core.windows.net/", then set this value to NONE.
fileBasedAzureBlobDestination.path.value
String
The path to your Azure Blob storage. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as https://myaccount.blob.core.windows.net/.
fileBasedAzureBlobDestination.container.templatingStrategy
String

Required. Set this value according to the type of value used in the container.value field.

  • If you want your users to input their own Azure Blob container name in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the container.value field to read the value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded container name for your integration, such as "path.value: myContainer", then set this value to NONE.
fileBasedAzureBlobDestination.container.value
String
The name of the Azure Blob Storage container to be used for this destination. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as myContainer.

Data Landing Zone (DLZ) destination server dlz-example

This destination server allows you to export files containing Platform data to a Data Landing Zone storage.

The sample below shows an example of a destination server configuration for a Data Landing Zone (DLZ) destination.

{
   "name":"Data Landing Zone destination server",
   "destinationServerType":"FILE_BASED_DLZ",
   "fileBasedDlzDestination":{
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      },
      "useCase": "Your use case"
   }
}
Parameter
Type
Description
name
String
The name of your destination connection.
destinationServerType
String
Set this value according to your destination platform. For Data Landing Zone destinations, set this to FILE_BASED_DLZ.
fileBasedDlzDestination.path.templatingStrategy
String

Required. Set this value according to the type of value used in the path.value field.

  • If you want your users to input their own Data Landing Zone account in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the path.value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded path for your integration, such as "path.value": "https://myaccount.blob.core.windows.net/", then set this value to NONE.
fileBasedDlzDestination.path.value
String
The path to the destination folder that will host the exported files.

Google Cloud Storage destination server gcs-example

This destination server allows you to export files containing Platform data to your Google Cloud Storage account.

The sample below shows an example of a destination server configuration for a Google Cloud Storage destination.

{
   "name":"Google Cloud Storage Server",
   "destinationServerType":"FILE_BASED_GOOGLE_CLOUD",
   "fileBasedGoogleCloudStorageDestination":{
      "bucket":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.bucket}}"
      },
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      }
   }
}
Parameter
Type
Description
name
String
The name of your destination connection.
destinationServerType
String
Set this value according to your destination platform. For Google Cloud Storage destinations, set this to FILE_BASED_GOOGLE_CLOUD.
fileBasedGoogleCloudStorageDestination.bucket.templatingStrategy
String

Required. Set this value according to the type of value used in the bucket.value field.

  • If you want your users to input their own Google Cloud Storage bucket name in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the bucket.value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded bucket name for your integration, such as "bucket.value": "my-bucket", then set this value to NONE.
fileBasedGoogleCloudStorageDestination.bucket.value
String
The name of the Google Cloud Storage bucket to be used by this destination. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "value": "my-bucket".
fileBasedGoogleCloudStorageDestination.path.templatingStrategy
String

Required. Set this value according to the type of value used in the path.value field.

  • If you want your users to input their own Google Cloud Storage bucket path in the Experience Platform UI, set this value to PEBBLE_V1. In this case, you must templatize the path.value field to read a value from the customer data fields filled in by the user. This use case is shown in the example above.
  • If you are using a hard-coded path for your integration, such as "path.value": "/path/to/my-bucket", then set this value to NONE.
fileBasedGoogleCloudStorageDestination.path.value
String
The path to the Google Cloud Storage folder to be used by this destination. This can either be a templatized field which will read the value from the customer data fields filled in by the user (as shown in the example above), or a hard-coded value, such as "value": "/path/to/my-bucket".

Next steps next-steps

After reading this article, you should have a better understanding of what a destination server spec is, and how you can configure it.

To learn more about the other destination server components, see the following articles:

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6