User Manual: CollectionSpace Converter Tool

The CollectionSpace Converter Tool is a Ruby-on-Rails tool that allows system administrators to upload properly formatted CSV files to CollectionSpace. Imported data can create new records or update existing records (writing over any existing data). The Tool is still under development and testing.

Technical documentation for the tool can be found in the tool’s Github repository landing page (scroll down) and wiki.

How to Format CSV Files

Please note that the tool is not forgiving. Your data must be formatted as noted, or the row will fail.

• Procedures and Authorities

• Relationships

• Hierarchical Relationships

Templates and Sample Data

Templates and sample data for procedures and authorities can be found in on the Configuration and Data Maps - Cataloging, Procedures, and Vocabularies page on the wiki, or in the Data folder on Github.

If you’re not familiar with Github, no problem! It’s a few steps to get the data into a template you can use:

• Click on the Github link

• Select the appropriate profile

• Click the name of the CSV template you’d like to use

• Click on RAW, and then copy the entire page that appears and paste it into a spreadsheet application such as Excel or Google Sheets

• The data may all appear in one column, in which case you need to edit a little bit further:

  • In Excel, select that column and then go to Data > Text to Columns. Choose “delimited” in the first window, then “next,” then change the delimiter to commas, then click “finish.”

  • In Google sheets, select the column and then go to Data > Split Text to Columns.

Once you have the columns headers and sample data please note:

• Use “Schema Field ID” row as your CSV header. If you’re using the templates from the Data map page linked above, delete the rows above it unless you need them as a guide while editing.

• For fields populated by an option list (UI Field Type = Controlled list; static), you must use the values exactly as they appear in the “Schema Option List Default Contents” row. For example, in Object Cataloging - Common, the collection value “permanent-collection” will import as expected. The following would not: “permanent collection” or “Permanent-collection”.

• For fields populated by a vocabulary (UI Field Type = Controlled list; dynamic), the CSV value needs to exactly match the value in the “Name” field of the vocabulary. This includes capitalization, spacing, and any included punctuation. (Variations will be imported and will display, but they will not be matched up with/reconciled against the vocabulary, introducing inconsistency in your data)

• For fields populated by an authority (UI Field Type will mention authority), the CSV value should exactly match the Display value field of the appropriate authority. If there is a mismatch, the term used in your record will not be connected to the authority as expected and a new term will be created.

• Please test a few rows of your data carefully before proceeding with an entire batch! Tips and examples of how to test are available at: Testing your import.

How to Import and Transfer CSV Files

There are two steps to getting data into CollectionSpace via the CSV Import and Data Update tool. The data must be imported into the tool, and then transferred into CollectionSpace.

If your data uses authority terms, it is preferable (but not required) to import the authority terms first, then the procedural records that use those terms.

Procedures, Authorities, and Relationships

Procedures, Authorities, and Relationships
Format procedural or authority data according to the templates provided on the Configuration and Data Map page Format relationship data according to this template. Relationships can be between two procedures, or between an object and a procedure. Format hierarchical relationship data according to this template. Hierarchical relationships must be among terms in the same authority. The hierarchical relationship importer can also be used for hierarchical objects. In this case, remove the ‘subType’ column, as it is only used for Authorities.
Open the converter tool. If you don’t see the screen at right, select Import > CSV from the menu at the top left of the screen.	Open
Choose a name for your import, the name itself is not important but it can be useful to include the date and the procedure, e.g. Acquisition_Jan29_1 From the profile menu, choose the procedure you’re importing data to, or if you’re importing Relationships or Hierarchies Upload your CSV file Click the Upload button	Open
The batches menu will show you the progress of your import Refresh your screen to update the menu
When all records have processed (should match the number of rows of data in your CSV), click the gray transfer button at the top left
From the transfer menu, choose the Action (transfer), Type (procedure name), and Batch - the name you gave your import earlier Click the Process button
The batches menu will show you the progress of your transfer Refresh your screen to update the menu
When all records have processed (should match the number of rows of data in your CSV, double for relationships), you will be able to view the records in CollectionSpace.