CSV upload

This plugin is better suited for administrators and users with elevated permissions in order to obtain the correct information and due to the risk of inserting incorrect data into ResourceSpace.

New version - Updated for version 9.3

The plugin has been updated to allow you to edit existing resource metadata as well as create new resources by uploading a CSV file.

You can now choose to: -

  • Upload resources using any method e.g via StaticSync and then update metadata using a CSV
  • Use a CSV to create the resources and then use batch replace functionality to upload the associated files
  • Download resource metadata from search results or a collection (see CSV Export), edit the data in the CSV and re-upload it to update the resources

The new process is split into steps as below

Step 1 - Select file

On this page you can:-

  • Select the CSV file to upload
  • Choose whether to create new or update existing resources
  • Select a previously saved CSV mapping configuration file to make the process quicker*
  • Clear any existing mapping configuration to upload a CSV in a new format
* Saving the configuration stores the column position, not the column name so this requires the CSV columns to be in the same order

Step 2 - Set options

If creating new resources

  • Choose to add the new resources to the currently selected collection
  • Select the column that contains the resource type
  • Set a default resource type if no column is selected or if no valid value is found
  • Select the column that contains the workflow state (e.g. for a default installation, -2 = Pending submission, -1 = Pending review, 0 = Active, 1 = Waiting to be archived, 2 = Archived)
  • Set a default workflow state if no column is selected or if no valid workflow id is found
  • Select the column that contains the access level (0 = Open, 1 = Restricted, 2 = Confidential)
  • Set a default access level if no column is selected or if no valid access value is found

If editing existing resources

  • Limit the resources that will be updated to those in one of your collections
  • Select the column that contains the resource type. Leave unselected to keep the resource type unchanged
  • Select the column that contains the resource identifier. Normally this will be the resource ID or filename
  • Select whether you are matching on resource ID or metadata field
  • If matching based on metadata, choose the action should multiple matching resources be found

Step 3 - Map CSV columns to metadata fields

On this page you define which metadata fields the CSV columns relate to. The plugin will attempt to automatically select the correct field if the column header matches the field title or shortname.
Any columns that are not required can be marked as 'DO NOT USE'.

Click 'Next' When you are happy with the mappings.

Step 4 - Checking CSV data

This is the 'dry-run' stage. ResourceSpace will process the CSV file information but without changing any data. Any errors or warnings (up to a maximum of 100) will be reported. If you want to change any data in the CSV you will need to return to step 1 and re-upload the amended file.

Click 'Process' if you are happy to proceed and the file will be processed

Step 5 - Processing CSV

ResourceSpace will process the CSV file information, creating or updating resources as required.

Click 'Process' when you are happy and the file will be processed

You now have the options of uploading another CSV file or downloading the current mapping configuration as a file so that you can use it in the future, or distribute it for use by other users who can upload CSVs in the same format.

Notes for version 9.2 and earlier

This plugin allows you to create resources by uploading a CSV file. This is used in tandem with the Batch Replace admin tool as another method to batch upload resources. The CSV Uploader creates the resource and metadata and then you can use batch replace to add resources to the CSV created resources.

The format of the CSV is important and must be created according to set rules:

  • The CSV must have a header row
  • The CSV file must be encoded in UTF-8 format and without BOM
  • The CSV should have text cells quoted in case they contain commas or other special characters
  • To create resources of different resource types there must be a column named 'resource_type' containing the reference ID of the resource type (e.g. 1 is Photo)
  • To assign different archive states to the resources there must be a column named 'status' containing the status ID:
    • -2=Pending submission,
    • -1=Pending review,
    • 0=Active,
    • 1=Waiting to be archived,
    • 2=Archived
  • To assign different access levels (open,restricted, confidential) states to the resources there must be a column named 'access' with access values:
    • 0=Open,
    • 1=Restricted,
    • 2=Confidential
  • If you want to use the batch replace functionality, you can use an original filename field which will make for easy file matching.
  • All other column headers must correspond to the full name of a resource metadata field
  • All mandatory fields for the created resource types must be present
  • Date values should be in the format YYYY-MM-DD HH:MM
    e.g. 2:42 PM on the 25th March 2013 should be formatted as '2013-03-25 14:42'.
    If the date field does not include times then '2013-03-25' is correct

Troubleshooting Tips

Error: duplicate header fields found

This error means that the system has compared the total number of header columns with the number of distinct header columns and found that they do not match. This is intended to detect multiple columns with the same column header name, but could also indicate that you have extra unused columns in your CSV with blank header values.

Error: override resource_type X not found or headers are incomplete

This error means that the system has not found columns for all the required fields that apply to the resource type that you have chosen.

Error: Incorrect number of columns X found on line Y (should be Z)

This error means that the system has detected extra columns on line Y. There are X columns present where there are only Z column headers.

Error: Column name X found in file does not exist as a ResourceSpace metadata field

This error means that the system has detected a column header present that does not have a matching named metadata field and therefore is unable to extract the data from the resource.

File uploads however first column of CSV seems to be missing from metadata

This may happen due to encoding issues. Please make sure whatever you are using to export/save the CSV is exporting using UTF-8 Unicode and not UTF-8 Unicode (with BOM)

Error: X - the value Y is not in the metadata field option list

This error can occur with fields of type 'Category Tree' where the full path to the category tree item has not been provided. The CSV needs to use the '/' separator to specify the full tree path. The format to use is level1,level1/level2,level1/level2/level3.