Working with Analytics REST APIs
As of the September Alma release, the Analytics API is RESTful. Like other REST APIs, documentation is available in the Alma section of this website. The following post provides some more detail for advanced users.
The reports resource (/almaws/v1/analytics/reports) requires one mandatory request parameter: path. The path is a URL-encoded full path to the report in the OBI catalog, so the simplest way to get this (and other arguments, as we will see) would be to open report in the Analytics UI. The path will appear in the URL:
So all you need to get started is to copy and paste it into your REST client (don’t forget a valid API key) with GET:
By default, the response will include up to 25 results. If there are more than 25 results, the response will include a ResumptionToken and IsFinished will be false:
<QueryResult> <ResumptionToken> E95A794F4077236B53DC4E34B9C072F481F2AB7D7626CDAE8B0D4296B27C0BA345B88774D96C464AC775E6B8C532D6F104D93C5C47D711E2124F45DA04AB72C7 </ResumptionToken> <IsFinished>false</IsFinished>
To get the next page, replace your path parameter with a token parameter:
Repeat the request until IsFinished=true. Note that only the initial response will return a token, and the same token should be used throughout the session for a given report – you simply send the same request over and over until IsFinished=true.
You can increase the number of results per request by setting a ‘limit’ parameter (any value between 25 and 1000), e.g.:
Note: OBI returns bulks of 25 results, i.e. if you set the limit to 30 and have more than 30 results, you will get up to 50 results in your response. To avoid confusion, it is therefore recommended to set your limit to multiples of 25.
There are two typical ways to work with filters:
1. Apply the filter directly to the report. Use this option when your filter parameters are static. For example, in the “Expenditure Per Transaction Item Type for the current year” report, the filter “Year(Current_Date)” is applied to the “Transaction Date Fiscal Year” field, and there is no need to routinely change this value:
In this case, calling the API will always return the filtered results without any further necessary action.
2. Add the filter to the API request. Use this option when your app needs to run the same report with changing (or multiple) filters. The filter should be appended to the request as a filter querystring parameter. The value is an XML representation of a saw:filter object. The syntax is not very straightforward. Fortunately, the OBI UI can help with this. Going back to the report in the previous example, click on the ‘Advanced’ tab and in the Analysis XML text area search for ‘saw:filter’:
You can clearly see how the filter is expressed in XML format. This would be the recommended method for building your filters: create them in the UI, copy the XML, and delete using the UI.
Returning to our original example using the ‘Expenditure Per year – Month’ report, let’s add a filter to remove all data before 2010:
In the “Advanced” tab, locate the relevant expression within the filter:
Now you need to go back and remove the filter (since you\re going to be applying it through the URL).
Note: In some cases we have found that setting the filter to ‘prompted’ is required by OBI for the API call to work. It is therefore recommended to add an ‘is prompted’ condition for every field you plan to filter (you do not need to add this in the API request itself). In the example below, I plan to add a filter by Year Key, so, using the ‘add filter’ icon on the far right I selected the ‘Year Key’ column and added an “is prompted” condition.
Let’s get back to the xml-formatted filter. Before we can add this as a filter parameter, we need to add namespaces:
<sawx:expr xsi:type="sawx:comparison" op="greaterOrEqual" xmlns:saw="com.siebel.analytics.web/report/v1.1" xmlns:sawx="com.siebel.analytics.web/expression/v1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <sawx:expr xsi:type="sawx:sqlExpression">"Transaction Dates"."Transaction Date Fiscal Year"</sawx:expr> <sawx:expr xsi:type="xsd:decimal">2010</sawx:expr> </sawx:expr>
This needs to be URL encoded, so our request should look like this:
Which returns the following set.
As you can see, the results are properly filtered.
- If your filter contains apostrophes, these must be xml-escaped (i.e. replace ‘ with ') before URL-encoding. An apostrophe after xml-escaping and URL-encoding will be %26apos%3B.
- Requests submitted via the the API console should not be URL-encoded.
- If your report has more than one filter you can sew them together like so:
<sawx:expr xsi:type="sawx:comparison" op="equal">
<sawx:expr xsi:type="sawx:sqlExpression">"Patron Details"."Patron Id"</sawx:expr>
<sawx:expr xsi:type="sawx:comparison" op="equal">
<sawx:expr xsi:type="sawx:sqlExpression">"Loan Circulation Desk"."Circ Desk Code"</sawx:expr>
The paths resource (/almaws/v1/analytics/paths) allows you to retrieve the path to an analytics report: It takes the analytics catalog path as a URL parameter and returns a list of sub directories and reports that appear under that path.
The API can be called without specifying the path – i.e. /almaws/v1/analytics/paths. Alma will return the root directory(s) in the analytics file hierarchy. e.g.:
<paths> <path link="/almaws/v1/analytics/paths/shared" type="dir">shared</path> </paths>
It is also possible to call the API with the path specified – e.g. /almaws/v1/analytics/paths/shared.
See also our Access Your Report List with the New Analytics Paths API blog.