Dumping data out of Alma using PERL and the Alma Analytics API ELUNA Conference 2017 Dumping data out of Alma using PERL and the Alma Analytics API Margaret Briand Wolfe Systems Librarian

Help on Ex Libris Developer Network This is the place to start for using Alma APIs: https://developers.exlibrisgroup.com/alma/apis Create a login Define an application Get an API key Tips and tricks on how to use the Analytics API: https://developers.exlibrisgroup.com/blog/Working-with-Analytics-REST-APIs

Call Format The Analytics API was SOAP (Simple Object Access Protocol) when it was first released. It is now REST (Representational State Transfer) and uses the HTTP protocol. Call base will always begin with: /almaws/v1/analytics/reports Base example from PERL: $rpt_base = "https://api-na.hosted.exlibrisgroup.com/almaws/v1/analytics/reports";

Required Parameters Only one Parameter is Required: Path to the report you want to run from the API. The path is a URL-encoded full path to the report in the OBI catalog, the simplest way to get this is to open your report in Analytics and run it. The path will appear in the URL. To avoid access issues make sure your report is stored in the Shared Folder and not in your personal ‘My Folders’ area.

Path Example

Optional Parameters: limit limit – the default number of rows returned from the API is 25. If you want to increase the number of rows returned set the limit parameter. Note: the OBI returns results in bulks of 25 so set limit to a multiple of 25. Example in PERL: #Override row return from 25 to 1000 $rpt_limit = "&limit=1000"; $rpt_url = sprintf("%s%s%s%s%s", $rpt_base, $rpt_path, $rpt_limit, $key_add, $api_key); https://api-na.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FBoston College%2FReports%2FDatawarehouse%2Fe-journal fund info by ISSN&limit=1000&apikey=YOUR_API_KEY_HERE

Using the Resumption Token If there are more results than specified in your rpt_limit, the response will include a ResumptionToken and IsFinished will be false: Only the initial response will return a resumption token, and the same token should be used throughout the session for a given report - Send the same request over and over until IsFinished=true.

Optional Parameters: filters Filters – you can apply your filters directly in your report or you can pass them as parameters in the API call. Pass them as parameters if your run-time parameters will change. The syntax for adding filters to the call is an XML representation of a saw:filter object. The syntax is confusing. To figure it out go back to the your report in Analytics and add the filter there. Then click on the 'Advanced' tab and in the Analysis XML text area search for 'saw:filter‘. I copied the entire Analysis XML area from the Advanced tab into notepad so I could search for the saw:filter area. I then used notepad to build the filter I wanted to copy into my API call. Once you have copied the syntax for the filter out of your report set the filter to ‘Is Prompted’ in Alma Analytics.

Filters, cont

Filters, cont Example of filter copied from Analytics Report: Filter: Permanent LC Classification Code begins with R What filter looks like in the Advanced Analysis XML: <saw:filter> <sawx:expr xsi:type="sawx:list" op="beginsWith"> <sawx:expr xsi:type="sawx:sqlExpression">"Holding Details"."Permanent LC Classification Code"</sawx:expr> <sawx:expr xsi:type="xsd:string">R</sawx:expr></sawx:expr></sawx:expr> </saw:filter>

Filters, cont Now set the filter to ‘Is Prompted’ in your report: Refer to the tech blog referenced in slide 3 to determine how to convert the filter using namespaces for URL Encoding.

Filters, cont: URL Encoding $rpt_filter_begin = "&filter=%3Csawx%3Aexpr%20xsi%3Atype%3D%22sawx%3Alogical%22%20op%3D%22beginsWith%22%20xmlns%3Asaw%3D%22com.siebel.analytics.web%2Freport%2Fv1.1%22%20%0Axmlns%3Asawx%3D%22com.siebel.analy\ tics.web%2Fexpression%2Fv1.1%22%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20%0Axmlns%3Axsd%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%22%3E%0A%3Csawx%3Aexpr%20xsi%3Atype\ %3D%22sawx%3AsqlExpression%22%3E%22Holding%20Details%22.%22Permanent%20LC%20Classification%20Code%22%3C%2Fsawx%3Aexpr%3E%0A%3Csawx%3Aexpr%20xsi%3Atype%3D%22xsd%3Astring%22%3E"; $rpt_filter_end = "% 3C%2Fsawx%3Aexpr%3E%0A%3C%2Fsawx%3Aexpr%3E"; $rpt_args = "R"; $rpt_filter = sprintf("%s%s%s", $rpt_filter_begin, $rpt_args, $rpt_filter_end);

Full API Call https://api-na.hosted.exlibrisgroup.com/almaws/v1/analytics/reports?path=%2Fshared%2FBoston College%2FReports%2FDatawarehouse%2FPullItem&limit=1000&apikey=YOUR_API_KEY_HERE&filter=%3Csawx%3Aexpr%20xsi%3Atype%3D%22sawx%3Alogical%22%20op%3D%22beginsWith%22%20xmlns%3Asaw%3D%22com.siebel.analytics.web%2Freport%2Fv1.1%22%20%0Axmlns%3Asawx%3D%22com.siebel.analytics.web%2Fexpression%2Fv1.1%22%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20%0Axmlns%3Axsd%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema%22%3E%0A%3Csawx%3Aexpr%20xsi%3Atype%3D%22sawx%3AsqlExpression%22%3E%22Holding%20Details%22.%22Permanent%20LC%20Classification%20Code%22%3C%2Fsawx%3Aexpr%3E%0A%3Csawx%3Aexpr%20xsi%3Atype%3D%22xsd%3Astring%22%3ER%3C%2Fsawx%3Aexpr%3E%0A%3C%2Fsawx%3Aexpr%3E

Find Code on Github

Easier Access to Alma data from Tableau For those of you out there using Tableau, Ex Libris has just released a web page whose URL you can plug into the Tableau Web Data Connector that facilitates easy access to your Alma Analytics reports. You just need to add your API key and the path to the report you want to run. For more information see the Power Point on the Ex Libris Knowledgebase: https://knowledge.exlibrisgroup.com/Alma/Training/Extended_Training/Presentations_and_Documents - click on Analytics and then click on link for ‘Analytics - Using Alma Analytics With the Tableau Web Data Connector.pptx’

Questions / Discussion? Contact me: ELUNA Conference 2017 Questions / Discussion? Contact me: Margaret Briand Wolfe briandwo@bc.edu