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.
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: Just gives you neutral information of some kind (e.g. task started)
-
Success: Something in the task was successful (e.g. file validation, image generation)
-
Warning: Something in the task needs your attention, task itself (and parent task) can still be successful
-
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:
-
By image identifier
Here the ID of the image is used as identifier to call the IIIF Image API:
Example with image IDe61b22ed-3d94-4322-9633-e4b9a3df1def
:
https://iiif.ub.unibe.ch/image/v3.0/e61b22ed-3d94-4322-9633-e4b9a3df1def/full/max/0/default.jpg
The ID of the image can be found in the Image View or in the CSV export created in the Collection or Sequence View. -
By project slug and image source file name
Here the project slug will be added to the{prefix}
value:
Example with project slugmy-project
:https://iiif.ub.unibe.ch/image/v3.0/my-project/...
As image identifier the image source file name (original file name in import, unique within a project) is used.
Example with project slughaller
and source file namegga_00001_001.tif
:
https://iiif.ub.unibe.ch/image/v3.0/haller/gga_00001_001.tif/full/max/0/default.jpg
The slug of the project can be found on the Project View, the source file name of the image can be found in the Image View. Both information can also be found in the CSV export created in the Collection or Sequence View.
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
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:
- By image identifier
Here the ID of the image is used as identifier to call the IIIF Image API:
Example with image IDe61b22ed-3d94-4322-9633-e4b9a3df1def
:
https://iiif.ub.unibe.ch/image/v3/e61b22ed-3d94-4322-9633-e4b9a3df1def/info.json
The ID of the image can be found in the Image View or in the CSV export created in the Collection or Sequence View. - By project slug and image source file name
Here the project slug will be added to the{prefix}
value:
Example with project slugmy-project
:
https://iiif.ub.unibe.ch/image/v3.0/my-project/...
As image identifier the image source file name (original file name in import, unique within a project) is used.
Example with project slughaller
and source file namegga_00001_001.tif
:
https://iiif.ub.unibe.ch/image/v3/haller/gga_00001_001.tif/info.json
The slug of the project can be found on the Project View, the source file name of the image can be found in the Image View. Both information can also be found in the CSV export created in the Collection or Sequence View.
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.