Tech Blog

Alma Analytics Data in a Google Chart

Alma Analytics is a great source of information that can help your institution get even more out of Alma. You can build custom reports and dashboards, and expose the information as a widget to appear on the Alma home page. Alma Analytics comes with impressive data visualizations which present the data in a compelling format.

All of this is great for library staff members who use Alma, but all of that information can be useful elsewhere as well. How can I expose data from Alma Analytics in my library portal or university website?

For this recipe, we’ll use the Analytics API and Google Charts to present report data on an external website. Google Charts is an easy-to-use but powerful charting implementation which displays live data in any HTML5 compliant browser. The Alma Analytics API returns the data in XML format¬†for any report defined in Analytics. This implementation uses plain HTML and JavaScript. (Warning: the methodology used in this example exposes your API key to third parties. See below for strategies to avoid this risk).

I made extensive use of this helpful blog post when implementing the API call.

The Report

I’m using an out-of-the-box report which comes with Alma in the “Shared Folder” of Alma Analytics. The report name is “General Circulation Statistics.” It shows loans, returns, renewals, etc. broken down by library.

I then created an application in the Developer Network dashboard and assigned permissions to the Analytics API. The URL for my API call is:

/almaws/v1/analytics/reports?path=%2Fshared%2FAlma%2FFulfillment%2FReports%2FGeneral%20Circulation%20Statistics&apikey=[[APIKEY]]

And it returns XML in the following format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<report>
<QueryResult>
  <ResumptionToken>76CF09CB251CB5F48BF82724FC9276E3D4C644702859E563F8A2B1EDAEDB7B5FCFDD4DACA9043A2A17AEDB2B963E08FF</ResumptionToken>
  <IsFinished>true</IsFinished>
  <ResultXml>
    <rowset:rowset xmlns:rowset="urn:schemas-microsoft-com:xml-analysis:rowset" xmlns="urn:schemas-microsoft-com:xml-analysis:rowset">
      ...
      <Row>
        <Column0>0</Column0>
        <Column1>Evergreen State</Column1>
        <Column2>0</Column2>
        <Column3>0</Column3>
        <Column4>0</Column4>
        <Column5>0</Column5>
        <Column6>2</Column6>
      </Row>
    </rowset:rowset>
  </ResultXml>
</QueryResult>
</report>

Google Chart

We now have to connect the report data to a Google Chart display. I chose to show a pie chart which breaks down loans by library. Google Charts work with a structure called DataTable. In order to present the data to Google Charts, we want to do the following:

  1. Retrieve the XML from the Analytics API
  2. Add a header row to the DataTable
  3. Loop through the data and add a row to the DataTable for each library
  4. Set some options and ask Google Charts to display the chart

The relevant section of JavaScript code is below (full code is available here):

xmlhttp=new XMLHttpRequest();
xmlhttp.open("GET","https://api-na.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FAlma%2FFulfillment%2FReports%2FGeneral%20Circulation%20Statistics&apikey=[[APIKEY]]",false);
xmlhttp.send();
xmlDoc=xmlhttp.responseXML;
var rows = xmlDoc.getElementsByTagName("Row");
var data = new google.visualization.DataTable();
data.addColumn('string', 'Library');
data.addColumn('number', 'Loans');
for (var i = 0; i < rows.length; i++) {
    data.addRow([
    rows[i].getElementsByTagName("Column1")[0].childNodes[0].nodeValue,
    parseInt(rows[i].getElementsByTagName("Column6")[0].childNodes[0].nodeValue)
    ]);
}

After the JavaScript executes the chart is displayed.

A Word About CORS

In this solution, we’re calling the Alma API from a web page hosted on another domain. Usually, such cross domain requests are not allowed for security reasons. In order to allow cross domain requests, a web server can implement the CORS (cross-origin resource sharing) protocol. In this protocol, the web server returns headers which describe the domains which are allowed to call the resource and the supported actions (GET, POST, etc.)

At this time, Alma supports CORS for GET requests on the Analytics API only. This support allows us to call the API directly from our web page.

It’s important to note that using this methodology exposes the API key to everyone. In this example, we have defined a separate API key with rights only on the Analytics API. However, anyone can use that API key to make other Analytics API requests, and that might expose data contained in this or other analytics reports to third parties. To avoid that risk, we recommend that you create a simple server-side proxy on the same domain to retrieve the data from Alma and return it to the web page. The CORS and server-side-proxy methods are both described in the diagram below.

The full code is available in this Github Gist. You can also view an example from Yoel Kortick in this Gist. Additional material is available in the Ex Libris Knowledge Center.

 

2 Replies to “Alma Analytics Data in a Google Chart”

Leave a Reply