Asset processing
Authentication
Collaboration
Compliance
Integrations
System
User interface
Workflow and access

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.

The CSV Upload plugin allows you to edit existing resource metadata as well as create new resources by uploading a CSV file.

 

CSV Upload offers flexibility when it comes to managing and creating new content in the system. For example, you can:

  • Upload resources using any method, including 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 process is divided into steps as set out below. It’s recommended to enable offline jobs if processing large CSV files with over 1000 rows.

Updating existing resources

If you already have metadata in CSV format, for example if you’re exporting your content from another system, you can upload your files using the standard method and then update their metadata using a CSV. 

When working with a lot of files, you can also add your resources in bulk using StaticSync before updating the metadata via CSV.

Alternatively, if your content is already in ResourceSpace, you can download resource metadata from a set of search results or a collection via CSV export, edit the data in the CSV and re-upload it to update the resources at any time.

Step 1 - Select file

First, upload your resources to a new collection. If your resources are already on the system, you could add these to a collection too. Working from a specific collection will provide a more targeted set of metadata.

From the ‘Actions’ menu, select ‘CSV export - metadata’ to download the metadata template.

Once you’ve edited your CSV and it’s ready to upload, click the ‘CSV Upload’ option in the header. From this page:

  • Select the CSV file to upload
  • Choose to update existing resources. This prevents new ones from being created.
  • Clear any existing mapping configuration to upload a CSV in a new format

You can also select a previously saved CSV mapping configuration file to make the process quicker. Saving the configuration stores the column position, not the column name so this requires subsequent CSV files to have the columns in the same order.

Step 2 - Set options

If you're editing existing resources, it's advisable to:

  • Select the option to update resources in a specific collection
  • Select the column that contains the resource type. Leave unselected to keep the resource type unchanged
  • Select the column that contains the resource identifier. For existing content, this can be the resource ID
  • Select whether you are matching on resource ID or a metadata field value
  • If matching based on metadata, you'll need to choose the action that should be taken by the system should multiple matching resources be found
  • Select the column that contains the workflow state. There is the option to select a default value which'll be applied if a row is missing a value for workflow state or if there isn't a column for the data in the csv.
  • Select the column that contains the access level. Like the workflow state there is a default that can be used if needed.

Step 3 - Map CSV columns to metadata fields

On this page, you can 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, updating resources as required.

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

Once the CSV has finished processing, you'll also have the options of uploading another CSV file or downloading the current mapping configuration as a file so that you can use it again, or share it with other users so they can upload metadata in the same format.

Creating new resources

Another option for adding resources in batches can be to first create a set of ‘empty’ resources using the CSV metadata, before uploading the files using the batch replace option.

If you're creating new resources you'll see these options in Step 2 of the upload:

  • Choose to add the new resources to the currently selected collection 
  • Select the column that contains the resource type, or;
  • Set a default resource type if no column is selected or if no valid value is found. If you're adding these into your spreadsheet, make sure you match up the resource types in your system, for example, photos to photos. If all the resources you're creating are the same type, it's easiest to just set this here - no need for a dedicated column.
  • 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. Again, this is easiest to set here unless you plan to upload your resources into different states. 
  • Select the column that contains the access level (0 = Open, 1 = Restricted, 2 = Confidential), or;
  • Set a default access level if no column is selected or if no valid access value is found.

The next step is to go to Admin>Resources>Replace resource batch to upload the files and make sure they sync up with the right record.  

Tips and troubleshooting

It can be useful to test the CSV column mappings with a small batch before working on larger groups of files. The most common error is when there’s a value in the CSV that’s to go into a fixed list metadata field but that value doesn’t exist as an option in the field in the system. You can either add it in the system, or change the value in the spreadsheet to match an existing option in the field in the system.

A few more tips to avoid common errors:

  • The CSV must have a header row
  • The CSV file should 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
  • 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
  • To include values for category trees the full path to the category tree item must be 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.
  • When uploading to a dynamic keywords list field, values containing a comma will be split on the comma to form separate keywords. If the comma is to be preserved as part of a single value, escape the value with two additional double quotes. For example, """part1, part2""".