Islandora

Introduction

Islandora is a module that turns a Drupal 8 site into a control panel for your digital repository. Through a user interface, it allows repository administrators to

• Persist digital content in a Fedora repository
• Model digital content using core Drupal entities (nodes, media, files, and taxonomy terms). Currently, there is support for
  • collections
  • images
  • binary files (including PDfs)
  • audio
  • video
• Design forms for editing metadata
• Control the display and theming of digital content
• Perform full text searching of content and metadata
• Bulk ingest content (using Drupal's migrate framework)
• Administer fine grained access control
• Index RDF metadata in a triplestore
• Generate derivative files, such as web quality represenations.
  • Currently, only image derivatives are supported (requires islandora_image), but more to come.
• Apply bulk operations to lists of content (re-index content, regenerate derivatives, etc...)
• And much, much more...

Content in an Islandora repository is treated as ordinary Drupal content, so the entire Drupal ecosystem of contributed modules is at your disposal. In fact, Islandora uses many contributed modules itself, including the extremely powerful and flexible context module. The context module allows users to do many things through a UI that normally would require programming custom modules or themes. Want to show certain users a simplified form for data entry? Want to give each collection a different theme? Want to give anonymous users a restricted view? All of this can be done using the context module. It is similar to the rules module, and it allows repository administrators to filter repository events (view, create, update, delete, etc...) by the criteria of their choice and respond by executing configurable actions.

Requirements / Installation

Setting up a full digital repsository is a daunting task involving many moving parts on one or more servers. To make things easier to get started, you can fully bootstrap a complete repository solution using our Ansible installer, claw-playbook. It can install both to a local Vagrant environment for development purposes, or it can install to one or more remote servers by providing your own playbook. By default you'll get one server with everything on it (i.e. the kitchen sink install). But we have broken down each component into its own Ansible role, so more advanced users can create customized builds containing only what their needs require. See the README for more details.

Configuration

If you want to get up and running as quickly as possible, import the islanora_demo_feature feature to install example configuration and bootstrap your site. If you're starting from scratch, then at a minimum, you must:

1. Set the url to your message broker at admin/config/islandora
2. Enable the islandora_core_feature module, then visit admin/config/development/features and import its config. It contains everything required for basic content modeling. You can also use drush to import the feature drush -y fim --bundle=islandora islandora_core_feature.
3. Run the migration to load the taxonomy terms required by Islandora. This can be done by visiting admin/structure/migrate, or executed via drush drush -l http://localhost:8000 mim --group=islandora.

Content Modeling

Islandora uses core Drupal 8 functionality for modeling content. Most core content entities are utilized:

1. Nodes
   1. Nodes hold descriptive and structural metadata about objects in your repository. Membership between nodes (e.g. members of a collection, or pages of a book) is denoted with field_member_of, which is provided by islandora_core_feature. Additional behavior can be controlled by tagging nodes with taxonomy terms using field_tags.
2. Media
   1. Media hold technical metadata for the files they represent. There are four core media types, used for audio, video, images, and generic files. Media are associated with a node using field_media_of, which is provided by islandora_core_feature. The role of the media is indicated by tagging it with a taxonomy term using field_tags. For example, tagging a media as 'Preservation Master' indicates that it is the master archival copy of a file, while 'Service File' would indicate that it is a lower quality derivative intended to be shown to the average user.
3. Files
   1. Files hold the binary conents that are described by Media. They often created along with a media to hold its technical metadata, but can be created and then later associted with a Media in a separate process.
4. Taxonomy Terms
   1. Taxonomy terms are used to tag nodes and media so they can be classified, organized, and acted upon. They must contain a field_external_uri field that holds an external URI for the term from a controlled vocabulary / ontology. The islandora_core_feature provides a migration that can be executed to load all of the required terms for basic use into your repository.

The islandora_demo_feature provides a complete example of content modeling in Islandora for audio, video, files, and images, including tiff and JP2 support (e.g. large images). This includes some more advanced techniques, like switching display modes based on taxonomy terms so 'images' and 'large images' can share a metadata profile but be displayed differently. It also includes example actions for generating image derivatives (using the islandora_image module). You may not, however, want all of this functionality. In fact, this feature is not meant to be the end-all-be-all of content modeling, but serves as an example of how it's done using Islandora. You can take as much or as little of it as you'd like. If you're doing you're own thing, the gist is:

• When making your own content type, it will require field_member_of, field_tags, and an rdf mapping.
• When making your own media type, it will require field_media_of, field_tags, field_mimetype, an rdf mapping, and a field to hold the file. You can re-use field_media_file, field_media_image, field_media_audio, and field_media_video to do so. Media should always be tagged (field_tags) with a term from the pcdmuse ontology (preservation master, service file, thumbnail image) to denote its usage.
• When making your own taxonomy vocabulary, its terms will require field_external_uri and an rdf mapping.
• All rdf mappings need to map the changed time to schema:dateModified.

Actions

Islandora provides several useful actions for repository administrators that can be configured and executed through the user interface. Any view can expose bulk operations by adding a Bulk update field to its display.

Islandora also provides a thin wrapper around Actions so that they can be used in conjunction with the context module. Repository events for indexing, deletion, and derivative generation are all handled by selecting one or more preconfigured actions using the context user interface.

Delete Media

You can use the Delete media action to bulk delete media, but not delete source files.

Delete Media and File(s)

You can use the Delete media and file(s) action to bulk delete media and their source files.

Emit Node/Media/File/Term Event

You can use Emit a * event to a queue/topic actions to produce messages so background processes can consume them and perform work. The islandora_core_feature contains several preconfigured actions to perform indexing and removal operations for Fedora and a triplestore.

REST API

Islandora has a light, mostly RESTful HTTP API that relies heavily on Drupal's core Rest module. The majority of what Islandora provides is Link headers in GET and HEAD responses. These headers can be used to locate related resources and navigate your repository. In addition to these link headers, there are additional endpoints exposed for uploading files, as well as a couple of useful REST exports.

Exposed Headers

Referenced taxonomy terms (Nodes and Media)

The taxonomy terms used to tag content are exposed as link headers with rel="tag" and a title equal to the taxonomy term's display label. If the term has an external uri in a controlled vocabulary, then that uri is provided. Otherwise, the local Drupal uri is provided. For example, if a piece of content is tagged with taxonomy/term/1, which has a display label of "Example Term", then the link header returned in a GET or HEAD response would look like Link: <http://example.org/taxonomy/term/1>; rel="tag"; title="Example Term"

If instead the term were to have the field_external_uri field with a value of http://purl.org/dc/dcmitype/Collection then the link header would look like Link: <http://purl.org/dc/dcmitype/Collection>; rel="tag"; title="Example Term".

Referenced entities (Nodes and Media)

Entity reference fields are exposed as link headers with rel="related" and a title equal to the entity reference field's display label. For example, if http://example.org/node/1 has an entity reference field name "Associated Content" that references http://example.org/node/2, then the link header returned in a GET or HEAD response would look like Link: <http://example.org/node/2>; rel="related"; title="Associated Content".

Associated media (Nodes only)

Media entities that belong to nodes and are tagged with terms from the PCDM Use ontology are exposed as link headers with rel="related" and a title equal to the display label of the taxonomy term. For example, if a Media is tagged as Preservation Master indicating that it is the archival copy, the link header returned in a GET or HEAD response for a node would look like Link: <http://example.org/media/1>; rel="related"; title="Preservation Master".

Source files (Media only)

Files that are the source for Media entities are exposed as Link headers in the GET and HEAD responses with rel="describes". The endpoint to edit the contents of the source file is also exposed using rel="edit-media". For example, if http://example.org/media/1 has the source file http://example.org/file.txt, then a GET or HEAD response would contain both

• Link: <http://example.org/file.txt>; rel="describes"
• Link: <http://example.org/media/1/source>; rel="edit-media"

Exposed Endpoints

/media/{media}/source

You can PUT content to the /media/{media}/source endpoint to update the source file for a media. The Content-Type header is required in addition to the PUT body. Requests with empty bodies or no Content-Type header will be rejected.

Example usage:

curl -u admin:islandora -v -X PUT -H 'Content-Type: image/png' --data-binary @my_image.png localhost:8000/media/1/source

/node/{node}/media/{media_type}/{taxonomy_term}

You can PUT content to the /node/{node}/media/{media_type}/{taxonomy_term} endpoint to create or update Media for Nodes. Media created in this way will automatically be assigned to the node in the route and tagged with the term in the route. The Content-Type header is expected, as well as a Content-Disposition header of the form attachment; filename="your_filename" to indicate the name to give the file if it's new. Requests with empty bodies or that are without Content-Type and Content-Disposition headers will be rejected.

For example, to create a new Image media for node 1, and tag it with taxonomy term 1:

curl -v -u admin:islandora -H "Content-Type: image/jpeg" -H "Content-Disposition: attachment; filename=\"test.jpeg\"" --data-binary @test.jpeg http://localhost:8000/node/1/media/image/1

Or, to update an existing image media that is tagged with taxonomy term 2:

curl -v -u admin:islandora -H "Content-Type: image/jpeg" -H "Content-Disposition: attachment; filename=\"test2.jpeg\"" --data-binary @test2.jpeg http://localhost:8000/node/1/media/image/2

/node/{node}/members

You can issue GET requests to this endpoint to get a list of members of a node. It is actually a REST export, and requires the _format query param. It can (read should) also be paged like other REST export. For example, to get a paged list of members for a node, ten at a time:

curl -v -u admin:islandora http://localhost:8000/node/1/members?_format=json&items_per_page=10&offset=0 

/node/{node}/media

You can issue GET requests to this endpoint to get a list of media of a node. It is actually a REST export, and requires the _format query param. Like the members endpoint, it can be paged, but is less likely to be neccessary as most nodes don't have that many media. For example, to get the full list of media for a node:

curl -v -u admin:islandora http://localhost:8000/node/1/media?_format=json 

Maintainers

Current maintainers:

• Diego Pino
• Jared Whiklo
• Danny Lamb

Development

If you would like to contribute, please get involved by attending our weekly Tech Call. We love to hear from you!

If you would like to contribute code to the project, you need to be covered by an Islandora Foundation Contributor License Agreement or Corporate Contributor License Agreement. Please see the Contributors pages on Islandora.ca for more information.

License

GPLv2