When designing an integration for Adobe Experience Platform (AEP) you will almost always need to work with schemas. What is a schema in AEP? A schema is a construct within Adobe's Experience Data Model (XDM) system. More specifically, a schema is a set of rules that represent and validate the structure and format of data. At a high level, schemas provide an abstract definition of a real-world object (such as a person) and outline what data should be included in each instance of that object (such as first name, last name, birthday, and so on). Nothing useful can be done within AEP without first creating a Schema. Learn more about AEP schemas here.
If you build an AEP Source connector using the Sources SDK, you will be giving your customer a simple way to bring data from your platform into their AEP environment. Before they can use the AEP Sources UI to configure the flow of data, they will first need to create a Schema and a DataSet so the data has a place to land. When instructing a customer on creating a Schema you will want to remember the following...
- An AEP user will need to create a schema and create a DataSet BEFORE they start the process of configuring the Source connection.
- You will need to provide documentation to the customer so they know what fields should exists within the schema. If the fields don't exist within the schema, the customer will be frustrated when they get to the field mapping step of the Source connector wizard.
- You should instruct the customer to put all of your data fields within a single field group. This will help the customer to keep their data fields organized across all of their Schemas.
- You should instruct the customer to put all of your data fields under a top level field of type 'object'. This helps the customer to know the context of the data fields when they utilize the fields within downstream applications such as Adobe Realtime CDP, Customer Journey Analytics, Adobe Journey Optimizer, etc.
Let's look at an example of creating a schema with the above recommendations. Our example is bringing in Loyalty data from a fictitious partner (non-Adobe) product called AcmeLoyalty.
Here are the data fields that should be imported into the customer's AEP environment -
- userID - String
- statusLevel - String
- totalPoints - integer
- signupDate - date
The first step is to create a new schema. It is important to select the correct base Class to build with. It is recommended in most cases to use either the XDM Individual Profile class or the XDM Experience Event class. If the data record will represent a specific event (with a timestamp) then use the Experience Event class, otherwise use the Individual Profile class. In our case, we'll use the Individual Profile class.
Once the schema is created the field group should be added...
With the field group created, you can start adding the fields. The first field should be the top-level 'Object' field. This will be the parent to all the other fields. Be sure to select the new field group in the panel on the right. Click 'Apply' to create the field.
All other fields should be created under the top-level (parent) object field. The same field group should be selected for all fields.
All four fields are now created under a top-level object and within the same field group. This will provide the best context as these data fields combined with other fields and used within the Adobe Experience Platform applications.
Adding Field Groups to the XDM Library
If the number of field groups is significant you should consider adding your field group to the XDM library. Doing this will save AEP customers from the work of manually creating the field group and all of the fields. It will also reduce errors by eliminating this manual and repetitive process. Once added to the XDM library a customer would simply select "Use existing field groups" and all the fields will automatically become part of their schema.
To have your field group added to the XDM library you must follow this process to contribute through GitHub. Each submission must be approved by Adobe and can take up to 2 weeks for review.