Zum Inhalt

User Manual

Terminology

Project

A virtually isolated area for each IIIF mandate that the University Library provides for an institution.

Administration interface users defined by the institute will be assigned to one or many projects and are then entitled to see and edit all information regarding the project. The contents within a project (collection, sequences and images) are organised in a tree.

Collection

Collections are used to arrange the images in a project hierarchically (similar to a folder in a file explorer). A collection could contain one or more child collections. A collection can have child collections and / or sequences.

Root Collection

Every Project has exactly one root collection (A collection with no parent collection).

Sequence

A sequence is used to store a series of images.

Image

An image which can be accessed via the IIIF API.

Task

A task is created when an action must be performed by the system that cannot be executed immediately (synchronously). The tasks are executed in the background by the system as batch process. A task can contain further sub-tasks and, if necessary, generate new tasks.

Web interface for administration

Access to the administration web interface

To get access to the administration interface for your users, please contact openscience@unibe.ch.

Users need to create a SWITCH edu-ID account. Affiliates of the University of Bern also need to link their Campus Account to the SWITCH edu-ID account. You need to provide the University of Bern email address for users with an affiliation and the main edu-ID email address for external users.

The web interface for administration can be accessed under https://iiif.ub.unibe.ch.

Click on "Sign in" on the top right corner and use your SWITCH edu-ID account to sign in.

If you don't have permission to access the web interface you will receive a 403 Forbidden error - otherwise you will see the following menu:

Projects

This menu item provides you with an overview of the projects to which you are entitled:

Action "Show"

This button opens the Project View and displays the Project Tree on the right side.

Action "Edit"

Here you can change the name and slug of your project.

The Slug is relevant if you want to access the IIIF Image API with the source file name of the image (See Using the IIIF Image API).

Action "Delete"

Warning

This action will delete the whole project including all collections, sequences and images of this project

After clicking on "Delete" you have to confirm the action:

Project Tree

As soon as you selected a project in the projects overview page (action "Show") and as long as you are navigating trough the projects collections and sequences you will see the project tree on the right side, which indicates where you are within the project and allows you to quickly jump trough the hierarchy of the project.

Project View

This will show you the project information (id, name, slug, links to the presentation API and the root collection) and also the actions "Edit" and "Delete" which are the same as on the projects overview page.

Presentation API

The buttons will open the URL which delivers the JSON information for the root collection of the project as defined in the IIIF Presentation API v2.1 or v3.

Root collection

This link will open the information page about the root collection (See Collection View)

Action "Edit"

Here you can change the name and slug of your project.

The Slug is relevant if you want to access the IIIF Image API with the source file name of the image (See Using the IIIF Image API).

Action "Delete"

Warning

This action will delete the whole project including all collections, sequences and images of this project

After clicking on "Delete" you have to confirm the action:

Collection View

This view shows you the collection information (project, parent collection, id, name, links to the presentation API, child collections and sequences) and also the actions "Edit", "Move", "Delete", "Export image details", "Add child collection" and "Add sequence".

When the current collection is the root collection, the actions "Move" and "Delete" are not available.

When there are no images found in the collection tree starting from this collection, the "Export image details" button is not available.

Example of root collection

Example of non root collection

Project

A link to the project information (See Project View).

Parent Collection

A link to the parent collection - only if the current collection is not the root collection (See Collection View)

Id

The UUID of the current collection

Name

The name of the current collection

Presentation API

The buttons will open the URL which delivers the JSON information for the current collection as defined in the IIIF Presentation API v2.1 or v3.

Child collections

Links to child collections of the current collection (See Collection View)

Sequences

Links to the sequences of the current collection (See Sequence View)

Action "Edit"

Here you can change the name of the collection.

Action "Move"

When clicking on this button, you will see a pop-up with a tree view of all the collections in the project (except the current one). To move the current collection, click on one of the displayed ones and it will be moved there as a child.

Action "Delete"

Warning

This action will delete the whole collection including all children,sequences and images of this collection

After clicking on "Delete" you have to confirm the action:

Action "Export image details"

Clicking on "Export image details" will generate a CSV with the image details for all images found inside sequences of this collection and in all sequences of successor collections (going down the whole collection tree from this collection on).

Action "Add child collection"

This action adds a new collection as child to the current collection.

Action "Add sequence"

This action adds a new sequence to the current collection.

Sequence View

This view shows you the sequence information (project, parent collection, id, name, number of images, links to the presentation API and containing images) and also the actions "Edit", "Move", "Delete" and "Export image details".

Project

A link to the project information (See Project View).

Collection

A link to the parent collection (See Collection View).

Id

The UUID of the current sequence

Name

The name of the current sequence

# Images

The number of images in the current sequence

Presentation API

The buttons will open the URL which delivers the JSON information for the current sequence (manifest) as defined in the IIIF Presentation API v2.1 or v3.

Images

Links to the images of the current collection (See Image View).

Action "Edit"

Here you can change the name of the sequence.

Action "Move"

When clicking on this button, you will see a pop-up with a tree view of all the collections in the project. To move the current sequence, click on one of the displayed collections and it will be moved there as a child.

Action "Delete"

Warning

This action will delete the whole sequence including all images of this sequence

After clicking on "Delete" you have to confirm the action:

Action "Export image details"

Clicking on "Export image details" will generate a CSV with the image details for all images inside the current sequence.

Image View

This view shows you the image information (project, parent collection, parent sequence, id, source file name, source file size, generated JPEG sizes, links to the image API) and the image itself.

Project

A link to the project information (See Project View).

Collection

A link to the parent collection of the sequence containing the current image (See Collection View).

Sequence

A link to the sequence containing the current image (See Sequence View)

Id

The UUID of the current image

Source file name

The name of the originally imported file

Source file size

The file size of the originally imported file

Generated JPEG sizes

The file size of the generated high quality JPEG files.

There are four pre-generated files: 100%, 75%, 50%, 25% (resolution)

Image API (info)

The buttons will open the URL which delivers the JSON information for the current image (info) as defined in the IIIF Image API v2.1 or v3.

Full image

The buttons will open the URL which delivers the full image in the highest available resolution as defined in the IIIF Image API v2.1 or v3.

Action "Delete"

Warning

This action will delete the current image and its four pre-generated files from the sequence and storage

After clicking on "Delete" you have to confirm the action:

Tasks

This menu item provides you with the possibility to create an import task and getting an overview over the open, completed and failed tasks for the projects you are entitled for.

Whenever the system needs to perform an action that cannot be executed immediately (synchronously), a task is created for this purpose. A task can contain further sub-tasks and, if necessary, generate new tasks.

The administration interface user can generate explicitly an import task and implicitly image deletion tasks (by deleting a sequence, collection or project which contains one or more images).

Create a new import task

This functionality is used to import image files which you delivered on the share.

Note

See File delivery for more information on how to prepare and deliver your image files.

Select the project for which you want to import images and click on "Next".

In the next step you need to select the path of your folder on the file delivery share. Depending on how you prepared your image files you need to specify a sequence.

If you want to override existing images, check the "Override Images" box - otherwise the system will not import existing images but create a warning for each such image in the corresponding task.

Click "Start" to add a new import task for your import to the Task overview.

Task overview

Here you get an overview of all tasks in the projects for which you are entitled.

By clicking on the corresponding columns, you can change the sorting. By clicking on the filter icon, you get the possibility to filter the tasks according to certain criteria.

By clicking on the linked TaskID you will get to the corresponding Task view.

Task view

This view shows you the tasks information (Id, State, IsRunning, Started, Modified, Path, Logs and Subtasks).

The Task view for an incompleted import task will also provide you with a button to cancel the task.

Id

The Id of the Task in the database.

State

The current state of the task.

Possible states are

  • New (Task was created but not started yet)
  • Started (Task was started)
  • Subtasks (Task is waiting for sub-tasks completion)
  • Successful (Task was finished successful)
  • Interrupted (Task was canceled by user)
  • Failed (Task execution failed)

IsRunning

Indicates if the task is currently running or not.

Started

Date and time when the task was first started.

Modified

Date an time when the task information was last modified.

When the task is in state "Successful", "Interrupted" or "Failed" - this is the date and time when the task finally stopped running.

Path

The path associated with the Task (e.g. the import folder for the import task; the path to the source image file for an image validation or image creation task).

Logs

Here you will find task specific log entries. A log entry can have the following types:

  • (info) Info: Just gives you neutral information of some kind (e.g. task started)

  • (tick) Success: Something in the task was successful (e.g. file validation, image generation)

  • (warning) Warning: Something in the task needs your attention, task itself (and parent task) can still be successful

  • (error) Error: Something in the task went wrong, task itself (and parent task) will be failed

Subtasks

This list behaves exactly as the list described under task overview but contains only sub-tasks of the current task.

Storage

This view shows you the storage usage information per project you are entitled for (Current usage and avg usage per year).

File delivery

Access to the delivery folder

To get access to the delivery folder for your users, please contact itsupport.ub@unibe.ch.

Users need to have an existing Campus Account at the University of Bern. Users need to use their Campus Account credentials to connect to the delivery folder on the Campus Storage share.

Operating System Path to the delivery folder
Windows \\nas-ub.unibe.ch\ub-iiif\delivery
Linux, Mac smb://nas-ub.unibe.ch/ub-iiif/delivery

Prepare a delivery for an import

Warning

Important note about naming of your image files

You can name your image files as you like but the name of an image file needs to be unique within a project. As example you can not have two files named image001.tif within a project.

Import of multiple images to a specific sequence

  • Create the sequence if it does not already exist. (See Collection View).
  • Prepare a folder on your storage which contains all images you want to import to a specific sequence. This folder must not have any subfolders.
  • Use Bagger to create a BagIt compatible folder on your storage.
  • Choose a meaningful name for the BagIt folder, we recommend to use the project slug (See Project view) as prefix (e.g. my-project_first_import_test).
  • Move the folder created with Bagger to the delivery folder
  • Create a new import task for your project, select the transferred folder and don't forget to select the sequence in which you want to import the images (See Create a new import task).

Import of multiple images to multiple sequences

  • Prepare a folder on your storage

  • Create a hierarchy of subfolders containing the names of the desired collections. Create subfolders with the names of the desired sequences and place the images to be imported there - these subfolders must not contain any further subfolders. There is no need to create a folder with the name of the root collection, the previously created folder can be considered as root.
    Example of such a hierarchy:

    ./prepared-folder
    ./Collection 1
        ./Sequence 1
            ./seq1_image001.tif
            ./seq1_image002.tif
            ./seq1_image003.tif
    ./Collection 1
        ./Sub-Collection 1
            ./Sequence 2
                ./seq2_image001.tif
                ./seq2_image002.tif
            ./Sequence 3
                ./seq3_imageA.tif
                ./seq3_imageB.tif
                ./seq3_imageC.tif
                ./seq3_imageD.tif
        ./Sub-Collection 3
            ./Sequence 4
                ./seq4_image.tif
    ./Sequence 5           <= Note: this sequence will be in the root collection
        ./seq5_1.tif
        ./seq5_2.tif
        ./seq5_3.tif

  • Use Bagger to create a BagIt compatible folder on your storage.

  • Choose a meaningful name for the BagIt folder, we recommend to use the project slug (See Project view) as prefix (e.g. my-project_first_import_test).
  • Move the folder created with Bagger to the delivery folder
  • Create a new import task for your project, and select the transferred folder (See Create a new import task).

Info

During the import the system will lookup collections and sequences by folder name. If a collection or sequence is not found the system will create a new one with the folder name.

What is BagIt?

BagIt is a set of hierarchical file system conventions designed to support disk-based storage and network transfer of arbitrary digital content. A \"bag\" consists of a \"payload\" (the arbitrary content) and \"tags\", which are metadata files intended to document the storage and transfer of the bag. A required tag file contains a manifest listing every file in the payload together with its corresponding checksum. The name, BagIt, is inspired by the \"enclose and deposit\" method, sometimes referred to as \"bag it and tag it\".

Source: https://en.wikipedia.org/wiki/BagIt

Use Bagger to create a BagIt compatible folder

See https://github.com/LibraryOfCongress/bagger for downloading and starting the Library of congress Bagger application.

  • Open the Bagger application
  • Click on the "Create Bag in Place" Icon
  • Click on the "..." Icon behind "Select Date"
  • Open the prepared folder (See Prepare a delivery for an import), ensure you are inside the folder. And click on "Open"
  • Click on "OK"
  • The bag is created and you will receive a success message, click on the "OK" button
  • The Bagger window is now updated
  • If you open the prepared folder in the file explorer you will now see, that there is a "data" folder where your prepared files/folder where moved and you will see the text files created by Bagger.
  • Close the Bagger software and move the prepared folder to the file delivery folder (See Access to the delivery folder)
  • After transfer of the prepared folder you can start the import (See Create a new import task)

Known Bagger problems

Negative time

It seems that Bagger won't accept negative file created or modified time stamps.

Depending on your operating system, Bagger won't accept date time stamps which are too old.

E.g. on Linux the time stamps are saved in an integer which represents the seconds gone from 01.01.1970 00:00:00 (UTC). Time stamps before this date/time are represented with a negative integer.

This can happen, when the creation date of the scanned item itself is saved in the creation or modified time stamp of the created file.

In this case you need to update the time stamps of your files.

Special characters in the path to the prepared folder

It seems that Bagger won't be able to open a prepared folder when there are some special characters in the path (e.g. if the path is in a OneDrive folder). In this case move your prepared to your local disk and ensure that there are no special characters in the path. We also recommend that you only use A-Z, a-z, 0-9, - and _ in the name of your prepared folder.

Using the IIIF Image API

Image Request

Info

See the IIIF Image API reference v2.1 or v3.0 for further details on the URI syntax (region, size, rotation, quality and format).

The IIIF Image API URI for requesting an image defines the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}

For the University Library IIIF Server, the {scheme}://{server} part is https://iiif.ub.unibe.ch followed by /image/{version} as {prefix} where version is either v2.1 or v3.0. For the following examples we will use v3.0 as {version} (https://iiif.ub.unibe.ch/image/v3.0/...)

There are two ways on the University Library IIIF Server to call a specific image:

Info

When using the variant with the project slug and image source file name, a HTTP redirect to the first variant (image identifier) will be created. This means for every such request to the image API the browser has to do a second request. This causes a minimal delay (microseconds) on each request and increases the load on the web server. We recommend to use the first variant whenever possible.

Image Information Request

Info

See the IIIF Image API reference v2.1 or v3.0 for further details on the URI syntax.

The IIIF Image API URI for requesting an image defines the following URI Template:

{scheme}://{server}{/prefix}/{identifier}/info.json

For the University Library IIIF Server, the {scheme}://{server} part is https://iiif.ub.unibe.ch followed by /image/{version} as {prefix} where version is either v2.1 or v3.0. For the following examples we will use v3.0 as {version} (https://iiif.ub.unibe.ch/image/v3.0/...)

There are two ways on the University Library IIIF Server to call a specific image information:

Warning

When using the variant with the project slug and image source file name, a HTTP redirect to the first variant (image identifier) will be created. This means for every such request to the image API the browser has to do a second request. This causes a minimal delay (microseconds) on each request and increases the load on the web server. We recommend to use the first variant whenever possible.

Using the IIIF Presentation API

Info

The University Library IIIF Server provides a rudimentary presentation API. At the moment we are extending the functionality of our presentation API to allow metadata enrichment.

The JSON-LD representation of a collection can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/collection/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0).

The {id} is the ID of the collection which can be found in the Collection View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/collection/691e6e0c-afc2-4f17-aee5-d9f88be15865/

The JSON-LD representation of a sequence (also called "Manifest") can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/manifest/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0). The {id} is the ID of the sequence which can be found in the Sequence View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/manifest/78285e64-0b86-4010-99f2-6c14b100432d/

The JSON-LD representation of a canvas can be reached with the following URL:

https://iiif.ub.unibe.ch/presentation/{version}/canvas/{id}/

Where {version} is the IIIF Presentation API to use (currently supported: v2.1 and v3.0).

The {id} is the ID of the image displayed on the canvas which can be found in the Image View or in the CSV export created in the Collection or Sequence View.

Full example: https://iiif.ub.unibe.ch/presentation/v2.1/canvas/e61b22ed-3d94-4322-9633-e4b9a3df1def/

Info

According to the IIIF Presentation API specifications, it is theoretically possible to place multiple images of different sizes on a canvas.

However, the University Library IIIF server always delivers a canvas in the 100% size of the image on which the respective image is placed in the same size.

Zurück zum Seitenanfang