In this section · 10 articles

Import records from a CSV file

Add many countries, states or cities at once. Upload a CSV file, match its columns to the list's fields, then run the import and check which rows were skipped.

Applies to
Core 12.7 and later
Who can do this
Administrator
Permission
feature.core.country.bulk_import
Where
Configurations › Master Settings › Locations
On this page

Before you start

  • In Core, three lists offer import: Countries, States and Cities, under Configurations › Master Settings › Locations. They show Import CSV at the top of the page, next to Create. Add-ons can offer import on their own lists too.
  • You need two permissions for the list: the one to create records, and the one to import them. For countries these are feature.core.country.create and feature.core.country.bulk_import (Import Countries (CSV) in the role editor). States and Cities use feature.core.state.* and feature.core.city.* in the same way. The standard Administrator role has both. Without either one, Import CSV doesn't appear.
  • Prepare your file:
    • Save it as CSV, with commas between values. Excel's CSV UTF-8 is fine.
    • Put the column headings in the first row.
    • Keep it under 10 MB and 5,000 data rows.

Columns each list accepts

ListColumnsNotes
CountriesName (required), ISO Code, Phone Code, OrderISO Code and Phone Code take up to 10 characters each.
StatesName (required), Country (required), OrderCountry can be the country's ISO code, its name, or its ID number.
CitiesName (required), State (required), OrderState can be the state's name or its ID number. If two states share a name, use the ID.

Names are matched without regard to capitals, so iqz, IQZ and Iqz all find the same country. A country or state name can be in any of your languages. Order can be left empty.

Every imported record is Active. A name is saved in the language you're using Laramin in; to add it in your other languages, edit the record afterwards. Flags can't be imported. Upload them on each country.

Tip: Use the field names as your headings, for example Name, ISO Code or Country. Laramin then matches the columns for you.

Upload the file

  1. Open the list and select Import CSV. The Import from CSV dialog opens.

  2. Choose your CSV file.

  3. Select Next.

Match the columns

  1. Check First rows of your file. It shows your headings and up to five rows, so you can tell which column holds what.

  2. For each field, choose the column from your file that fills it. Fields marked * are required.

  3. Leave a field on — Skip — if your file has nothing for it.

  4. When every required field has a column, select Import.

Check the result

The dialog shows how many rows were imported and how many were skipped, for example 48 imported and 2 skipped. Each skipped row is listed with its row number and the reason, such as Row 7: The name field is required. If a Country or State value matched nothing, the reason reads The country id must be an integer. or The state id must be an integer.

Row numbers match your spreadsheet: the heading row is row 1, so the first record is row 2.

If your file had more than 5,000 rows, the dialog also says Only the first 5000 rows were read. Split the file and import the rest separately. The rows after that weren't read, and they aren't counted as skipped.

Select Close. The list reloads with the new records.

What happens next

The rows that were valid are saved, even when others were skipped. To add the skipped rows, fix them in your file, delete every other row, and import that file again. Importing the whole file again would add the good rows a second time, because names aren't checked for duplicates.

Import countries before their states, and states before their cities, so each row can find its parent.

If rows are skipped and you can't see why, see A CSV import skips rows or won't start.