This is a streamlined guide for creating a new Destination configuration -- using the Adobe Experience Platform (AEP) Destination SDK -- and testing it in your AEP sandbox. The target audience is an Adobe technology (ISV) partner who desires to publish a Destination connector in the AEP Destination catalog for use by all Adobe RT-CDP customers. This guide will not cover all of the configuration options available for making a customized Destination that works with your APIs -- for that see the full Destination SDK documentation. Instead, this guide takes you quickly through all the steps, giving you a solid overview of the technology and the process. This will help you to confidently scope and resource your own Destination creation project.
--> Watch the video for this tutorial.
To successfully complete the steps in this guide you will need the following:
- Membership in the Adobe Technology Partner Program (formerly called Adobe Exchange program)
- Access to an AEP sandbox environment
- An Adobe developer console project with "Experience Platform API" added; API credentials need to be assigned to Role by admin
- Access to Postman and basic experience with it
In this guide, we will execute several API calls using Postman. Before we do that, we need to import a Postman collection and a Postman environment. We will also need to make a few additions to the environment.
Second, download the Postman environment file from the Adobe developer console project UI and import it. (Figure 1)
Figure 1: Developer Console page to download environment file for Postman
Third, we need to augment the environment with a few additional values.
- Add a new environment variable called "PLATFORM_GATEWAY" with the value "https://platform.adobe.io"
- Add a new environment variable called "SANDBOX_NAME" with the value of your sandbox name
- Add a new environment variable called "UNIQUE_NAME" to provide a unique label for each time you might go through this tutorial. Initially you can give it a value like - - “tutorial” (if you ran through it a second time you could use “tutorial 2”)
Figure 2: Postman Environment with additional fields ‘PLATFORM_GATEWAY’, ‘SANDBOX_NAME’, and ‘UNIQUE_NAME’
Generate an Access Token
Now that Postman is set up, let’s generate an access token so that we can make all the API calls in the remaining sections.
Open the “Create a Streaming Destination...” collection in your Postman app. Expand the first subfolder, named “Authentication”, and you will see one request. Run this request.
You’ll know that this was successful if you see a 200 response and if you now have a ‘Current value’ for your ACCESS_TOKEN environment variable.
Figure 3: Postman Environment showing generated Access Token’s Current Value
Now we will be creating the Schema, Dataset, Segment, and Source.
The Schema is a blueprint for the data to be stored in Adobe Experience Platform. A schema is made up of a Class and zero or more Field Groups.
A Dataset is a storage and management construct for collecting data. A dataset is always linked with a schema.
Segments is a way to narrow down a large group of individuals by using Segment Definitions, resulting in an Audience.
A Source gives you a simplified way to ingest data records into a Dataset.
Make sure to change the UNIQUE_NAME in the environment variables to something unique when running the folder. You might have to scroll down the environment variable list to see it. If you run the postman calls a second time, you can change the UNIQUE_NAME value to prevent naming collisions in the objects that are created.
Figure 4: Postman Environment showing a distinctive ‘UNIQUE_NAME’ value
We can create all the above by running through the postman collection “Sandbox Setup”. Right click the folder and hit “Run folder” (Make sure you have generated an access token, or this step will not work!)
Figure 5: Postman workspace showing how to run the ’Sandbox Setup’ folder
Figure 6: Postman workspace showing options on running the ’Sandbox Setup’ folder
Verify that all NINE calls were given a 200 or 201 success message.
That’s it! We are now ready to create the connector.
Create a Destination
In this section, we will create a branded card in Adobe's Destination Catalog.
Please refer to ‘Create a Streaming Destination’ folder shared in the postman collection
Figure 7: Postman collection showing the ‘Create a Streaming Destination’ folder
We need to have access to an API to which the destination is going to send data. In this exercise we will use a free Webhook API service. Webhook.site lets you easily inspect, test and automate any incoming HTTP request.
Please go to Webhook.site and copy the URL from the browser. We will be using this URL when creating the Destination Server Template.
Figure 8: Webhook.site webpage
The End-to-end process of building a destination involves:
1. Create a destination server
2. Create a destination
3. Create a Destination instance in the UI
4. Generate Test Profile Data
5. Test Destination by sending profile data
6. Submit the Destination via API for Adobe to review and publish
Please refer to Create Destination Configurations section in the sample postman collection shared by the TPP team.
1. Create a destination server
In Postman, open the ‘Server Template Configs’ folder and the ‘Create a Destination Server Template’ request.
Figure 9: Postman collection showing ‘Server Template Configs’ folder and ‘Create a Destination Server Template’ request
In the request Body, replace the urlBasedDestination.url.value with your webhook.site URL and run the request.
Figure 10: Postman ‘Create a Destination Server Template’ request with example webhook.site URL highlighted.
You’ll see a 201 response if the Destination Server template has been created successfully. Copy the value of ‘instanceId’ from the response, as we will be using this ID in our next call.
Figure 11: Postman 201 Response for ‘Create a Destination Server Template’ request, with ‘instanceId’ field noted.
2. Create a destination
Open the ‘Create a Destination Configuration’ request.
Figure 12: Postman collection showing ‘Destination Configs’ folder and ‘Create a Destination Config’ request
The value of the ‘name’ field provided in this call is what appears in the Destination Card of the catalog. Change the value of the name with your preferred name for the destination. In this example, we have used the name ‘101 Streaming Destination’.
Figure 13: ‘Create a Destination Config’ request with updated name
Copy the value of ‘instanceId’ generated in the previous call (of Step 1 above) and update it in the ‘destinationServerId’ field in the ‘destinationDelivery’ section.
Figure 14: ‘Create a Destination Config’ request with destinationServerId field highlighted
A 201 response means a Destination instance was created.
With this we have created a Destination and we should be able to see our Destination appearing in the Destination Catalog. To verify this, login to https://platform.adobe.com and verify that the correct Org and sandbox are selected in the upper right. Navigate to the Destinations area using the left navigation bar, then click the “Catalog” tab and search for the name of your Destination.
Figure 15: Adobe Experience Platform UI Destinations Catalog, showing the Destination just created
3. Create a Destination instance in the UI
Navigate to the Destinations section on the left-hand side indicated by number 2 in Figure 16 below.
Search for the Destination name; in this example we have used the name ‘101 Streaming Destination’ (indicated by number 3 in Figure 16 below).
As this is the first time we are exploring this Destination in the UI, we have a few more steps to complete the configuration.
Figure 16: Adobe Experience Platform UI Destinations Catalog, showing ‘101 Streaming Destination’ just created
Press the ‘Set-up’ button on the Destination Catalog to start the configuration process.
The Authentication Type we have defined in the server is Bearer type, hence provide the Bearer Token and click ‘Connect to the destination’. Note that you can put any value into the Bearer token field as it will not be validated here.
Figure 17: AEP Destination Configuration Connection Type and Bearer Token field
Under the ‘Configure’ step, fill in the Destination name, endpoint, Exchange Partner ID value and press the ‘Next’ button. Note that for this exercise it does not matter what values you enter.
Figure 18: AEP Destination Configuration Destination Details fields filled out with example values
Under the ‘Governance’ step, Choose the appropriate Marketing Actions that are acceptable for this destination and click the “Next” button. Again, what you select is not important for this exercise.
Figure 19: AEP Destination Configuration Governance Marketing Actions page
Under the ‘Select Segments’ step, Choose the Segments to be activated to this Destination and select next, in this exercise we have selected the segment "Exchange Partner 102 – First Name exists” that was automatically created earlier in the Sandbox Setup. Your segment might have a slightly different name.
Figure 20: AEP Destination Configuration Segment Selection page
In the Mapping step, we are going to define the fields that our Destination accepts.
Source Fields are the fields from the platform and the Target Fields are the fields defined when we created our Destination.
We have selected the firstName, lastName, and Email fields to be exported.
- Source: xdm: person.name.lastName -> Target: xdm: lastName
- Source: xdm:person.name.firstName -> Target: xdm: firstName
- For Email: Source: Add New Mapping – pick the Identity Namespace radio button; choose Email; then for Target field – pick the ‘Identity Namespace’ radio button again and select ‘External_id’
Figure 21: AEP Destinations Configuration Mapping lastName and firstName
Figure 22: AEP Destinations Configuration Mapping Email
Press the finish button. This completes the loop of creating a Destination through API, Configuring the Destination Instance in the UI, activating a Segment to be exported.
Figure 23: AEP Destinations Configuration complete page with activated segments.
Now, let us ingest sample profiles into the platform using the streaming ingestion API.
Open the Postman Collection and go to the End-to-end testing folder, Open the Import: Stream to PROFILE API call and make a SEND request.
Figure 24: Postman ‘End-to-end testing’ folder and ‘Import: Stream to PROFILE’ request
A 200 response means the profile has been successfully ingested into the platform.
Note - you can edit the profile details (name.firstName, name.lastName, personalEmail.address, etc.) and run this call multiple times to create additional profiles.
Log in to platform.adobe.com , navigate to the Profiles section on the left-hand side of the navigation pane. Choose Email as the identity namespace and enter the email that was ingested in the API Request above (you can pull this from the body of the request); you will notice a list of Profiles.
Figure 25: AEP Profiles, searching for profile created in Figure 24
Click on the Profile ID to see the Attributes, Events and Segment Membership of this newly ingested Profile.
Figure 26: AEP Profile detail on sample profile created in Figure 24
Click on the Segment Membership tab and notice all the segments this profile qualifies for:
Figure 27: AEP Sample Profile segment membership
Figure 28: webhook.site webpage showing that POST calls from testing API are being sent to sample destination.
There can be some latency when creating brand new objects within your sandbox environment. This can result in a delay in seeing the data messages sent to the webhook.site service. To have AEP send data messages immediately to the webhook.site service you can utilize the Destination Testing API. Learn more about that here.
Now open webhook.site in a new tab, we will notice the POST call from Testing API is being registered and we can see the segment data getting pushed to our destination which is webhook.site.
Summary and Next Steps
In this guide you have created and tested a new Destination connector within your AEP sandbox. Once published, this connector will be available to AEP customers that have access to the public Destinations Catalog. They can then use the connector to push audiences and profile data to your platform.
However, before you offer this Destination connector to AEP customers you will need to go through this exercise again and create a connector that better matches the requirements of your delivery endpoint. You can modify the Postman requests provided and make the needed adjustments to fit the naming, endpoint URL, authentication, data mapping (etc.) to configure a successful connector for your customers.
See the full Destination SDK documentation.
After you have configured, tested and documented your destination, you can use the destination publishing endpoint to submit it to Adobe for review and publishing. Read more in the article on submitting your destination for review.