Search

Introduction to TDI

Turvo Data Importer (TDI) allows users with Admin or Super Admin privileges to bulk upload data into the Turvo platform using .csv files in a specified format. TDI allows the user to create new entities as well as make updates to existing entities via file import.

This guide provides instructions to use the import function as well as how to fill out .csv files to meet successful upload requirements. TDI has specific requirements for use. Read this article and the following articles to understand how to use it before proceeding:

Upload entities

Different types of system data can be imported into Turvo using TDI; those different types of data are called entities.

Currently TDI supports bulk upload for 15 entities:

  • Groups
  • Users
  • Parents
  • Factors 
  • Carriers 
  • Customers 
  • Other accounts
  • Locations
  • Contacts
  • Assets 
  • Items
  • Orders
  • Shipments
  • Contract
  • Routing Guide

Each entity has a set of .csv file templates that must be used to upload. An entity will have one mandatory file and may have a set of optional files as well.  

Mandatory and optional template files

Mandatory files are required to upload. There is only one mandatory file required for each entity.

Optional files are used to provide additional, non-essential information about an entity.  For instance, a common optional file is called communication_channel.csv and this file allows the user to provide additional information around methods of communication—additional email addresses, phone numbers, or addresses– is not required in order to create the entity.

How many optional files you need to upload per entity varies. You can upload as many or as few as you need, you don't need to upload any optional files for a successful load. 

Here is how you tell which is mandatory and which is optional:

  • Mandatory files always have the name of the entity as the file name (Ex: user.csv)
  • Optional files are all other files that are not named as the entity.

How mandatory and optional entity files are related

Mandatory and optional .csv files are separate. When you enter a unique ID in a mandatory file, that same ID becomes the context ID in the optional files for the entity.

Mandatory_file_Optional_file.png

Example: In the user.csv mandatory file, you input 983271 as the user’s ID. In the communication_channel file for users, you would input 983271 as the Context ID to link a particular email, phone, etc. to that user.

Preparing template files for upload

Important note: Columns within these templates should not be renamed, changed, or rearranged in any way. Even if a column is blank, do not remove it from the template.

Within this manual, we provide field mapping tables for each entity (see the TDI field mapping articles for the corresponding entity for more information). These tables detail how to fill in each mandatory and optional .csv file and are an essential reference for a successful upload.

Unique identifiers

Unique entities are identified by their reference IDs (“id” column in the template). This ID is used to create new entities as well as to identify updates to existing entities. If an upload is processed with IDs that do not already exist in the system for that entity, a new entity will be created as a result of the upload. If the ID already exists in the platform, the entity with the corresponding ID will be updated with the new information.

Format and restrictions

Within a template, certain fields may require a certain format or have character restrictions, or you may be required to enter a Turvo code or value which corresponds to a particular attribute. Format, character restrictions, and available values or codes are denoted within the field mapping files for each entity (shown below). Make sure to read the field mapping carefully.

Required and conditional fields

There are certain fields that are required for upload. These fields are marked with an asterisk within the downloaded template file itself:

Note: You can also use the field mapping tables within this document to find required fields in each template. Fields marked with an asterisk are required.

There are also conditional fields. Conditional fields become required when you opt to add specific optional information for an entity.

For example, if you enter an Email or Phone number into a communication_channel.csv file, you will then be required to specify an Email or Phone type. The Email.type and Phone.type fields are conditional; they become required if you enter the corresponding Email or Phone master field. Conditional field requirements are mentioned in the Format/restrictions column:

Naming upload files

All mandatory .csv files that are uploaded for a specific entity must be saved with the entity name at the beginning of the file name. For instance, any files uploaded for the carrier entity must begin with the word “carrier.”

Optional file names must start with the original name of the optional file. For example, if you are uploading a communication_channel file for users, its name must start with “communication_channel.”

Every file name must correspond to the original file name. We recommend including upload dates at the end of the files names, such as “communication_channel_usersFeb2021.csv” or “carrier_March2021.csv” to help you keep track of which file it is and when it was uploaded.

Important upload restrictions

  1. Only .csv file format is supported for upload. If you are working in Excel, the default file type is .xlsx.  Make sure to save as .csv.
  2. Maximum of 5,000 rows per .csv file. If you have more than 5,000 entities to upload, you will need to break the files down into increments of no more than 5,000 rows.
  3. Maximum size of 5MB per .csv file.
  4. Uploads take time and are not instantaneous. During business hours, you will need to wait awhile, potentially hours, for larger uploads to complete.

Was this article helpful?

0 out of 0 found this helpful