Skip to Main Content
It looks like you're using Internet Explorer 11 or older. This website works best with modern browsers such as the latest versions of Chrome, Firefox, Safari, and Edge. If you continue with this browser, you may see unexpected results.

FL-Islandora Guide

A guide for FL-Islandora users.

Introduction

There are three ways to suppress a content object from public view:

  1. Use an Object Policy on Object Viewing
  2. Add the object to a collection with an Object Policy
  3. Place an IP Embargo on the object

Object Policy

Object Policy (XACML Restrictions)

Islandora Object Policies that restrict access to collection and/or content objects are implemented via XACML policies (written in eXtensible Access Control Markup Language). An Object Policy (XACML Policy Stream datastream) restricting Object Viewing will allow only users with roles specified in the policy to view the object. For example, viewing could be restricted so that only users with staff roles can see the object. Unauthorized viewers will not see the object in browses or in search results. Also, an unauthorized user trying to access the object directly by PID will get the message “You are not authorized to access this page.”

The roles defined in the system are:

  • anonymous user

  • submitter

  • editor

  • supervisor

  • collection manager

  • site administrator

  • administrator (this role is reserved for FLVC staff)

  • authenticated user

The role “authenticated user” automatically includes anyone logged on to the system, all but anonymous users.

Attaching Object Policies to a Content Object

An Object Policy (XACML Policy Stream datastream) can be attached to an individual content object. Navigate to the object and click the "Manage" tab, then click “Object Policy.” Three permission categories will appear:

  • Enable XACML Restrictions on Object Management
  • Enable XACML Restrictions on Object Viewing
  • Enable XACML Restrictions on DSIDs and MIME types

Click the checkbox in front of “Enable XACML Restrictions on Object Viewing”. This will expand to a form:

NOTE:  It is possible to select both roles and individuals.

Set the roles which will be allowed to view the object by clicking on one or more role(s) listed under “Allowed Roles”. To select multiple roles, hold CTRL when you click. To a select a range of roles hold SHIFT and click the first and last roles in the range. NOTE: selecting “authenticated user” will automatically select all the roles requiring authentication (administrator on down). With planned feature enhancements, patrons will be able to log on to their own patron accounts for “mySpace” type of functions. Therefore, it is not a good idea to select “authenticated user” if the intent is to restrict viewing only to authorized staff. Permission to view can also be granted to individual users, rather than all users with a certain role. Select the individual(s) with permission the same way you would select roles. After you select the roles and/or users to be allowed to view the object, click the “Set Permissions” button.

Content Specifications:

  • Object Viewing policies set on Book objects at the title level will be inherited by the pages in the book. However, if pages are added via the Zip File importer to an existing Book object with an Object Viewing policy, those pages will not inherit the policy.
  • Object Viewing policies set on Newspaper issues will be inherited by the pages in the issue, with the same caveat about the Zip File importer as for books. However, an Object Viewing policy set at the Newspaper title level will not be inherited by issues or pages.
Attaching Object Policies to Collections

To attach an Object Policy on Object Viewing to a collection, navigate to the collection and click the "Manage" tab, then click “Object Policy”. Three permission categories will appear:

  • Enable XACML Restrictions on Object Management
  • Enable XACML Restrictions on Object Viewing
  • Enable XACML Restrictions on DSIDs and MIME types

Click the checkbox in front of “Enable XACML Restrictions on Object Viewing”. This will expand to a form:

Select the role(s) and/or user(s) with permission to view the collection object in the same way you would do so for a content object. The collection form gives an additional option that must be selected from a pull-down menu: “What items would you like to apply this policy to?” The policy choices are:

  • New children of this collection:  This will hide the collection object itself and all content objects added to the collection after the policy is set if the objects are added by online ingest or offline ingest.

  • All children of this collection (existing and new):  This will hide the collection object itself and all content objects in the collection, both current and new.

  • *Recommended Setting* All children of this collection and collections within this collection (existing and new):  This will hide the collection object itself, all sub-collections, and all content objects in the collection or sub-collections, for all current objects and any new objects. The entire collection hierarchy is suppressed from the collection with the policy to the lowest level and it is assumed that the user's intention when placing restrictions on viewing of a collection is to allow only logged-in staff to view that collection and its child objects.

Select the appropriate choice and click “Set Permissions”.

NOTE: We recommend that not to add restrictions on more than 10 objects at a time. Doing so will result in an error and restrictions will not be lifted or applied to the objects.

NOTE: when a book or newspaper issue that is added to a collection with an Object Viewing policy, that policy will be applied to the book or newspaper issue and all its pages.

Checking an Object Viewing Policy

After applying an Object Viewing policy to a collection or content object, it's always wise to check the "Manage"->"Object Policy" setting to confirm that an object viewing policy has been correctly set and that a "XACML Policy Stream" datastream has been added to the object.

Removing an Object Viewing policy

To remove an object viewing policy from a content object, navigate to the object, Click the "Manage" tab, then click “Object Policy”. Uncheck the box and click “Set Permissions”. The policy will be removed.

To remove an object viewing policy from a collection object, navigate to the collection and follow the same steps. If you want the policy removed from existing members of the collection, you must select “All children of this collection (existing and new)” or “All children of this collection and collections within this collection (existing and new)” as appropriate. If you take the default option, “New children of this collection”, the policy will be removed from new additions to the collection going forward, but current members of the collection will remain suppressed to unauthorized viewers.

NOTE: We recommend that not to lift restrictions on more than 10 objects at a time. Doing so will result in an error and restrictions will not be lifted or applied to the objects.

Collection Access

There is only one recommended way to suppress a collection object from public view: attach an Object Policy to the collection. FL Library Services recommends using the policy option all children of this collection and collections within this collection (existing and new) when suppressing a collection object, so that the child collections and content objects are not retrievable by the public and will not be contributed to the Discovery Tool (Mango).

IP Embargo

An embargo will restrict viewing of an object to users within a defined set of IP address ranges. The thumbnail of the object is visible in both search results and browses, but if the user is coming from an address outside the allowed address ranges, the thumbnail will indicate that the object is restricted. IP embargoes can be placed on collections or content objects, however, an IP embargo on a collection object will not automatically place embargoes on the content objects within the collection and these content objects will be retrievable in search results. To display an embargo message on an entire collection, and to also ensure that its content objects are not retrievable in search results, IP embargoes should be placed on the collection and on all of its content objects.  NOTE: Lower levels in an object hierarchy do not inherit an embargo placed at a higher level. That is, an embargo of a Book at the title level does not embargo each page of the book; the pages can be retrieved by full-text searches and viewed. Similarly, an embargo of a newspaper at the title level does not embargo issues or pages, and an embargo placed at the issue-level does not embargo pages.

The Embargo function is useful for limiting access to campus use only or other IP-definable populations. Embargoes work by prohibiting access to all users EXCEPT those coming from a particular set of IP addresses. These sets must have been previously created by a site administrator. They may include an empty set including no IP addresses at all, which prohibits all access to the object.

Embargo Setup

The general procedure to embargo objects is to first set up an embargo, then apply that embargo to items. Site administrators can set up IP embargo lists and parameters that will affect IP embargoes site-wide.

Embargo Lists

Named lists of IP ranges can be created and changed through the Embargo Lists interface. An embargo list consists of the set of IP addresses that will be allowed to view an object when an embargo is set using that list. This is to say, the IPs you list are INCLUDED not EXCLUDED addresses.

Create a new IP list for embargos

1) Look along the top of your screen just under your institution's banner, and look for the menu bar with an option for “Embargoed Objects”. Click that link. The default tab will be Embargo Lists.

2) To create a new list, click to the "Network address lists" tab, then click the “Add network list” link at the bottom of the screen. A form will appear prompting you to enter the name of the list.

3) The list name you create should be descriptive, like “FSU campus” for a list including all IP addresses on the FSU campus, or “FSU Law building” for a list including IP addresses for a single building.

4) Click “Create list”. The new list will appear on the Embargo Lists screen.

5) Populate the list following the instructions in the “Edit an existing list” section below.

Edit an existing list

1) From the Embargo Lists screen, click on the name of the list you want to modify. You will get a screen showing existing IP ranges in the list (if any).

2) To add a new range, click “Add range” at the bottom of the screen. A form will prompt you for the low end and high end of the range.

3) Enter addresses in IP format (nnn.nnn.nnn.nnn), e.g.: 128.186.0.0

4) If it is a single IP address, enter the same IP address for the Low end and the High end.

5) Click “Create range”.

Delete or change an IP range
To delete an IP range
  1. Go to the IP range list
  2. Check the range to delete
  3. Click “Delete ranges”
To change an IP range
  1. Go to the IP range list
  2. Delete the existing range
  3. Add a new range

To add an embargo to an object, navigate to the object and click the "IP Embargo" tab. (The tab only displays to staff authorized to manage embargoes.) You will get the Set Embargo form:

IP address range list: Select the named range of IP addresses that should be allowed access to this object.

Expiry: Set this to the date the embargo should automatically expire. If the embargo should never expire automatically, click the checkbox “Never expire” The Expiry date displayed will not change from the default (today’s date) but the actual embargo will be set to indefinite.

Click “Set Embargo”.

NOTE: When an embargo is placed successfully, the system does not respond with a message, it simply redisplays the embargo screen.

If you click “Set Embargo” without supplying the name of an IP address range, a long error message is produced. This can be ignored -- go back to the embargo screen and supply the IP range name.

Adding an embargo to an object using Offline ingest

Offline ingest requires a manifest file see Offline Ingest under Content for more info about manifest. You would add the following line to the manifest file after the <owningInstitution></owningInstitution>line:
<embargo rangeName="Name of IP Embargo" endDate="yyyy-mm-dd"></embargo>

For example: <embargo rangeName="FSU Campus" endDate="2020-06-27"></embargo>

Changing or Removing an embargo

You can use the same form to change a previously set IP range or expiry date. To remove an embargo completely, select the blank entry from “IP Address Range List”.

Manage Embargo Settings

The site administrator can establish settings that control embargo behavior site-wide. From the menu bar near the top of the screen, select “Embargoed Objects”. Click the tab labeled “Islandora IP Embargo Settings”.

Object embargoed redirect: If this field is left blank, when a user who is not authorized to view an embargoed object (i.e., is not within the named IP range of the embargo) clicks the object thumbnail or icon, that user sees an Islandora screen with the message “You are not authorized to access this page”.  If a valid URL is provided in the field, the user will be redirected to the page at that URL. For example, a library could create a customized page of information about IP embargoed objects on its own website and redirect the user to it.  NOTE: only public/anonymous users will see the redirect; logged-in users will not be redirected to this URL.

Days before embargo alert: If this field is blank, staff will not be alerted before expired embargoes are removed automatically by the system. If a number n is entered, an email will be sent to a designated email address n days before the embargo is removed from any given object. (Note that if 100 objects expire on the same day, 100 emails will be sent.) The email contains the title and PID of the object and a URL to the object. See example email, as viewed in Outlook, below.

Setting an Email to Receive Embargo Alerts

To configure the email address to which the email notification should be sent:

1. Log in as admin to the Islandora site.

2. Click "Configuration" along the top of the page.

3. Look under "Workflow" and click "Rules".

4. Under "Active Rules" you can see rules that already exist and that you can "edit". Click to "edit" an existing rule, or if you don't already have one, click to "+ Add new rule". Feel free to write help@flvc.org to ask for help, and FLVC can set up an embargo for you using the IP range you provide.

New Embargo Functionality: Islandora Scholar Embargo

Note: FLVC has not yet looked at how to configure this. There are settings FLVC can get to, which librarians can't and those include allowing Islandora Scholar Embargo to be used with such and such a content model, and that kind of thing. You can get to Islandora Scholar Embargo on your test site, but assume that it's not fully configured. If you look at it, and want it to work differently, definitely make the ask.

Note: Since Islandora Scholar Embargo does not yet have a cannonical configuration, this page has background info rather than instructions.

  • Islandora Scholar Embargos.
  • Embargo by date range; not IP.
  • Can embargo at the datastream level.
  • Different from IP Embargo, which has already been on all Florida Islandora sites for years.

 

undefined

XACML Settings to Show Scholars, but Hide Collection Browse of Scholars

A XACML policy on a collection will automatically apply to all new items loaded into that collection.

In showing scholars, you want to (1) allow members of the public to see the View All Scholars view available at site_root.digital.flvc.org/browse_scholars and (2) when looking at an individual scholar's profile not see a breadcrumb to a collection holding the scholar.

To get this working: First, XACML must be lifted from all scholars. So, at the collection level from each collection holding scholars, lift XACML and do a shallow traversal, so that XACML is lifted from any scholars. This allows members of the public to see the View All Scholars views, and to look at individual scholar profiles. Second, hide the collection. Apply XACML to the collection that the scholars are in, and apply for new children only.

Those two steps must be repeated anytime you create new scholars on the site. Editing or migrating scholars won't cause display issues and doesn't require repeating those steps