ArchivesSpace Public User Interface Technical Integration

IT projects aren’t about IT

I like to say that projects such as upgrading servers and rolling out new software are not actually IT projects.  They’re really, for lack of a better phrase, human projects.  They’re about analyzing business needs, altering and optimizing workflows, and making work more enjoyable and effective for everyone who uses the product or service.

The IT side of a project, while it demands precise and strict planning, is just a part of the whole show.  It’s the special effects.  It wows the crowd.  It requires painstaking attention to detail, many months of agonizing work, and at times an enormous budget.  But without excellent writing, acting, and cinematography around it, the movie is nothing but a big digital T-Rex stomping through a city surrounded by exploding cars and time-travelling liquid metal robot men.

So, with your permission, I’d like to tell you a little bit about those special effects.  Welcome to The ArchivesSpace Public User Interface Technical Integration Saga.

The principal concern of the Technical Integration group is that the physical, user-facing transition from YFAD to the ArchivesSpace PUI is a smooth one.  This requires notifying our patrons that the change is coming, redirecting requests for individual finding aids to the PUI instead of YFAD, transitioning YFAD touch-points to the PUI, and giving the PUI the YUL look-and-feel.

Notifying patrons

It is critical to let our patrons and stakeholders know that the finding aid tool on our site is changing.  Springing changes on patrons is a sure-fire way to welcome pitchfork-wielding mobs, earn one-star Yelp reviews, and eventually be escorted from the building.  None of these things is particularly good.

On the day of the soft launch, notice will be posted on the YUL home page announcing the arrival of the PUI and the sunsetting of YFAD.  The notice will include a link to try out the new PUI and information on when YFAD will no longer be available.

On the day of the official cutover, notice will be posted to the YUL home page that YFAD is no longer available.

Individual libraries will have many options on how to handle their own landing pages (such as during the soft launch and after the official cutover.  These options are:

  • Whether they’d like to have an ArchivesSpace PUI search box on their landing page during the soft launch, and which existing search box should be replaced by it;
  • Whether they’d like the same “ArchivesSpace PUI is coming” notice as the YUL home page posted on their landing page; and
  • Whether they’d like the same “YFAD is no longer available” notice as the YUL home page posted on their landing page, and when it should come down.

The ArchivesSpace PUI search box would replace one of the landing page’s existing search boxes in the area highlighted below.


The “ArchivesSpace PUI is coming” messages can can be displayed as green “info” type of message or red “important notice” type.  Below are examples of  the two.

The text of the messages will be determined by the PUI Branding and Marketing Workgroup.

There is a web form available for individual libraries to easily (well, I hope easily) choose from the above options.

Redirecting requests for individual finding aids

The trickiest part of the PUI rollout is ensuring that requests for individual finding aids are redirected to their PUI equivalent.  When a patron requests the YFAD finding aid for the Harvey Williams Cushing Papers in the Yale University Library, they should be brought to the ArchivesSpace PUI finding aid for the Harvey Williams Cushing Papers in the Yale University Library.

Therefore, we need to create redirects that turn a request for a YFAD finding aid into one for its PUI finding aid on an individual basis.  Redirecting individual finding aids is a very good thing, as it ensures that all existing finding aid links continue to work.  More, search results in Google and other search engines (does anyone even use Bing?) will also continue to work.  Even better:  The redirects are done in such a way as to cause search engines to update their indexes with the PUI URL.  Epic win!

The brow crinkling part of executing the redirects is that the ArchivesSpace PUI URLs are significantly different from the YFAD ones.  An example of a simple redirect would be going from


In the above case, all that is needed is “take everything after the old server name (the part in bold) and append it to the new server name.”  Coding this is simple.  More simple, probably, than just writing it in English.

The YFAD-to-PUI URL changes, on the other hand, are complex.  Example:

must be changed to


It’s apparent that what comes after the server name in the first example is not the same as what comes after the server name in the second.  What’s probably not apparent is that what makes the first URL unique is not anything like the second.  This eliminates the possibility of making wholesale programmatic changes such as “take everything after the server name and append it to the new.”

The solution is to take each individual YFAD URL and redirect them to the new PUI URL.  Unlike our first example, coding the solution is considerably more difficult than writing it in English.  The existing YFAD URL must be extracted for each finding aid, and the new PUI URL must be matched up to each finding aid.  This will need to be done for more than 10,000 finding aids.

Again, yikes.

By far, the toughest bit of this is to actually get the list of old URLs to new URLs.  Thankfully, Mark Custer did just that and delivered the list.  I honestly have no idea how he did it.  I owe him many beers.

Once this list was compiled, it was not hard to process it so the unique part of the YFAD URL redirected to the new PUI URL.  It was a little hairy, sure, but the process was straight-forward enough to be documented and tucked away should it ever be needed again.  We now have a complete configuration file that will redirect the old to the new.  Rockin’.

Here’s where the spanner gets tossed into the works:  The YFAD server is itself going to be decommissioned at some point in the future when YUL has declared the PUI a success.  Installing the redirect rules into the YFAD server won’t do the job.  When the server is no more, no one will be home to shuttle the YFAD requests off to their shiny new PUI home.  Nuts!

What now?

With a little digital slight-of-hand, we can make this operation work.  We take an existing server that we know will be around for the foreseeable future, and install the redirect configuration file on it.  This server will now happily escort YFAD URLs to their PUI equivalent.  On the day of the official cutover, we just need to configure the network to think that the YFAD server is this new interloper (which, incidentally, is named Sapphire after my lovely and tech-savvy kitty) .  Once that’s done, hey presto! the existing YFAD URLs, duped by the network into going to Sapphie, will redirect to the ArchivesSpace PUI!  Yaaaaaaay!

Sadly, due to the fact that search URLs are built on-the-fly and completely dependent upon what the patron entered into the search box, it will not be possible to redirect searches.  This means that old search boxes and saved (“canned”) searches will not be redirected to the PUI with the results displayed as desired.  Instead, they will be brought to the PUI search page where they can re-perform the search.

Transitioning YFAD touch-points to the ArchivesSpace PUI

YFAD has a significant presence in YUL’s web environment.  The website, LibGuides, and digital exhibitions all interoperate with YFAD to some degree.  Making sure that these touch-points transition from YFAD to the PUI is going to be an important part of the official cutover.

Special care will need to be given to the touch-points that include search boxes.  As mentioned above, the one thing that cannot be redirected from YFAD to the PUI is a search string.  If a user attempts to use a search box that searches YFAD, they will be redirected to the PUI search page rather than their search results.

Search box widgets in the the * web space will be updated for the official cutover.  We have worked with stakeholders to notify us about any YFAD presence outside of the web ecosystem, where we can contact their web administrators and ask them to update links.

The ArchivesSpace PUI will be rolled out in a soft launch.  This means that both YFAD and the PUI will be available simultaneously to patrons and staff for four to six weeks.  When the PUI is in soft launch, it will not be a beta release.  It will be the real deal.  While we have prepared for issues and errors as much as possible, all staff are encouraged to use and review the PUI to help us find any integration points that may have slipped through.

Giving the PUI the YUL look-and-feel

To provide a professional and cohesive experience for visitors, a web environment should maintain consistent interface elements and visual cues.  Pulling this off in the YUL web ecosystem is a challenge as we use many back-end systems to deliver our web content:  The Drupal site, FindIt, Quicksearch, Orbis, YFAD/PUI, LibGuides, LibCal, Ask Yale, CampusPress, and Omeka.  I’m probably forgetting a few.

It’s important that we integrate the PUI look-and-feel into the YUL website’s as much as possible.  The Technical Integration group will bring the YUL identity to the PUI by carrying over the YUL color scheme and general branding.  The Technical Integration group will also develop documentation and suggestions on what else can be done to make the PUI experience integrate more with the YUL website’s.  Having a consistent and holistic web ecosystem goes beyond colors and fonts.  Having consistent location, purpose, and actions of interface widgets, a clearly understood objective of each application or component, and seamless transitions from one touchpoint to another are the ultimate goals.

It’s not about us

At the end of the day, we are providing a tool that must make it easier for our patrons to discover special collections material while streamlining and improving the workflow of Library staff.  The ArchivesSpace PUI must work for them.  To that end, we will be providing a feedback mechanism in the PUI that will collect the thoughts of staff and patrons throughout the soft launch period.  The feedback will provide invaluable insight regarding which parts of the tool are working and which parts could be improved.


I hope this provides a behind-the-scenes look at the special effects of the ArchivesSpace Public User Interface rollout.  It’s a complex and difficult part of an even more complex and more difficult whole.  It doesn’t make the movie into a great movie on its own.  Special effects have its own Academy Award, but ask yourself this:  Was Total Recall really the best film of 1990 just because it won the Oscar for best special effects?