Reports, in three phases

After attending this month’s ArchivesSpace Hackathon (which was an amazing event, by the way, which deserves its own blog post or two!), I started mucking about with the new reporting features in ArchivesSpace. So far, I’ve been tackling reports in three ways:

  1. Adding new reports to ArchivesSpace that I authored in JasperSoft Studio
  2. Editing prepackaged ArchivesSpace reports with JasperSoft Studio
  3. Adding a print.css stylesheet to ArchivesSpace to emulate those “print screen” reports from Archivists’ Toolkit

Long story short, it was actually a lot easier than I expected to add new reports to ArchivesSpace (tested on versions 1.4.x).  If you can write a new report with a tool like JasperSoft Studio, then you’ll be able to upload it to ArchivesSpace with ease.  That said, I still wonder what other changes might be required to load new reports into ArchivesSpace that are parameterized (and so, require additional user interactions before running), but I hope that those features will be added to new releases of the ArchivesSpace reports module if they aren’t already there.  In any event, those types of reports will be my next steps of exploration.  In the meantime, this post is about what I have up and running right now.

Phase 1

To author and then add a new report to ArchivesSpace, here are the steps that you’ll need to take, if you follow my particular path:

  • Install JasperSoft Studio on the machine that you plan to write your reports, (Note, you do NOT have to register for an account.  When the download modal window pops up, just click the “No thanks” link in the bottom right-hand corner!)
  • Use the “Create Database Adapter” wizard to connect JasperSoft Studio to your ArchivesSpace database.  There are good directions on how to do this in the ArchivesSpace user manual, but in case you don’t have access to that manual, you just need to follow a few simple steps, which should be pretty familiar if you’ve already hooked up a tool like MySQL Workbench to ArchivesSpace:
  • Choose the “Database JDBC Connection” option
  • Select “com.mysql.jdbc.Driver” as your JDBC driver
  • Enter the server name and database name in the JDBC URL field.  For instance, if you’re running the ASpace application on your local machine for testing purposes, your JDBC URL might look like this:  “jdbc:mysql://localhost/archivesspace_database_name”
  • Enter your MySQL username and password that you used to create the ArchivesSpace database (if you’re connecting to a production database, you should probably create a read-only MySQL account for this instead).  If you’re following the directions exactly as they’re listed in the ArchivesSpace Github Installtion readme, though, then your MySQL username and password will be “as” & “as123”.
  • Finally, you just need to provide JasperSoft with the path to the MySQL Connector Java file in the “Driver Classpath” tab.  Again, if you’re running ArchivesSpace on your local machine, while also using the MySQL database as the backend, then you already put this connector file in your “archivesspace/lib” directory.  So, your path might look something like this on a Windows machine:  “C:\archivesspace\lib\mysql-connector-java-5.1.34-bin.jar”.  If you’re not running ASpace on your local machine, and you haven’t already downloaded this file with a program like MySQL Workbench, then you can just download a standalone version here: (again, no need to create an account just to download the file).
  • Once you’ve filled in all of that data, click the Test button.  As long as you get the success message, it’s time to write a report…. or to learn how to write reports.
  • Next,  watch a video like this one:  This video covers many of the previous steps, as well as walking you through writing a simple report.
  • Happy with your Jasper report?  Then it’s time to upload it to ArchivesSpace.  As it turns out, you don’t need to do anything that special to enable new reports (despite what the current user documentation says); you just need to load the JRXML files in your reports directory in a very specific way, add a YML file, and then re-start ArchivesSpace so that the reports can be compiled.  Here’s what I did:
  • Within the archivesspace/reports directory, I created a new directory that I named “Local”.  I did this as a reminder that I will need to migrate this directory when upgrading to a new release of ArchivesSpace.  Originally, I was hoping that I could just load my custom reports in the plugins directory, but I could never get them to run properly that way, and just putting them in the reports directory turned out to be a lot easier!
  • Within the “reports/Local” directory, I added a new directory for each of my custom reports.  These directories MUST be named with the same filename as the JRXML files that you’ll be including in each.  Additionally, each directory name must end with the word “Report”.  Any subreports can be named whatever you want, since those files will be referenced by the primary report.  So, here’s  what the new filepath looks like at this point:  reports/Local/LocalTestReport/LocalTestReport.jrxml
  • Next I added one more file to the “LocalTestReport” directory.  Like all of the pre-packaged reports, you’ll need a “report_config.yml” file for your custom reports.  Here are the contents of the YML file for my test report:

report_type: jdbc
uri_suffix: local_test
description: “My first report.”

  • The only real trick here is making sure that the uri_suffix value excludes the word Report and includes underscores in between the previously camel-cased words.  In other words, since your directory is named “LocalTestReport”, you have to set your uri_suffix = “local_test”.  This same convention is followed with all of the pre-packeged reports.  For instance, the “DigitalObjectListReport” directory has a uri_suffix = “digital_object_list”.
  • Still with me?  If so, here’s what your directory looks like:reports-part1
  • Now, just check your config.rb file to make sure that Jasper reports are enabled and that they’re set to compile.  Here’s what that should look like: Screen Shot 2015-11-25 at 5.03.34 PM
  • Even though the documentation says to set compile to false if you’re using Java 8, that didn’t work for me (at least not when running ArchivesSpace on a Mac with Java 8 on a local test instance).  I kept both options set to true and everything started fine.  Your mileage may vary at this point, but it shouldn’t be too hard to debug what’s going on here if your reports don’t load.
  • Now, restart ArchivesSpace.  If everything is okay, your report will be compiled during startup, at which point you’ll find a “.jasper” file in that same directory: reports-part2
  • If you happen to use any jar files for your reports that aren’t included with ArchivesSpace, like I did, then you’ll need to add those to your archivesspace/lib directory (otherwise, ArchivesSpace won’t even start up, since it won’t be able to compile the reports).  If you use charts in your reports, for example, then you’ll need to add two more jar files to archivesspace/lib:
    • jcommon-1.0.23.jar
    • jfreechart-1.0.19.jar

Tip: you can find all of the jar files that are used in JasperSoft Studio by downloading the JasperReports Library here,

  • With ArchivesSpace back up, head over to the reports page, and you should find your “Local” report(s) exactly where they line up in the “reports” directory when sorted alphabetically.  Here’s mine, which falls right after the prepackaged RepositoryProfileReport (since that report is in the General subdirectory, and the Local subdirectory comes right after that):Screen Shot 2015-11-25 at 5.15.02 PM
  • Finally, here’s what the summary page of my new report looks like after running it through ArchivesSpace for the first time (pardon the fake data): Screen Shot 2015-11-25 at 5.14.30 PM

That’s it!

Phase 2

Now, to modify an existing ASpace report, here’s what I did:

  • I copied the ASpace JRXML file from ArchivesSpace and moved it to my JasperSoft Studio workspace, MyReports.
  • I then tested and made sure that I could run the report.  At this point, you’ll need to make sure that you connect the report to the Data Adapter that you previously added (by default, the data adapter will be set to “One Empty Record”, so you won’t get any data if you run the report without changing the data adapter first).
  • When you run any of the pre-packaged ASpace reports, you’re going to get prompted to enter a “basePath” value.  Due to the way this parameter is used in the reports, it’s easiest to just supply this value:  “../MyReports”.  If you do that, you won’t need to edit that part of the report at all, which you won’t want to do anyway since you’ll eventually be loading this report back into AchivesSpace.  Here’s what everything should look like before you push the green arrow again to pass in that parameter (note, too, that I’ve already changed my data adapter in this example, which you’ll see in the upper left-hand side of the screenshot): Screen Shot 2015-11-25 at 4.42.28 PM
  • Here’s an important trick: if you’re using one of the reports that pulls in any data from the Notes MySQL table in ArchivesSpace, then you’ll need to tell JasperSoft Studio about the “areports-aspace.jar” file, which was added to ArchivesSpace to partially parse the JSON notes that are stored in the database (I say partially since this script currently doesn’t do anything with mixed-content elements, like “title” and “persname”, and so, you’ll still see that EAD encoding in your reports right now).  Anyhow, to add this file, here’s what you do in JasperSoft Studio:  Project (top menu) –> Properties (last option) –> Java Build Path –> Libraries (tab) –> add external JAR file –> and then point to that jar file.  If you have ASpace installed on a Windows machine, then the file path might look like this: C:\archivesspace\lib\areports-aspace.jar  For more details, see here:
  • That’s about it.  You should be able to tweak the files and test them from here on out.  Once you’re ready to load them back into ASpace, all that you need to do is copy over the same files back in the apsace/reports directories and then restart ArchiveSpace so that it can recompile the JRXML files into the binary Jasper files.

Phase 3

Finally, here’s how I went about adding a “print.css” stylesheet to the staff side of ArchivesSpace so that our staff can use their web browser to print pages (or even make PDFs of what’s on the screen) without having to include navigation menus, buttons, and any other data that generally clutters things up.

  • I used the “local” plugin architecture. This is a great plugin that comes packaged with ArchivesSpace, and I believe that it’s turned on by default in the config.rb file, which means that you don’t have to do anything else to activate the plugin.
  • I added one new directory and two new files to the local/frontend plugin directory.  The new directory, assets, is where I placed a print.css file.  The local/frontend/assets/print.css file is the CSS file that includes all of the directives you want the browser to use when someone attempts to print a page in the staff interface.  The second new file is an embedded ruby template file that simply includes a bit of coding that makes sure that the print.css file will be added to all of the HTML headers within the staff interface.  That file should be located here:  local/frontend/views/layout_head.html.erb
  • Here’s the entirety of my “layout_head.html.erb” file:

<%= stylesheet_link_tag “#{base_url}/assets/print.css”, media: :print %>

  • The “media: :print” part just makes sure that the HTML style tag will be loaded by ArchivesSpace with media=”print”, which will ensure that this new CSS file will be used by the browser if a user attempts to print any page in the staff interface.
  • Once you restart ArchivesSpace with this plugin installed, you can change and update the print.css file as often as you’d like without having to restart ArchiveSpace to see the changes reflected in your new print.css stylesheet.

Please let me know if anyone has any questions, or runs into any problems when trying to follow any of these directions.  I’ve run through them a few times now on both Windows and Mac, and everything seems to work pretty smoothly, so I’m thankful for that…  so far! We’ll so how things go when I enter the 4th phase to discover what’s required to add parameterized reports into the staff interface.

All that said, before too much work is put into Jasper by the ASpace team, I think that the biggest impact that the ArchivesSpace membership could have with its users would be for the core code to be updated so that its staff-side search result screens are just as configurable as the browse screens.  Once that’s addressed, it would also be really great if users could use a technique like the print.css style sheet in order to print as many paginated results in a single go.  Right now, our current default is 10 search results on a single page, and even though we could update that number in the config.rb file, there will always be times when a user wants to see more data offline than what’s displayed on a single result screen, if paginated.  In those cases, it would be ideal if they’d have the option to create a simple PDF export (like what you get with a print.css file) as well as the option to create a simple CSV dump of the data that displays on screen.  Something like you see in this example,, but a little different so that it would also include the search result column headers (and hopefully it could be done server side, too).  Now that would make me really thankful!

Leave a Reply

Your email address will not be published. Required fields are marked *