Troubleshoot: Importing your Data

Overview

Before proceeding, we recommend you review our guide on importing your data in FreeAgent first. 

Imports are a very important part of our being able to manage your data in FreeAgent. 

When an import fails, there are a few things that could be involved. This guide should help you to identify the issue and hopefully provide a solution. 

This article will cover the following:

1. If you are Importing New Records
2. If you are Updating Existing Records
3. Special Considerations

Let's go over a few different scenarios and possible fixes for each.

If you are Importing New Records

1. Download the errored file 

This step will help you to understand the problem from the system’s perspective. 

Understanding Import Errors 

As your CSV is being imported, when an error is encountered in a row, this row will fail to Import.  The import process will continue and an Error Description column will show the error(s) per row.  At the end of the import process, you will have the option to retrieve all the Failed rows in a CSV to review and remedy.

You will see Processed / Added / Updated / Failed columns in your Import.  Click on 'Failed' to generate a new CSV containing all Failed rows and error description(s) shown conveniently in a new column.

The system will identify the first 1000 errors.  If an import reaches that threshold, the import process will be cancelled.  The resulting Failed CSV will show the rows that failed along with rows that were unprocessed before failure. 

There is no size limit for the CSV file, so this will not be the cause of an import error or failure.  However, if an import process does not finish within 24 hours, it will automatically timeout.  As a rule of thumb, 100K records will process in approximately 3 hours, depending on how many columns your file has.  Use these guidelines to decide whether to split a very large file into smaller imports.

Let's look at each of the errors in detail.

Error Description Meanings

Sometimes there are issues with an import. You'll notice in the screenshot we've been told that two rows failed. If you click on the number next to Failed Rows you'll be prompted to download a csv which will contain the reason for the error.

"Skipped." This does not signify an error in the row.  It means the threshold for errors (1000) has been reached and the import process shut down before this row could be processed.  Thus it was skipped.

"The reference value could not be found". This error is usually found in columns that map to Choice List or Reference fields. It means that the value used in that cell of the file doesn't exist in FreeAgent CRM. 

In order to solve this error, make sure that the value in your file looks exactly the same as the options in FreeAgent CRM, they are Case Sensitive. 

If the Choice or Reference doesn't exist, create it first and then try to import your file again.

"This is not a valid number". This field type expects a number, either an integer or a decimal.

"This is not a valid number: null".  If the App you're importing to has any calculated fields and you import into a said calculated field, this error may result.

"This is not a valid date". The date field also expects a specific format. The date should include day, month, and year. The year should include 4 digits. The date should be formatted like this: YYYY-MM-DD e.g. 2020-06-04 

"This is not a valid email address". When this error is found, it usually means that the email address is missing the '@' sign or the domain extension (.com, .net, .edu, etc...)

"This is not a valid phone number". The most common cause for this error is including the extension with the phone number. Extensions should be saved in a separate field. The phone number format can include '()' and/or '-'.

"This value violates unique field". This error means that your file contains duplicated information. For this to happen there needs to be a field in your App configured as "unique". The system will validate the information in the system and if the value already exists in any record of your App, it will show this error message. 

2. Make sure that you are only adding relevant information for yourself and your team.

Make sure that phone numbers, addresses, emails, etc.. are well-formatted. Your file shouldn't include any empty columns or rows.

There are some specific formats pre-established by the customer and those need to be honored in the file. Going to see the Form Field types is very important and helpful to make sure the correct format is being used. In the case of the empty columns or rows, below there’s an example of what should and should not be included:

3. Review if the customer honored the Import Sequence

Given the existing relationships in the data, the import process should follow a specific order. The name of the Apps may vary based on your team's configuration but the order should be:

1. First, create your Accounts (or Organizations)
2. then you will need to create your Contacts (Leads or Customers)
3. lastly your Opportunities (Deals or Sales)

This way, if you try to update records via import - you will be able to reference the previously created records with their corresponding ID.

4. Review the Unique Fields

This is very important, especially when you input different information than what you should input or when you include repeated (non-unique) information. For updates, you can use the Unique Fields instead of the FreeAgent ID.