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:
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:
- First, create your Accounts (or Organizations)
- then you will need to create your Contacts (Leads or Customers)
- 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.
5. Ensure the Date fields have the correct and only supported format: YYYY-MM-DD
|Date and time, with a space between the date and time. Time is in the 24-hour clock format
|ISO standard for midnight time
6. Review every column and make sure their titles match their fields on FreeAgent.
Review even whether they are uppercase or lowercase.
It is important to review the Form Fields and make a thorough investigation to match the specific name names and values.
7. Field Mapping
After we have reviewed everything is correct, we need to complete the Field Mapping. If we get a 'Do Not Import field' by default, that means that the import will not work, so we need to double check that specific field.
If You Are Updating Existing Records
We follow the same steps from above, but here we make sure that the column with the ID/Unique Identifier is correctly referenced to indicate which records are being updated.
Best Practice: It is advised that when updating your data through import, you only update the data you want to change.
For example, if a Contact record in your FreeAgent instance has 100 fields and you want to update the Contact Owner field via import, all you should include is the ID of the Contact and the Contact Owner field.
If you are updating notes or tasks, you need to make sure that the relevant references are included in the file so that the imported records can appear in their corresponding Timeline.
- To keep the field mapping process simple, make sure the column names are the same as field names. The Field Mapping will try to match column names in your spreadsheet to system field names.
- Beware of extra (blank) columns at the end of your file. These will cause errors.
- The first column should be as populated as possible, not sparse. This may also cause errors.
- Check and make sure all drop-down values exist. Case sensitive. This is true for any Choice List information as well as for Reference values.
- Avoid using the Create Field option when importing. It's best to create the fields beforehand.
- & could get imported as &. So you may want to find/replace &s with and's.
- The importer will update records if the record value is found in the ID column, otherwise, it will create the record.
- Columns with missing headers will also cause the importer to fail.
- Calculated fields are not calculated on import. In order for the calculations to occur, the records need to be updated at least once.
- We recommend not to use apostrophes " ' " within your file, these sometimes cause errors during import.