Importing data with TDI

Before you start an upload, review the information available in the Introduction to TDI article and follow the guidance provided in the article.

To see a list of the specific field mapping table articles, skip to the Entity field mapping table articles section in this article.

Upload sequence and order of operations

There are three main TDI entity dependency categories that determine the upload order sequence.

Entities that are dependent on other entities.
- Note: These will be noted as Prerequisites in the entity mapping tables found in the TDI section of the Help Center.
Entities that are not dependent on other entities.
Entities that are not dependent on other entities but may be more easily configured if certain entities are uploaded first.

Due to these considerations, we recommend uploading entities in the following order (as needed):

Group
User
1. Contact*
Parent
Factor
Carrier
Customer
Other account
Location
Contact**
Asset
Items
Order
Shipment
Contract
Routing Guide

*Note: If you have a single contact that is associated with multiple entities (Parent, Factor, Carrier, Customer, Other account, and/or Location), you can upload the Contact entity before the Parent and other account-related entities. If you do so, when you are configuring these other entities, you can plug in the contact.csv’s context ID into the other entities’ files in multiple areas, such as the Primary contact or Billing contact. However, if you do not have a contact that is associated with multiple entities, it may be easier to upload the Contact entity after the account-related entities, so that the contact can be configured with the correct IDs for the account they are associated with.

**Note: If the Contact entity was uploaded between the User and Parent entities, do not upload it again between Location and Asset. Otherwise, upload the Contact entity between Location and Asset.

Considerations for upload order

While you are not required to upload your files in this exact sequence, we highly recommend following the order outlined above to allow entities to be mapped with each other at the time of upload. A newly uploaded entity cannot reference information from another entity that does not exist yet.

For example, the Factor entity can technically be uploaded before the User or Contact entity. However, the following columns in two of the Factor entity’s files are dependent on IDs found in the other entities:

The primaryContact.id column in factor.csv references the unique system ID for a contact, found in the id column of the Contact entity’s contact.csv file.
The user column in user_commissions.csv references the unique system ID for a user, found in the id column of the User entity’s user.csv file.

If the Factor entity is uploaded before these other entities, then the columns must be left blank when uploading the Factor entity’s files. If you wish to provide contact and commission information for factors, you will need to fill in the user and contact information manually in your factors’ profiles on your Turvo tenant at a later time.

Step-by-step upload guide

Step 1:

Step 2:

Click on the Turvo data importer tile.

Step 3:

Click DOWNLOAD TEMPLATE to access the list of available templates.

Step 4:

Select the entity you wish to update from the drop-down.

Step 5:

Once selected, you will see all available template files for that entity. The file listed first is the mandatory file, and all others are optional files.

Step 6:

Download the templates by clicking the DOWNLOAD button. All mandatory and optional files will be downloaded as a .zip folder.

Mandatory vs optional files are not obviously marked, but there is a simple way to tell which is which:

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.

Open the folder to access the templates and fill them in using the field mapping tables within this document.

What to expect in the downloaded .zip folder:

Mandatory file
1. This is a required file to upload that specific entity.
2. This file will always have the name of the entity as its name (entityname.csv)
Optional file(s)
1. Not required for successful entity data upload.
2. They are provided to add more information for each entity.

Refer to the articles linked in the Entity field mapping table articles section for the corresponding entity to understand how to fill in the .csv columns.

Step 7:

Once the template has been filled out, save the document as a .csv file.

Step 8:

Click the upload button to upload the files.

Step 9:

An Upload files modal displays. Select the entity you would like to upload from the list. Once selected, the list of available mandatory and optional upload files for that entity will appear.

Step 10:

Upload files must be dragged and dropped or selected into the correct slot for the template type. Always place the mandatory file in the top file slot in the Upload files modal.

Optional files must be placed in the correct slot in order to correctly upload. For instance, if you are trying to upload a contact_info optional file, you must place it into the contact_info slot.

See screenshot below which shows the user uploading the mandatory file along with the contact_info file. Note how the files are named as well. Click PROCESS to start the upload.

Step 11:

You will be taken back to the Turvo Data Importer dashboard where you can check the status of the import. New imports will show up in Processing status and may take a few minutes to a few hours to process depending on the file size and time of day.

See the next section on TDI Dashboard for important areas to focus on in the dashboard.

TDI Dashboard

The TDI Dashboard is where you can view a summary of information about any current or past uploads. The dashboard indicates upload status, errors, and has information required by Turvo Support should you need to reach out to us for assistance.

Dashboard Overview

Review the table below to understand dashboard columns. Each row in the table corresponds to a column shown in the TDI Dashboard.

Column	Description
Job ID	Unique ID for the upload which you must provide to Turvo Support when reaching out for TDI troubleshooting assistance. This is what allows Turvo to investigate a particular upload.
Entity Type	Displays the entity being uploaded. Note that only one row is created per upload. For example, you will not see a separate row for each .csv file uploaded simultaneously for a single entity.
Status	Indicates the status of the upload. See Upload statuses below for additional information on each status type.
Successful records	This shows the number of successful rows vs the number of total rows attempted. For successful uploads, the numbers should match.
Uploaded by	Indicates the user who performed the upload.
Upload date	Indicates the date/time of the upload.
Last updated	Indicates the last time that an update was received from the platform. Once an upload is completed, this field should not change.

Upload Statuses

Statuses displayed in the Status column indicate whether the upload was successful. Use the status displayed to understand what steps to take if your upload did not complete successfully. The Action column indicates recommended troubleshooting steps. These troubleshooting steps should be followed prior to reaching out to Turvo Support.

Status	Indication	Action
Processing	Indicates the system is working on completing the upload. An upload may be in this status for a few minutes to a few hours depending on the file size and time of day. Turvo throttles upload speed during peak working hours to reduce load on the system.	N/A
Terminated	Uploads that are too large to process are terminated by the system. Any upload that processes for more than 5 hours will be terminated.	Check your file size to ensure each .csv contains 5,000 rows or less. Try uploading after hours when there is less load on the system.
Failed	The file contained errors which prevented successful upload.	Check the corresponding errors .csv file that appears in the Errors column of the Dashboard.
Completed successfully	All rows were successfully uploaded.	N/A
Completed with errors	Some rows were successful while some rows were not.	Check the corresponding errors .csv file that appears in the Errors column of the Dashboard.

TDI Errors

If your import comes back with a status of Failed or Completed with errors, an error file will be created and available for download in the right pane pop-out when the upload job line is selected:

Click the DOWNLOAD ERROR FILE button available in the right pane column to download a copy of the error.csv to your computer to view the details of the error and next steps to resolve the error.

Entity field mapping table articles

You can find the appropriate field mapping tables and their prerequisites for upload in the following articles. Click the link to open the article in a new tab.

Importing data with TDI