Creating a Data Mapping
- Parker Hutcheson (Deactivated)
This article contains the introductory information for creating a Data Mapping. A Data Mapping is what informs the Behavioral Engagement Platform™️ of the Customer Attributes that should be populated with imported information.
Table of Contents
What is a Data Mapping?
Data Mappings are a collection of configurations allowing for the ingestion of Client business data into the Symend Application. A mapping is the alignment of:
Symend Attributes → Client Source Fields → Client Source Files | |
Data Source | Description |
Symend Attribute | The data attribute is part of the Symend Canonical Data Model, or those Custom Attributes called for by the Symend Playbook or your organization’s customization. |
Client Source Fields | The data from your own business data model, each field represents a data attribute that you opt to provide to the Symend application. |
Client Source Files | Representing the files that your organization intends to pass to Symend that feeds ingestion of your customer data. This can be a single or multiple files that are uniquely identified and containing different Source Fields. |
The creation of a Data Mapping will tell the Symend application how to interpret the contents of the files of Customer Data sent by your organization. This helps us understand where and how to use your business data in a Playbook, Segmentation, Email, SMS outreach, etc.
Data Mapping is accessed in the application from the Data Designer page and you can find more information on that in the article Getting Started - Introducing the Data Designer.
Mapping Statuses
It is important to understand the various Statuses a Mapping can exist in. These Statuses reflect the current usage of the configurations within.
Mapping Type | Description |
Active | An Active Mapping reflects those configurations currently being utilized to ingest files and handle the data within. Only a single Mapping can be active at a time. |
Draft (inactive) | A Draft Mapping is an incomplete or inactive group of Mapping configurations that is currently not used during the ingestion of Client data. Many Draft mappings can exist at a time. |
Archived (inactive) | Archived Mappings are those Mappings that have previously been Active and were since replaced. We keep these as a record of the configurations that were previously used to ingest your data into the Symend application |
Creating a Data Mapping
Navigate to the “Data Automation” page from the Settings menu item, and click the “New Mapping” button.
You’ll notice that the new mapping is named “Untitled” but you can edit and name it at any time.
Naming your Mapping
In the “Mapping name” field, type in the new name for this data mapping.
Names are alpha-numeric (letters and numbers) and can contain special characters. The maximum size of the name field is 128 characters. This name cannot be changed after the mapping is activated.
Define your Source Fields
What is a Source Field?
A Source Field is the name of the data attribute you’ll be passing with your files during the data ingest process. This field will need to mimic exactly the column headers in the CSV file you’ll produce to ingest customer data into the Symend Application. We’ll identify the data in your file by the column header and appropriately map that to the correct attribute.
Defining your Source Fields is one of the first steps toward attribute mapping, we recommend you complete this step and the Source Files before attempting to map any attributes.
Create your Source Fields
Describe the Fields that make up your data sources so they can be mapped and used as the attributes that power the application.
For new Mappings without any defined Source Fields, in the “Field from your Data Source” section, click the “+ Add Source Fields” button to open the Source Fields workflow.
To manage or add to your Source Fields you can always click the “Manage Source Fields” button at the top of the mapping screen.
Click the “Bulk add from text button”.
A new window will appear on screen where you will be able to free-text type or paste in your field names.
Each Source Field name must be separated by a comma.
Any validation errors will appear beneath the input box and must be resolved before continuing.
Once complete, click the “Submit” button to create these new fields (fields can be edited and deleted later).
This page summarizes your Data Sources, any current Mappings, and allows you to edit or delete them.
From this screen you’ll be able to:
Edit the Field Name by click on the value in the Field Name to see the edit screen.
Delete a Source Field by clicking on the trash can icon on the right-hand side of that field name.
This is not possible if the field is currently used in a mapping (as data is already assigned to that field). You will need to un-map the Source Field first to be able to delete it.
Add a new Source Field to an inactive mapping by:
Clicking “Bulk add as text” button at the top of the Data Source Fields screen.
Typing the field name into the input at the bottom of the list of current Source Fields on the Data Source Fields screen and clicking the “Add Field” button.
There is no restriction on the number of Source Fields that you can create for a Data Mapping.
Define your Source Files
What is a Source File?
A Source File represents the data files your business will generate to ingest customer data into the Symend application. This definition helps the Symend Application correctly identify your ingest files, ensuring we process the correct files only, understand what contents to expect, and ensures our application does not process your files out of order.
The completeness of your Customer Records and each customer’s data does not need to be bound to a single file. In fact, the total update of a Customer Record can come from many source files. Though it is critical that the UniqueIdentifier is included in all Source Files.
Defining your Source Files is one of the first steps toward attribute mapping, we recommend you complete this step and the Source Fields before attempting to map any attributes.
Create your Source Files
For new Mappings without any defined Source Files, in the “Files that make up your Data Source” field, click the “+ Add Source Files” button to open the Source Files workflow.
To manage or add to your Source Files you can always click the “Manage Source Fields” button at the top of the mapping screen.
Click the New Source File button.
A new screen will appear with a series of inputs for configuring your Source File.
Enter in a Label for your file.
The label will reflect the first part of your file’s name. For example, if your file is named CustomerData_01012022.csv the label would be the CustomerData component.
Select the appropriate Field delimiter for your files (comma, semicolon, tabs, pipe).
Select the appropriate Date Format for your files.
Date Format is required in the Source File definition. This allows the Symend application to properly identify the file’s uniqueness and ensure it is run in the correct order.
We only currently support the formats available in the dropdown selections for Date format.
Identify the time-stamp format to be included in the file name
This is an optional selection so you can select “Not included” from the dropdown list if it’s not used. Including a time-stamp will allow for this file to be ran many times throughout the day, otherwise a file will only be ran once per date.
Select your File’s extension (CSV or TXT).
Review the Source File name format, and Preview to confirm the configuration is correct and then click the “Save” button.
It is critical that the configurations entered in the Source File definition properly reflect the files you will be providing to Symend to trigger data ingestion. Otherwise, we will not be able to identify your files and will not ingest any data.
Once you’ve created a Source File, you’ll see a summary within the Data Source Files screen listing all the currently configured Files, including being able to:
Edit the Source File configurations
Delete a Source File
A Source File with any mappings cannot be deleted, it must be unmapped first.
View the number of Mappings using this Source File.
A new Source File can be added to an Inactive Mapping by clicking the “Manage Source Files” button and clicking on the “New Source File” button.
Defining your Unique Identifier
Why is this important?
It is critical to the successful engagement of your customers by Symend that we be able to uniquely identify all customers in your data. This ensures that:
The correct customer is updated when new data arrives
Each customer account is properly identified and duplicates are not created
Without a unique identifier for your customers, the Symend application cannot properly engage your customers, leading to a potentially negative customer experience.
What is a Unique Identifier?
A Unique Identifier is a field in your data that defines each customer as unique from another. In many cases this could be an account number, or other identifier. This is the primary key used in your customer data to identify each customer account.
Setting your Unique Identifier?
On the main mapping screen, under the “AccountKey” header:
Select the drop-down list.
The options in the drop-down is populated from the Source Fields you previously created. If your unique customer identifier attribute is not here, you can create another Source Field to include it.
Select the Source Field value that represents your Unique Identifier in your organization’s data from the drop-down list.
It is critical to get this configuration correct, as this mapping cannot be edited after your first Data Mapping is activated.
Unlike other mappings, you do not need to set a source file for the Unique Identifier. This is because the Unique Identifier you mapped to the “AccountKey” is required in all files you provide for data ingest. If this value is not present in a file, then it will not run and the data ingest will fail.
The Customer Data Model
On the Mapping screen, you’ll see a list of Categories and Attributes listed along the length of the screen. These Attributes are part of your Organization’s Customer Data Model. These are the Attributes you’ll be able to map against, and in some cases will be required to map against to enable the functionality of the Symend Application and any Playbooks you’ve installed.
Not all Attributes are required to be mapped, however those being used by the Playbook will prevent activation of that Playbook until a mapping is provided. Others (like the “AccountKey”) are required by the Symend application to operate.
Mapping an Attribute
Having defined your Data Source Fields, and Source Files it is now possible to begin mapping your business data to the attributes of the Customer Data Model for your organization. Each mapping is comprised of:
Symend Attributes → Client Source Fields → Client Source Files
Not all Attributes must be mapped, however some are required for operating the Symend Application, while others will be required in order for your Playbook to be published.
Completing an Attribute Mapping
When you’re ready to begin mapping to Symend’s attributes you’ll see a listing of all the available attributes grouped by category on the Mapping screen. For each attribute you wish to map you will need to:
Select a Source Field mapping, defining what Field from your files will update this attribute
Select a Source File, this will define what file will contain the Field and own the update of this attribute
Confirm that your Source Field data matches the Data Type of the attribute (for example, String, Integer, Date)
To be valid, any attribute mapping must have a complete Attribute → Source Field → Source File relationship. Partial mappings will prevent activation. If your Source Field’s data type does not match that of the attribute you are mapping to, your customer record(s) will not be processed.
Saving a Mapping
As you work on your mapping, it will be autosaved as changes are made, there is no requirement to explicitly save it. Your Mapping will be saved in Draft status until you are ready to activate or discard it.
Activating and Deactivating a Mapping
To learn more about activating and deactivating a mapping please review the Activating and Deactivating a Mapping article.