Help Documentation

Custom Data Tables

Updated on

Custom Data Tables (CDT) refer to tables created to store data. They are part of a relational MySQL database and enable complex data manipulation. Data can be added to these tables via the API, an import, or a SQL query. Custom Data Tables are utilized within Dynamic Data Tables and SQL Queries, allowing manipulation of data and output of a new set of contacts.

Creating a Custom Data Table

Follow the steps below to create a custom data table.

  1. On the Data Table Manger page, enter the name of the custom data table in the Create New Data Table field. The name can only contain characters, numbers, and underscores.
  2. Select Custom Data Table as the content type.
  3. Click Create.

Once the data table has been created, you will be brought to the properties page to create the data fields.

Properties

The top portion of the properties page provides you with the standard information about the custom data table.

Object
Description
Name
The name of the custom data table.
Description A description given to the custom data table. This field is optional.
Folder Location The location of the data table in the folder tree of the data table manager.
Available for Sending Enables the data table to be used in an email send. When this is selected, you will be asked to select which data field in the tables should be used as the Recipient Key. Select the field from your table that contains Email Addresses.

** For clients using a field besides email address as the unique identifier (UID) for the account, the UID field should be selected as the Recipient Key and the data field with a Data Type of Email should be used when selecting the Email Column.
Email Testing This indicates that the data table can be used for testing an email. Test tables can contain a maximum of 20 contacts (or rows).
GDPR The data table contains contact information as outlined by the General Data Protection Regulation (GDPR). This field will need to be enabled for all data tables that contain data outlined by GDPR in order for iPost to process any GDPR removal requests.
Records
The number of contacts contained within the data table.
Content Type The type of data table.
Created Date The date the data table was created.
Created By The user who created the data table.
Modified Date The date the data table was last modified.
Modified By The user who last modified the data table.
Distribute to Subclients Use this feature to easily recreate the custom data table in any subclient account. This is only available if your account is provisioned with subclients and this feature is enabled. Contact your Customer Success Manager if you would like this feature enabled.

Attributes

The bottom portion of the Properties page allows you to define the data structure for the custom data table.

CDT Edit Attributes

To create an attribute, follow the steps below.

  1. Click on the Edit Attributes button.
  2. Click on the Add New Attribute button on the Edit Attributes page.
  3. Enter the attribute information.
    • Name: This necessary field serves as the unique identifier for the table. It may only contain letters, numbers, and underscores.
    • Data Type: This field is mandatory and determines the data type for the field. For more information on data types, please refer to the Reference Section at the end of this article.
    • Default Value: This field is optional. If no value is present during data import, the default value is applied to the contact.
    • Required: This indicates that the data field is required when new data is added to the table. If this column has an empty value, the records will be rejected.
    • Primary Key: This indicates if the field is the Unique Identifier for the contact records in the table. The field is used when adding and updating data in the table.
    • Post Code: This field is optional. If selected, this column will indicate that the field contains postal codes. This field should be selected if the Custom Data Table is being used in a dynamic data table for postal code radius search.
    • Post Code Validation: This field is optional. If selected, the platform will perform validation on the postal code field.
  4. Once all data fields are entered, click on the Save button.

Custom Data Table Relationship

Relationships allow you to establish a relationship between your new custom data table and an existing custom data table. It can then be used in dynamic data tables.

CDT Relationships

To create a Custom Data Tables Relationship, please follow the steps below.

  1. Click on the Add Relationship button.
  2. Enter the name for the relationship in the Insert Relationship Name field.
  3. The name of the current custom data table will pre-populate the first data table field. 
  4. Select the field from the current data table that you will be using for the relationship; typically, this field is the same data type as the corresponding field in your existing data table.
  5. Select the existing data table from the Select Table field.
  6. Select the field from the existing data table that you will be using for the relationship.
  7. Click on Add Relationships.

Custom Data Tables Relationships cannot be edited or removed once created, unless one of the custom data tables is deleted. Relationships can, however, be created, edited, or removed if they are configured for a Dynamic Data Table.

Once all the information has been entered on the properties page, click on Continue to save your CDT and proceed to the Records page.

Records

The Records page is where you can access the contacts associated with the Custom Data Table. When the Custom Data Table is created, the Records page will be blank and contacts will need to be added to the table.

Uploading Data

Contacts can be added to a Custom Data Table via the API, a Process Automation that utilizes the Import Activity, or by manually importing via the UI.  

Manually Add Records
  1. On the Records page, click on the Upload icon.
  2. Select how you would like to locate your data file.
    • Browser Upload - upload a file on your PC. The data file must be smaller than 50MB if this option is used.
    • FTP Upload - select a file that is located in the CDT_IN folder on your FTP site.
  3. Check the Expect Large Data box if the large text data field is in use. This will default the delimiter to Tab and enforce the Respect double quotes as a text qualifier option.
  4. Select the Delimiter of the data file.
  5. Choose the Import Options for your data (multiple options can be selected).
    • Skip rows in the import file with bad data
    • Respect double quotes as a text qualifier
    • Include column headers as the first line
  6. Select the Record Operation. The options available in the drop down will vary depending on the presence of one or more Primary Keys in data structure of the custom data table.
    • Overwrite Existing Records - replace data currently in the table with data from the data file.
    • Only Update Existing Records - only update any contacts associated with the data table and will reject any new contacts.
    • Add Only New Records - add new contacts from the data file but will not update any existing contacts.
    • Add New & Update Existing Contacts - add new contacts and update any contacts associated with the data table.
  7. Click Next.
  8. On the Map Records step, you will need to map the fields on the data file to the attributes for the data table. Any fields that match the data table attributes will be mapped automatically. If you do not want to map a field, select Ignore this column.
  9. Click Finish.

The column headers and data format in your file should match the attributes and data type in your custom data table. Otherwise, the records could be rejected.

The import will run in session and you will be notified via a pop-up in the UI when it has completed. The notification will provide you with a total number of records added or updated, as well as a total of the records that were rejected. You will also be able to download the rejected records. The rejected record file will include a column with the reason as to why the contact was not imported.

Once the import has completed, the custom data table will be populated with contact information. You will be able to see the contacts and the various data fields associated with the contact for that custom data table. You also have the option to Edit or Delete a contact in the Action column.

  • Edit - update a contact and any data values related to that contact. Once edited, these changes will be updated in the custom data table. Edit is only enabled if a Primary Key is configured on the custom data table.
  • Delete - remove a contact. Once deleted, the contact will no longer exist in the custom data table. Deleted contacts are unable to be recovered after the delete has been completed.

Records Functions

Once the custom data table is populated with contacts, other functionality will be enabled on the Records page. These functions are icons located on the right hand side above the contact information.

Split

Split allows you to split the custom data table into multiple custom data tables.

To split a table, follow the steps below.

  1. Click on the Split icon.
  2. On the Split Table page, select the number of branches you would like to split the table into. The default number of branches is two.
  3. Select how you would like to divide the contacts into the new branches.
    • Numbers - split the table by a specific quantity per branch.
    • Percentage - split the table by a percentage per branch.
  4. In order to distribute the contacts into the new branches, slide the blue circle for each branch until the correct quantity or percentage is reached.
  5. Click Split.
  6. The new custom data tables will be located in the same folder as the custom data table that was split. The resulting data tables will have the split letter (A, B, C, etc) and date and time appended to the custom data table name.

Export

Export allows you to export the contacts out of the custom data table to the CDT_OUT directory (folder) on your FTP. An email notification will be sent when the export is available.

To export a custom data table, follow the steps below.

  1. Click on the Export icon.
  2. Your email address will be populated in the Send a Data Export Summary Report To box. 
  3. Click Done.

Download Table Structure

Download Table Structure allows you to download a .csv file in your browser that contains the Attributes of the table as column headers. The file can then be used as a data template for future imports to this table.

Clean

Clean allows you to remove all contacts from the custom data table. Please note that once a data table has been cleaned, the contacts cannot be recovered to repopulate the data table.

To clean a data table, follow the steps below.

  1. Click on the Clean icon.
  2. Click Yes to confirm that you want to clean the custom data table.

Search allows you to search for a contact in the data table.

To search for a contact, follow the steps below.

  1. Click on the Search icon.
  2. On the Search Members page, select the field you want to search on from the Select Field to Search By drop down.
  3. Enter the information you are searching on in the Insert Text to Search By field.
  4. Click the Search button.

The search results will appear below the search criteria. From here, you can click on the Edit or Delete icon next to the row.

Editing a Custom Data Table

Once a Custom Data Table is created, you can edit the table structure as needed. If you are adding or removing a Primary Key in a populated data table, you will need to empty the data table prior to making this change.

Please follow the steps below to edit the data table.

  1. Locate the Custom Data Table in the Data Table Manager.
  2. Click on the Name of the Custom Data Table.
  3. Once on the Properties Page, changes can be made.
    • If editing the Name of the table, click in the Name field to make edits.
    • If editing the Attributes, click on the Edit Attribute button to make changes.
    • Once a Custom Data Table Relationship has been established, it cannot be edited.
  4. Click Continue to save your changes.
Reference

Data Types

Column Type
MySQL Type and Length
Notes
Date & Time Datetime Format: 'YYYY-MM-DD HH:MM:SS'
Decimal Decimal (16,4)
Email Varchar (255)
Integer Int (10) Value range: -2147483648 - 2147483647 (not bigint)
Long Text Text

"Long text" columns cannot part of a Primary Key

"Long text" columns cannot participate in relationships
Monetary Decimal (9,2)
Short Text Varchar(255
Boolean Tinyint(1) Values:1/0
Large Text
Used when importing large data sets such as HTML. The use of this data type will require that data files be tab delimited.

Operators

Below is a list of available operators for dynamic data tables.

Data Type
Operator
Text
Is / Is Not
Contains / Does Not Contain
Number Equal To / Not Equal To
Less Than
Greater Than
Between
Like / Not Like
Begins With
Ends With
Boolean Is 0
Is 1
Date Is Equal / Is Not Equal
Is After
Is On or After
Is Before
Is On or Before
Is Null / Is Not Null
Matches Day
Matches Month
Matches Day and Month
Matches Year
Radius Search Zip Code
Previous Article Overview of Data Tables
Next Article Dynamic Data Tables