# Alma A client for Web Services provided by the Ex Libris's Alma Library System. ## Installation Add this line to your application's Gemfile: ```ruby gem 'alma' ``` And then execute: $ bundle Or install it yourself as: $ gem install alma ## Usage ### Configuration You'll need to configure the Alma gem to ensure you query the appropriate data. To do so in a rails app, create `config/initializers/alma.rb` with : ```ruby Alma.configure do |config| # You have to set the apikey config.apikey = 'EXAMPLE_EL_DEV_NETWORK_APPLICATION_KEY' # Alma gem defaults to querying Ex Libris's North American API servers. You can override that here. config.region = "https://api-eu.hosted.exlibrisgroup.com" # By default enable_loggable is set to false config.enable_loggable = false # By default timeout is set to 5 seconds; can only provide integers config.timeout = 10 end ``` Now you can access those configuration attributes with `Alma.configuration.apikey` ### Making Requests #### Get a Single user ```ruby user = Alma::User.find(123456789) user.first_name > Chad user.email > chad.nelson@fictional.edu user.keys >{first_name: "Chad", ...} ``` #### Get details on a users fines ```ruby fines = user.fines fines.sum > "20.0" fines.total_record_count > "2" fines > [#, #] fines.first.title > "Practical Object Oriented Design with Ruby" ``` Each fine object reflects the available fields in the returned JSON,[as documented on the Ex Libris Api docs](https://developers.exlibrisgroup.com/alma/apis/xsd/rest_fees.xsd?tags=GET) #### Get details on a users loans ```ruby loans = user.loans loans.total_record_count > "2" loans > [#, #] loans.first.title > "Javascript: The Good Parts" loans.first.due_date "2016-12-26z" ``` Each loan object reflects the available fields in the returned XML,[as documented on the Ex Libris Api docs](https://developers.exlibrisgroup.com/alma/apis/xsd/rest_item_loans.xsd?tags=GET) #### Get details on a users requests - WIP ```ruby requests = user.requests requests.total_record_count > "1" requests.list > [#] requests.list.first.title > "Food in history / Reay Tannahill." requests.list.first.pickup_location > "Main Library" requests.list.first.request_status > "In Process" ``` Each request object reflects the available fields in the returned XML,[as documented on the Ex Libris Api docs](https://developers.exlibrisgroup.com/alma/apis/xsd/rest_user_requests.xsd?tags=GET) Loans, fines and Requests can also be accessed statically ```ruby Alma::User.get_fines({:user_id => 123456789}) Alma::User.get_loans({:user_id => 123456789}) Alma::User.get_requests({:user_id => 123456789}) ``` ##### Get a single user without fees, requests, or loans By default, this gem fetches a user's fees, requests, and loans. If you don't want these, you can pass the `expand` param with only the expansions you need. ```ruby # don't request fees or loans user = Alma::User.find(123456789, expand: 'requests') # don't request any of the above user = Alma::User.find(123456789, expand: '') ``` ### Bib Records Wrappings for some of the API endpoints described by the [Bibliographic Records and Inventory ](https://developers.exlibrisgroup.com/alma/apis/bibs) section of the Ex Libris Developers Network ### All the items for a Bib Records Corresponds to the [Retrieve Items list](https://developers.exlibrisgroup.com/alma/apis/bibs/GET/gwPcGly021om4RTvtjbPleCklCGxeYAfEqJOcQOaLEvNcHQT0/ozqu3DGTurs/XxIP4LrexQUdc=/af2fb69d-64f4-42bc-bb05-d8a0ae56936e) api endpoint To get the list of items for all holdings of a bib record. `items = Alma::BibItem.find("EXAMPLE_MMS_ID")` You can also pass a holding ID as an option, if you only want that holdings items. `items = Alma::BibItem.find("EXAMPLE_MMS_ID", holding_id: EXAMPLE_HOLDING_ID)` The response is a BibItemSet which can be iterated over to access items: ```ruby items.each { ... } items.total_record_count > 4 ``` You can remove items that are missing or lost from the result set ` avail_items = items.filter_missing_and_lost ` Items can be grouped by the library they are held at, which returns a hash with library codes as the keys and an array of items as the values. ```ruby items.grouped_by_library { "MAIN" => [#], "NOT_MAIN" => [#, #,], } ``` The data for each item can be accessed via hash representation of the [item structure](https://developers.exlibrisgroup.com/alma/apis/xsd/rest_item.xsd), e.g.: ```ruby item = items.first item["holding_data"]["call_number"] "T385 .F79 2008" item["item_data"]["location"]["value"] "STACKS" ``` There are also numerous convenience methods ```ruby # Boolean checks item.in_temp_location? item.in_place? # Basically, On Shelf or Not item.non_circulating? item.missing_or_lost? item.has_temp_call_number? item.has_alt_call_number? item.has_process_type? # Opinionated Accessors - return the value, or an empty string # Returns temp library/location if appropriate, else normal library/location item.library item.library_name item.location item.location_name # which use these methods under the hood item.holding_library item.holding_location item.temp_library item.temp_location # Looks for Temp call number, then alternate call number, then normal call number item.call_number # and which use item.temp_call_number item.alt_call_number # standard accessors item.process_type item.base_status item.circulation_policy item.description item.public_note ``` ### Logging This gem exposes a loggable interface to responses. Thus a response will respond to `loggable` and return a hash with state values that may be of use to log. As a bonus, when we enable this feature using the `enable_loggable` configuration, error messages will contain the loggable values and be formatted as JSON. ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). Use `bundle exec guard` to continuously run specs while developing. ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/tulibraries/alma_rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).