Locations

Locations Importer

The Locations Importer lets you create new Locations or update existing ones in bulk via a .csv file upload. You can add Locations from scratch, update existing ones, or do both in the same file.

{% hint style="info" %} Note: Testing for upload of custom attributes on the Locations Importer include custom attributes of type string, number, and multiselect. These types have been tested with the importer. Other attribute types may work but have not been verified. {% endhint %}

Before you start

• Parent Location column: Always include a Parent Location column in your file, and ensure that it is populated with an existing parent Location
• Top level Locations cannot be created by importing, and must be created in ION.
• Order of creation: Create Locations one level at a time. Parent Locations must already exist in ION before you reference them as a parent. For example:
  • Upload Locations that are direct children of top-level Locations.
  • In a later upload, upload the next level down, and so on.
• Organization settings: If your organization’s Location custom attributes have changed, refresh your ION page before importing so the importer shows the latest custom attribute fields for mapping.

How to upload

1. Prepare your spreadsheet. Include the columns you need. Required and common columns:

• Name (required) – Must be unique. Duplicates will trigger a warning that the row will update the existing Location.
• Parent Location (required) – Name of the parent Location exactly as it appears in ION.
• Description, Latitude, Longitude, Type, Address, Available, Archived, Exclude from Inventory Merge (V2) (and any custom attribute columns) as needed.
• When including columns in your upload file, ensure that every row in the column contains the intended value, even if you do not intend on changing the value from what it was before. For columns with boolean values in particular, values should be TRUE or FALSE
• If you are intending to add or change custom attributes, add one column per custom attribute; the header should match the attribute name.
• For multiselect attributes, list selected options separated by a semicolon with no spaces, e.g. good;better (not good; better or good, better). Any other format will cause errors.

2. Batch size

• Use small batches (e.g. around 30 Locations or fewer) so you can check results and correct errors more easily. The importer has been tested at around 30 Locations - errors can occur with larger batch sizes; smaller batches also make auditing simpler.

3. Upload and map

• Upload your file in the importer, map columns to the fields shown (Name, Parent Location, custom attributes, etc.), then complete the import.

4. New Locations and “Available”

• Newly created Locations are set to Available by default. You do not need to include this in the file unless you want to set it explicitly.

5. Archiving (and un-archiving) Locations

• Locations can be unarchived through the importer - a process not otherwise available in the current UI
• Archiving mid level locations (with parent, child and grandchild locations) - if you archive 'child' locations the taxonomy between parent and grandchild is broken (it gets restored if you unarchive 'child') - this is general location behavior, not related to the importer

Known issues and limitations

Error handling and auditing

• The importer often shows a single, generic error message. It does not list which rows succeeded and which failed.
• Some rows may be created or updated while others in the same file are not, so it can be hard to see exactly what changed.
• Recommendations:
  • Follow the “How to upload” steps to reduce errors.
  • Use small batches, in case results need to be checked in ION
  • Test in a sandbox environment first when possible.

Updating existing Locations

The following can be changed in the bulk importer, but cannot be cleared (set to null)

• Parent Location relationships: If you leave parent Location empty for an existing Location, the importer does not clear its parent. The current parent in ION will remain, and the importer will not indicate that the “null” parent was ignored. To remove parent relationships, use ION directly.
• Custom attributes: Custom attributes (e.g. NS_ID) can be updated to new values, but they cannot be set to empty or null via the importer. Empty or null values in your file are ignored for updates. To clear a custom attribute, do it in ION.
• The importer cannot be used to change locations names, once the location has been created

Multiselect format

• Multiselect values must use a semicolon with no spaces (e.g. option1;option2). Other separators or spacing will cause import errors.

Recent testing

• Most recent testing on this feature has occurred on the .csv upload (as opposed to manually populating the FlatFile spreadsheet from scratch). The same workflow is recommended for use.

Quick reference