Adding multiple media

By default, Islandora Workbench adds only one media per node. This applies to both create and add_media tasks, and the file that is used to create the media is the one named in the "file" CSV column. The media use term ID is defined in either the media_use_tid configuration option or in the "media_use_tid" CSV field.

However, it is possible to add more than a single media per node in create and add_media tasks. This ability might be useful if you have pre-generated derivatives (thumbnails, OCR, etc.) or if you want to add the main file (e.g. with a media use term of "Original File") and one or more files that are not generated by Islandora's microservices. Workbench looks for the additional_files configuration option, which maps CSV field names to media use term IDs. If the field names defined in this option exist in your CSV (in either a create task or an add_media task), Workbench creates a media for each file and assigns it the corresponding media use term. Here is an example of this configuration option:

additional_files:
 - thumbnail: 20
 - rightsdocs: 280

Note

The syntax of the additional_files entries is important. Be sure to include a space after the dash at the start of each entry, like - rightsdocs, not -rightsdocs.

The accompanying create CSV would look like this:

file,id,title,thumbnail,rightsdocs
main.jpg,036,Testing,/tmp/thumbs/main_tn.jpg,/tmp/rightsdocs/036.txt

The accompanying add_media CSV using the same sample file paths would look like this:

file,node_id,thumbnail,rightsdocs
main.jpg,2078,/tmp/thumbs/main_tn.jpg,/tmp/rightsdocs/036.txt

You can use multiple media use term IDs by subdelimiting them, e.g.:

additional_files:
 - thumbnail: 20
 - rightsdocs: 280|465

Warning

If you are creating Media using this feature, you should temporarily disable Contexts that would normally generate derivatives equivalent to the additional Media you are creating. Do this at admin/structure/context by choosing "Disable" in the "Operations" list for each applicable Context, and be sure to re-enable them after running Workbench. Because Islandora creates derivatives asynchronously, it is impossible to guarantee that Contexts will not overwrite additional Media created using this feature. Running --check will warn you of this by issuing a message like the following: "Warning: Term ID '18' registered in the 'additional_files' config option for field 'thumbnail' will assign an Islandora Media Use term that might conflict with derivative media. You should temporarily disable the Context or Action that generates those derivatives."

A few notes:

  • If the additional_files columns are empty in any rows, or if the reserved file column is empty because all file-related columns are listed in additional_files, you will need to add the allow_missing_files: true option to your configuration file.
  • Fixity checking is only available for files named in the file CSV column, not in the additional columns described here. See this issue for more information.
  • If you create an "Extracted Text" media, the contents of the specified text file will be added to the media's "field_edited_text" field, allowing it to be indexed in Solr.