DataDocs is a feature for storing relational data regarding your contacts, this can for example be purchase history, upcoming events, booking data or other services.
Watch our video on DataDocs
Visit our API documentation to learn more about using DataDocs.
Terminology
-
Document type
In your DataDocs central you can store one or more Document Types. A Document Type gathers DataDocs with the same content and defines the two mandatory fields (originalId and externalId) in your JSON. You will always map a DataDoc to a type.
Multiple types can be used if you, let's say, want to separate different markets or brands due to different setups or data sources.
When viewing a contact's DataDocs you first select the document type and all rows connected to that contact within the selected type will appear.
You must create a type before you can start creating docs for your contacts.
It is recommended to add a JSON Schema to your types. Read more about this below.
-
DataDoc
A row of data connected to a contact by original id. Must belong to a Document type. The data for a contact can be updated and/or deleted.
-
OriginalId
The originalId is your unique identifier for a contact in Symplify.
What field in your JSON that correspond to originalId is defined by the Document Type.
-
ExternalId
The external Id is your own identifier for a specific DataDoc row, for example an order or booking number. It must be a unique string for that specific event. The externalId can be used for updating or deleting a row.
What field in your JSON that correspond to externalId is defined by the Document Type.
Preparations
DataDocs is a blank sheet when you first start so begin with defining your content.
There are only two mandatory fields for each row; one field containing the original Id and one field containing the external id, the rest of the headers are mapped according to what you include in your file/call.
The mandatory fields are mapped when creating the Document Type.
Consider if you want to include a transaction date and/or a date for when a document was last updated.
Important! Document headers are case sensitive and must be alphanumeric (A–Z, a–z and 0–9) and not contain any whitespaces. Underscore (_) and dash (-) is allowed.
Document headers are used for visualization of data (when using placeholders) and when creating segments.
You can add more document headers - please read more in JSON Schema below.
No column mapping is needed for visualization within the Symplify interface. When looking at a contact, all DataDoc row headers found on the specific contact (for the selected type) are included automatically.
DataDocs within a selected Document Type on a contact
The field values can be text, dates or numbers (decimals separated with a period (.)) that can be used for segmentation and placeholders in sendouts.
A value field can also contain JSON.
You can include as many headers you like but have in mind that everything should be there for a reason, unnecessary data means unnecessary work for the marketers.
Document history
Each time an update is made to a document, you can view the specific changes by clicking the cogwheel icon and selecting 'History'. This will display a list of all past changes, allowing you to track and review updates over time.
For example, as shown below, the 'Delivery' column has been updated with different delivery statuses:
Technical setup
You can import data with a file, via our Event Hub or as single rows using the API. Learn more on apidocs.symplify.com.
A DataDoc is a text string with JSON. When importing a DataDoc file, each line in the import will contain a JSON row:
{"originalid":"F3","bookingnumber":"F3-2","transactionDate":"2024-06-02","category":"sport","eventDate":"2024-09-01","event":"Team A - Team B","eventDetails":{"location":"Tiny Stadium","startTime":"15.00"},"orderItems":[{"ticketType":"adult","quantity":1,"price":15},{"ticketType":"student","quantity":2,"price":10}]}
{"originalid":"F3", "bookingnumber":"F3-3", "transactionDate": "2024-05-30", "category": "music", "eventDate": "2024-07-22","event":"The musical","eventDetails": {"location": "Big Arena", "Entrance": "F", "startTime": "20.00"},"orderItems":[{"ticketType":"adult","quantity":2,"price":20},{"ticketType":"kid","quantity":1,"price":10},{"ticketType":"student","quantity":1,"price":15}]}
When updating, you must always provide the Document Type id for which the DataDocs belongs.
After a successful import, when selecting the specific Document Type, the rows will be visible on the contacts.
JSON Schema (via JSON Schema Builder)
The Document Type is built on a JSON Schema for each Document type. The schema will help you structuring and editing segments and using placeholders since this will automatically generate the correct segment options based on the schema.
JSON Schema Builder (video) enables users to create and edit a schema by mapping values to data types. This builder makes it easy and very intuitive to add new columns to an existing Document type or creating new ones. The schema always reflects the segment editor, so you can easily detect if you are missing anything when working in segment editor based on your Document type.
Here is an example of the JSON Schema Builder with 6 column headers where DonationID (as a string) is the first column header of your Document.
Use different data types such as "strings", "number" or even "arrays". If your documents include arrays, the array must have the type=array in order to be able to create segments on. Please view "orderItems" in below example schema.
Example schema:
{
"$schema":"http://json-schema.org/draft-07/schema#",
"type":"object",
"properties":{
"category":{"type":"string"},
"transactionDate":{"type":"string","format":"date-time"},
"eventDetails":{
"type":"object",
"properties":{
"location":{"type":"string"},
"Entrance":{"type":"string"},
"Event":{"type":"string"},
"startTime":{"type":"string"},
"section":{"type":"integer"}
}
},
"orderItems":{
"type":"array",
"items":{
"type":"object",
"properties":{
"ticketType":{"type":"string"},
"quantity":{"type":"integer"},
"price":{"type":"number"}
}
}
}
}
}Note! You also have the option to work with raw JSON via the Schema Builder.