You can use Digital Analytics Import to merge data from other sources with information captured by our site tracking technologies. You can also import data without IT help.
Supported solution types for data import
Digital Analytics supports the following solution types for import:
- Category definition file (CDF)
- Provides information that describes the navigation and content organization hierarchy of your site. The information is used in Digital Analytics reports.
- Visitor registration fields
- Import visitor data such as age, gender, income, and other data in addition to up to 50 registration attributes. Report, filter, and segment on your imported registration values in Digital Analytics.
- Data extensions
- Provides data attributes to extend your Digital Analytics data model. You can import up to 50 attribute fields that are associated with a specific data field or from a select list of data objects. These 50 attributes are in addition to the 50 attribute fields you can pass in page tags.
- Multichannel
- Imports offline transaction data. You can merge the imported data with the online transactions and visitor behavior data captured by your tag implementation.
Requirements
Import has some strict requirements for SFTP targets, file names, and file configurations. These requirements apply regardless of your import method. Before you begin, read the following information for successful data import.
- Every client ID has its own unique import SFTP target. Regardless of your solution, all import files are sent to the SFTP target for your client ID.
- Each import solution has file naming conventions that you must follow. For details, check out File name format.
- Each import solution has a configuration that defines the structure and contents. Digital Analytics Import expects to see them in the files that you import.
- Some import solution configurations are static. Other import solution types are more flexible.
For example, Category definition files follow a specific structure. You are only allowed to change the file delimiter character.
- Import validates the files against the configurations you define. Creating files that match the configuration is essential for successful data imports. For details, check out Create import files.
- You can import data from Import or use another process such as a recurring cron job or SFTP client upload. Regardless of the method, the files are processed against the same validation rules.
Create import files
You can import data files created outside of Digital Analytics. These files have requirements for the name, structure, and content. Some of these requirements are the same regardless of import solution type, while others depend on the solution type. Files that do not meet the requirements cannot be imported.
Each import file configuration has a strict list of fields. You must include all fields and adhere to the prescribed column order. If the data field column order does not match the specification, then the file cannot be loaded.
To make the file configuration process easier for you, Digital Analytics provides templates for each solution type. Simply download the template for your solution type and populate it with your data. The import solution templates contain the correct field names, the correct file delimiter, and a supported file name. When you add your data to the template file, do not change the file in a way that causes it to deviate from the configuration for the import solution type. For details about downloading a template for your solution type and using it to create an import file, check out Build an import file from a template.
There is a limit on the file size for importing. Files that are imported through the Import user interface must be less than 50 MB. Files that are sent to Digital Analytics through SFTP must be less than 100 MB.
The text of the files must be in either ASCII or UTF-8.
File name format
Files that you import must meet strict file naming conventions. The file naming convention tells Import what type of data you are sending, and what import solution it applies to.
All import file names consist of four parts:
An import solution prefix
- A filename prefix that identifies the import solution type for the file that you are sending. Valid file name prefixes:
- CDF - Category Definition File
- DE - Data Extensions
- MCS - Multichannel Shop
- MCO - Multichannel Order
- A numeric client ID
- The assigned unique site numeric identifier.
- A user-defined import file name or the primary key
- For data extension files, this name is the name of the data field that is the primary join key. For other import solution types, it is any name that you want to use to distinguish the import file.
- The file extension CSV
- File names must always have a CSV extension, otherwise, the file is rejected as invalid. You are not limited to using the comma as the separator, but you must use CSV as the file extension. You can create or edit files in Microsoft Excel, but make sure that you do not use the default Excel file extension.
Multichannel import file
Use a multichannel import configuration to import offline transaction data for individual items or for orders.
There are two types of Multichannel import files.
- Multichannel Shop (MCS)
- Use this file to import offline transaction data for individual items. The data in this file is merged with data collected by the Digital Analytics shop tags on your website. If you are using the Multichannel solution, you must have a Multichannel Shop import file.
- Multichannel Order (MCO)
- Use this file to import offline transaction data for orders. The data in this file is merged with data collected by the Digital Analytics order tags on your website. This file is optional.
Note: The uniqueness of an imported record is determined by the combination of values in the following fields: RegistrationID (MCS only), OrderID, TransactionID, ProductName (MCS only). If an imported record has an invalid value in any field that defines record uniqueness, you cannot import the corrected record until the invalid record is deleted. You cannot use the OverwriteFlag field to overwrite the record. The OverwriteFlag field corrects only values in data fields that are not used to define the uniqueness of a record. Contact Digital Analytics support to request the record deletion.
Multichannel Shop fields
Every Multichannel Shop (MCS) file that you import must contain the same set of fields. All the fields are required to be imported, but you can leave some fields empty.
You can find the Multichannel Shop (MCS) file fields in the following table. Data values are required only for the fields with a Y in the Data Required column of the table. You do not have to enter a default value to signify a null field. You can leave those fields empty.
Name | Description | Length | Format | Data Required |
---|---|---|---|---|
Date_ID | Date when the offline transaction occurred. Date_ID is always an 8-digit numeric string in YYYYMMDD format. | 8 | String | Y |
OverwriteFlag | A yes/no code (Y or N) used to identify if the file record replaces an existing record field.
If this field is empty, a value of N is assumed. |
1 | String | N |
RegistrationID | Unique customer identifier. This value is used in combination with the values of other fields to determine record uniqueness. | 256 | String | Y |
OrderID | Unique order identifier. This value is used in combination with the values of other fields to determine record uniqueness. | 256 | String | Y |
TransactionID | Unique transaction identifier. This value is used in combination with the values of other fields to determine record uniqueness. | 256 | String | Y |
TransactionType | Number/code to identify the type of imported transaction. This value is for future use. The only valid value is 1 Purchase. | 256 | Number | Y |
ProductID | Unique product identifier. | 256 | String | Y |
ProductName | The name of the product. This value is used in combination with the values of other fields to determine record uniqueness. | 256 | String | Y |
ProductCategory | The Hierarchical Product Category, which is separated by the greater than symbol (>). For example, Women's > Shoes > | String | Y | |
BasePrice | The price at which this product is sold. The format is a number with a single decimal character. Do not use commas or currency symbols. Values are assumed to be in the currency of the CID of record for the import. For example, use 123456.78 not $123,456.78. | 16.2 | Double | Y |
Quantity | Quantity of items sold. | 8 | Number | Y |
online_attribute_1 | The attribute fields are tied specifically to the ProductID value, which is required for each row in a Multichannel import file.
Online Attributes 1-50 map to the attribute fields that are collected by Digital Analytics shop tags. Use these attributes to merge online and offline data reports. |
100 | String | N |
… | 100 | String | N | |
online_attribute_50 | 100 | String | N | |
Offline_attribute_1 | Offline attributes 1-50 are for attributes that do not apply to online shopping (for example, Store ID). | 4000 | String | N |
… | 4000 | String | N | |
Offline_attribute_50 | 4000 | String | N |
Multichannel Order fields
Every Multichannel Order (MCO) file that you import must contain the same set of fields. All the fields are required to be imported, but you can leave some fields empty.
The Multichannel Order (MCO) file fields are listed in the following table. Data values are required only for the fields with a Y in the Data Required column of the table. You do not need to enter a default value to signify a null field. You can leave those fields empty.
Name | Description | Length | Format | Data Required |
---|---|---|---|---|
Date_ID | Date when the offline transaction occurred. Date_ID is always an 8-digit numeric string in YYYYMMDD format. | 8 | String | Y |
OverwriteFlag | A yes/no code (Y or N) used to identify if the file record replaces an existing record field.
If this field is empty, a value of N is assumed. |
1 | String | N |
RegistrationID | Unique customer identifier. | 256 | String | Y |
OrderID | Unique order identifier. This value is used in combination with the TransactionID value to determine record uniqueness. | 256 | String | Y |
TransactionID | Unique transaction identifier. This value is used in combination with the OrderID value to determine record uniqueness. | 256 | String | Y |
TransactionType | Number/code to identify the type of imported transaction. This field is for future use. The only valid value is 1 Purchase. | 256 | Number | Y |
TotalPrice | The total price for this product in this transaction. Do not include shipping and handling charges because they are tracked separately in the Shipping field.
A format is a number with a single decimal character. Do not use commas or currency symbols. Values are assumed to be in the currency of the CID of record for the import. For example, use 123456.78 not $123,456.78. |
16.2 | Double | Y |
Shipping | The shipping and handling charges associated with the order.
A format is a number with a single decimal character. Do not use commas or currency symbols. Values are assumed to be in the currency of the CID of record for the import. |
16.2 | Number | N |
online_attribute_1 | Attribute fields are tied specifically to the OrderID value, which is required for each row in a Multichannel import file.
Online attributes 1-50 map to the attribute fields that are collected by Digital Analytics order tags on your site. Use these attributes to merge online and offline data reports. |
100 | String | N |
… | 100 | String | N | |
online_attribute_50 | 100 | String | N | |
Offline_attribute_1 | Offline attributes 1-50 are for attributes that do not apply to online orders (for example, Store ID). | 4000 | String | N |
… | 4000 | String | N | |
Offline_attribute_50 | 4000 | String | N |
Data extensions import file
Data Extensions files must contain the fields listed in the Data Extensions import configuration for the primary key. The field order in the file must match the configuration.
Your Data Extensions import file must include all the data extension records that you want to use for this primary key. You must also include the records that you imported previously. Importing a Data Extensions file deletes all data that you previously imported by using the same template. The data that you previously imported by using the same template is removed and replaced with the most recent data.
The following primary keys involve values in a hierarchy:
- Content Category
- Product Category
- Element Category
- Vendor/Category
- Vendor/Category/Placement
- Vendor/Category/Placement/Item
You must use " > " (space character + greater-than symbol + space character) to separate values at different levels. For example, a Product Category value of Furniture > Desks indicates two levels of the category hierarchy. Yahoo > Email > Marketer is a correctly formatted value for the Vendor/Category/Placement key. Values without " > " are assigned to the top level of the hierarchy.
Note: When Import matches imported data with data in the database, case is ignored. For example, if the primary key of the import file is Country, and a row in the import file has GeRmAnY as the value of the primary key field and EMEA as one of the attribute values, any records in the database with a country value of germany, regardless of case, would have EMEA as an attribute.
The following are some common mistakes in Data Extensions files that cause files to fail validation.
- Duplicate Record
- Multiple rows have identical values for the primary key. Email notification indicates the number of records that failed.
- Saved Import Configuration Mismatch
- The import file does not match the import configuration you saved.
- Invalid Import File Name
- You cannot upload a file with an invalid file name through the Import user interface or through a manual SFTP process.
- Template Field Number Does Not Match Import File Field Number
- The number of fields in the import file must match the number of fields in the actual import file.
- Attribute Character Limit Exceeded
- The value of a single non-key field exceeds 256 characters. The row that contains that field is skipped. The rest of the file is imported.
- Key Field Character Limit Exceeded
- The value of a key field exceeds 4096 characters. The row that contains that field is skipped. The rest of the file is imported.
Category Definition File
When you create a Category Definition File, it must contain the mandatory fields to validate successfully.
The Category Definition File import file must include the following fields:
- Client ID
- Category ID
- Category Name
- Parent Category ID
The following are some common mistakes in Category Definition File import files that cause files or records to fail validation.
- Invalid Delimiter
- The file uses a delimiter character that is different from the delimiter character in the CDF import configuration. For example, you selected comma (,) as the delimiter for the CDF import configuration and then you import a file that uses the pipe (vertical bar |) character as the delimiter.
- Root Not Found
- The CDF import file does not have at least one root category. For example, there is no parent category or the parent category is empty.
- Invalid Client
- The CDF import file uses a client ID value in its file name that is not valid.
- Loose or Unescaped Character
- The CDF import file does not recognize double quotation marks (") as text qualifiers.
- Duplicate Category
- The CDF import file has two lines with the same category and parent category ID.
- Circular Reference Found
- The parent category for one record becomes the child category of the same category in another record.
- Category not found
- A category is used as parent category but not defined as a category.
- Insufficient Number of Columns
- The CDF file has fewer than three columns of data for a line. Each line must have Client ID, Category ID, and Category Name.
Build an import file from a template
Download your solution type's template and use the template to populate an import file.
- Go to Build > Import in Digital Analytics.
- Choose a solution type. For example, if you want to perform a multichannel import, select Multichannel. This step ensures that the template file is configured with the correct format and content for the selected solution type.
- Choose a template:
- Select a template. If existing templates exist, you can choose from one of them, or you can create a new template.
- Configure the template. Available configuration options are based on the selected solution type. For example, you configure delimiter options (comma, tab, pipe) for Multichannel.
- Click Download template. A copy of the template is downloaded to a location on your computer as indicated by your browser settings.
- Find the template file on your computer and populate it with your data. Make sure that you do not change the file configuration. For example, do not change the size of any columns.
- Save the populated template as your import file. Make sure you follow file name requirements for your solution type. Check out File name format.
Note: In the case of the Multichannel, two files are downloaded: Multichannel Shop (MCS) File and the Multichannel Order (MCO) file.
Import your data file
- Go to Build > Import in Digital Analytics.
- Choose a solution type. Make sure you select the same solution type that you selected when you created the import template in Build an import file from a template.
- In the Choose template, specify a configuration for the import file. Make sure you select the same options as you selected when building the import file in Build an import file from a template. For example, if you selected Comma as the delimiter option when building a multichannel template, make sure you select Comma now. In step 6 when the import file is processed, Digital Analytics validates the import file against the format and content specified in this configuration.
- Import the data file that you created in Build an import file from a template by dropping the file into the Import window or by clicking Browse to upload the file. If you are importing multichannel files, make sure you upload Multichannel Shop (MCS) and Multichannel Order (MCO) at the corresponding prompts.
- Optionally, specify users who you want to be notified about the import status by adding the email addresses to the Email notification list. Your email is added by default. Import sends email notifications to users to alert them of the success or failure of any files that you attempt to send. If an import fails, Digital Analytics provides file validation error detail so that you can correct your import file and reattempt the import.
- Click Process file. The validation process starts. The length of this process is proportional to the size of the file and is also affected by the number of files in the process queue. After successful validation, the data is loaded. Data is typically loaded within a few hours, but loading times vary depending on your configuration and the import type.
Imports' history
You can view a history of your imports by opening the History tab in the Import window. To open the History tab, click Expand (<<) on the right side of the Import window.
On the Import History tab, you can view recent import jobs. The history includes up to 10 import jobs per import solution type.
A file stays on the list for 30 days unless it is the last file for its import solution type or data extensions primary key. The last file for each type stays on the list until you import another file of that type.
The list is organized by solution type. You can expand and collapse each import solution section to reveal or to hide the individual import jobs. Every import job displays the file name, the date the import was processed, and the user who imported the file.
Comments
0 comments
Please sign in to leave a comment.