User Manual: CSV Importer: Import a CSV File

To import a file into the CSV Importer, you must have an account, be part of an active group, have established a connection with an existing CollectionSpace instance, and have a properly formatted CSV File.

  • Login as a User who has been Enabled and added to a Group

    • Tip: If you are a member or more than one Group (most users are not), check next to your user name to see your active Group. If the Group you see is the Group you’d like your Batch to be associated with, move to the next step. If the Group you see is not the Group you’d like your Batch to be associated with, click on your user name, select the Group you’d like to be your active Group from the dropdown, click Submit, and then move to the next step. 

  • Select the Batches top menu item

  • Select Create a batch +

  • Enter a brief but descriptive name for your batch

  • Select the Connection you’d like to use (most users will only have one)

  • Select the Mapper you’d like to use, this aligns with the type of record data you are importing or updating (e.g. Object Cataloging or Loans).

  • Select the CSV file you’d like to import from your file system

  • Expert only: If you would like to override any of the default data mapping configuration (e.g. using | to separate multi-valued fields), you can enter overrides into the config field. Documentation for data mapping configuration is here.

  • Select Submit

The Preprocessing step ensures that your uploaded CSV has the required fields necessary to move through the Batch Import process. Steps following Preprocessing provide more detailed reports on the individual values in your CSV.

  • From Step 1, confirm the Summary details of your Batch are as expected (e.g. Name, Number of rows, File name)

  • If correct, select the Start button in the Preprocessing step

  • Once the progress bar is at 100% complete and the Preprocessing header reads Finished or Failed, refresh the page using the Refresh page button in the Preprocessing section to complete the step

  • After page refresh, the Preprocessing Message box will share details including:

    • How many fields (columns) will import

    • How many fields (columns) will not import

    • A list of wholly missing / partially missing required values. Wholly missing would mean an entire field (column) such as ID Number is not present, partially missing would mean one or more rows in that required field (column) are empty. 

  • If Preprocessing has Failed, the issues highlighted in the Message box must be fixed. After fixing, delete the failed batch and go back to Step 1. 

  • If Preprocessing has Finished, click the Next button

  • If Preprocessing is “hanging” on Preprocessing (Running), check your CSV for:

    • Missing column headers or incorrectly formatted column headers

    • Merged cells in your CSV - sometimes Open Office will merge cells copied from Excel. To remove all merged cells in Open Office, select your whole workbook, and go to the Format menu. Make sure Merge Cells does not have a checkmark next to it.

The Processing step determines the current CSpace record status (existing or new) of each record generated, translates authority and vocabulary terms into CSpace refnames to provide proper linkage in generated records, provides a report of unique authority/vocabulary terms in your data that do not yet exist in CSpace, and provides a processing report of any potential data issues.

  • When ready, select the Start button in the Processing step

  • Once the progress bar is at 100% complete, refresh the page using the Refresh page button in the Processing section to complete the step

  • After page refresh, any issues with your file discovered in Processing will appear in the Messages box. You can download your file to view more detailed error and warning messages.

  • If there were no issues with your file, move to the next step by clicking the Next button

  • If there are issues with your file, download the report file(s) and examine them. 

    • If the issues are only warnings that are not blockers to your load, you can proceed to transferring your records. 

      • If there are errors or warnings that you need to correct before loading, delete this batch. Correct the errors in the downloaded file, and create a new batch to process the revised file.

        • Tip: You may want to delete any error/warning columns before processing the revised file. If you leave them in they will be ignored by the processor (though the preprocessing step will indicate their presence).

The Transfer step will transfer the records in your CSV file to your CollectionSpace instance.

  • From Step 3, confirm the following checkboxes:

    • Create new records? Check if you would like the CSV Importer to add new records to your CollectionSpace instance based on your CSV data.

    • Update existing records? Check if you would like the CSV Importer to update existing CollectionSpace records based on your CSV data

      • Critical tip: If you don’t check either of these, transferring won’t do anything. You can select one or both of the boxes. 

    • On the roadmap: There is currently a “Delete existing records?” checkbox, but it is not yet working. Once enabled, if you uncheck the other two boxes, you will be able to select “Delete existing records?”. When selected, the delete option will cause any existing CollectionSpace records matching your CSV data to be deleted. 

This is a "hard" delete, which removes the record and all of its data from the CollectionSpace system. Unless an export or backup has previously been performed, the record and its data can be considered permanently deleted and unrecoverable.

  • When ready, select the Start button in the Transferring step

  • Once the progress bar is at 100% complete, refresh the page using the Refresh page button in the Transferring section to complete the step

  • After page refresh, any issues with your file after Transferring will appear in the Messages box. You can download your “full_report” file to view more detailed information

    • This report contains your full original CSV data plus any columns added from the processing step

    • It adds the following columns: XFER_status (success or failure), XFER_message (Updated, Created, Deleted), XFER_uri (link to view the resulting XML record in CollectionSpace via the services API).

The Archive step deletes all files associated with this batch that are being held in the CSV Importer’s internal storage. Archiving will also mark the batch as complete, and it will be viewable only via the Archive Tab under the main Batches menu.