Importing Collection Items

Depending on the nature of the collection, they have the potential to contain a lot of content. While individual collection items could be created manually or via Easy Form submissions, it can be much easier and faster to bulk import them. 

This article will focus on how to complete an import of collection items; specifically, you'll learn how to:

• Prepare your .csv file for import
• Map content from a .csv file to your Stacks collection
• How to import your collection items
• Re-import to add or edit collection items
• Why imports might fail

Preparing your .csv file for import

A basic spreadsheet can be used to list all of the items and data you want to add to your collection. While the building of such a spreadsheet is fairly straightforward, there are some considerations to take into account.

• Use the columns to identify the fields of data that you are importing, each column will be mapped to a field in the collection in your Stacks site
  • While a header row is not required, it is recommended
• Each row should contain the content for a single item that is being imported
• Each cell will contain the data associated with the field the row/column represents
  • Caution should be taken here with certain characters, especially if you are using delimiters to distinguish between multiple values within a single cell
• Once the spreadsheet has been built and all content added, save a copy in the UTF-8 format, as this format is required for importing

Field mapping

Once the collection has been initially created, the collection labels have been updated, and the spreadsheet built, the next step is to map the fields from your collection to the associated column(s) of data in your .csv file. 

1. From the Dashboard, click the Collections tile
   1. Find the collection by
      1. Browsing the list; or
      2. Searching the list by collection name
   2. Once found, under the Operations column, click the drop-down arrow, then click Import
   3. Click the Import menu tab near the top of the screen, then the Settings tab just below
   4. Click the menu options on the left to configure the import
      1. Regular Fields (including Generic fields)
         1. From the drop-down for each field, select the corresponding column letter on the .csv file
         2. The field labelled with '*' is typically used for the collection item's name/title and is the unique identifier for the item
            1. This is important if/when re-importing, so new and existing items can be distinguished from one another
      2. Filter Vocabulary Fields
         1. From the drop-down for each filter vocabulary field, select the corresponding column letter on the .csv file
         2. Important! For any unused fields, leave the drop-down selected as -None
      3. Link & Button Fields
         1. From the drop-down, select the corresponding column letter on the .csv file
         2. Important! If you import both links and buttons, be sure to review the delimiters in Extra settings section (described below)
      4. File Fields
         1. From the drop-down, select the corresponding column letter on the .csv file
         2. Important! Files must be uploaded to Stacks separately, the associated column in your .csv file should only contain the names of the files that were uploaded. This will then map the already uploaded file to the appropriate collection item
         3. Important! Stacks supports file sizes upto 64MB per file, excessive amounts of files can affect site performance. 
            1. Tip! If your collection contains a large amount of files, we strongly recommended these files be stored outside of Stacks, and use the Link or Button options described above as an alternative option for users/patrons to access this content
      5. Extra Settings
         1. If needed, update the appropriate delimiter that was used in the .csv file to identify separate values when there are multiple links, buttons, and/or terms in a single column
         2. Tip! Your choice of delimiter may differ based on the language or region settings of the device used to create the .csv file
   5. Click Save Configuration when finished

Importing the .csv file

To import the collection:

1. From the Dashboard, click the Collections tile
2. Find the collection to import items to by
   1. Browsing the list; or
   2. Searching the list by collection name
3. Once found, under the Operations column, click the drop-down arrow, then click Import
4. Click + Add import, complete the fields:
   1. Title, add a title for the import, this is used for internal reference
      1. It is recommend to use something that will allow administrators to easily identify the import should it need to be rolled back later
   2. File
      1. Click Choose File, then browse to and select the .csv file (in the UTF-8 format)
   3. Delimiter, if applicable, select the character that is used to delimit data (separate multiple values) within the cells of the .csv file (described in the mapping section above)
      1. Many regions use a comma; however, there may be cases where your language or region uses a different character, for example, Germany uses a semi-colon
   4. No Headers, check this box if your .csv file does not contain a header row
      1. Tip! It is recommended that all .csv files contain a header row for easy reference and management of the file
5. Click Save and Import
   1. Important! Do not navigate away from the page that displays the progress bar until the import is complete
      1. As the Import progresses:
         1. The title will be checked against all existing collection items, if there is an exact match, the collection item in the .csv file will be skipped
         2. The progress bar will indicate the activity for each collection item; it is normal to see the progress bar completing and restarting multiple times
         3. Once complete, you will see a message indicating the import was successful; or if an error occurred, information about the failed import will be provided

Re-importing to add or edit collection items

It is possible to update an existing collection by adding new items or editing the details of existing items by importing a new .csv file. 

A couple of important items to note when performing this function:

• While the original import spreadsheet does not have to be used, the column(s) must match to ensure proper import
• Items will be added if they do not currently exist in the collection
• In order to edit the details of an existing collection item, it must have the exact same Title (column that is mapped to the '*' field during field mapping) on the new import spreadsheet; any other information can be different and will be updated upon import
  • If the Title differs, the item will be added as a new item
• Items that are an exact match in both the existing collection and new import spreadsheet will be skipped during import
• Existing collection items that are not included on the re-import spreadsheet are not deleted. Collection items can only be deleted manually, see the Manually Creating, Editing and Deleting Collection Items article for information

To complete the re-import, follow the same steps in the Importing the .csv file section above.

Why Imports Might Fail

If your import failed, there could be a few reasons for this, the most common being

• Navigating away from the progress bar page when the file is importing
• Exceeded the maximum file size; ensure your import file is less than 64MB
• Your data contains invalid characters, review the .csv file content and update if needed
  • Be cautions with the characters used in any data to ensure it isn't also being used as a delimiter!
• The mapping is incorrect, review the mapping to ensure the fields/columns match
• The delimiters are incorrect, review the .csv file to ensure the delimiters match the configuration

If your you import was successful, but you find errors in the items that have been imported or wish to rollback the import for whatever reason, refer to the Rollingback a Collection Import article.