exlibris-aleph 0.0.2 → 0.1.0

data/README.rdoc

@@ -1,3 +1,56 @@
 = Exlibris::Aleph
 
-This project rocks and uses MIT-LICENSE.
+Exlibris::Primo offers a set of libraries for interacting with the ExLibris Aleph ILS.
+
+== Exlibris::Aleph::Patron
+Exlibris::Aleph::Patron provides access to the Aleph Patron REST API.
+
+=== Example of Exlibris::Aleph::Patron in action
+  patron = 
+    Exlibris::Aleph::Patron.
+      new("S0M31D", "http://aleph.institution.edu")
+  patron.address # Returns HTTParty::Response of patron's address
+  patron.loans # Returns HTTParty::Response patron's loan
+  patron.renew_loans # Renews all loans
+  patron.renew_loans("ADM5000000001") # Renews loan of item 00000001 in ADM50
+  patron.place_hold("ADM50", "SBLIB", "00000001", "00000001", {:pickup_location => "SBLIB"}) # Places hold on the specified item for pickup at SBLIB
+  
+== Exlibris::Aleph::Record
+Provides access to the Aleph Record REST API.
+
+=== Example of Exlibris::Aleph::Record in action
+  record = 
+    Exlibris::Aleph::Record.
+      new("ADM50", "00000001", "http://aleph.institution.edu")
+  record.bib # Returns HTTParty::Response of record's bibliographic metadata
+  record.holdings # Returns HTTParty::Response of record's holdings
+  record.items # Returns HTTParty::Response of record's items
+
+== Exlibris::Aleph::TabHelper
+Exlibris::Aleph::TabHelper provides a way to access the various tab settings for patrons, patron_permissions, items, item_permission (both by item status and by item processing status), collections and pickup locations. It also provides convenience methods for common tasks like getting the pickup location for a given combination of item status, item process status and borrower status or getting an item's web text.
+
+=== Example of Exlibris::Aleph::TabHelper in action
+  # Placed this in an initializer.
+  Exlibris::Aleph::TabHelper.init("/mnt/aleph_tab", ["ADM50", "ADM50"])
+
+  # Rake task to refresh the config yml files
+  rake exlibris:aleph:refresh
+
+  # Get an instance of TabHelper
+  helper = Exlibris::Aleph::TabHelper.instance
+  helper.sub_library_text("SBLIB") # Returns display text for the give code
+  helper.sub_library_adm("SBLIB") # Returns ADM for the give code
+  helper.item_pickup_locations({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :bor_status => "51"}) # Returns the pickup locations for the given parameters
+  helper.collection_text({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :collection_code => "MAIN"}) # Returns the collection display text for the give parameters
+  helper.item_web_text({:adm_library_code => "ADM50", :item_process_status => "Item Process Status"}) # Returns the web text for the given parameters
+  helper.item_web_text({:adm_library_code => "ADM50", :sub_library_code => "SBLIB", :item_process_status_code => "DP"}) # Returns the web text for the given parameters
+  
+== Exlibris::Aleph::BorAuth
+Exlibris::Aleph::BorAuth provides access to the BorAuth Aleph XService.
+
+=== Example of Exlibris::Aleph::BorAuth in action
+  bor_auth = 
+    Exlibris::Aleph::BorAuth.
+      new("http://aleph.institution.edu", "ADM50", "SBLIB", "N", "S0M31D", "V3R1F1C@T10N")
+  permissions = bor_auth.permissions # Return a Hash of permissions based on the Exlibris::Aleph::BorAuth instance
+

data/lib/exlibris/aleph/bor_auth.rb

@@ -2,8 +2,12 @@ module Exlibris
   module Aleph
     require 'open-uri'
     require 'nokogiri'
+    # ==Overview
+    # Exlibris::Aleph::BorAuth provides access to the BorAuth Aleph XService.
     class BorAuth
       attr_reader :response, :error, :session_id
+      
+      # Creates an instance of Exlibris::Aleph::BorAuth based on the input parameters.
       def initialize(aleph_url, library, sub_library, translate, bor_id, bor_verification)
         url = "#{aleph_url}/X?"
         url += "op=bor-auth&library=#{library}&"
@@ -13,7 +17,8 @@ module Exlibris
         @session_id = @response.at("//session-id").inner_text unless @response.at("//session-id").nil?
         @error = @response.at("//error").inner_text unless @response.at("//error").nil?
       end
-    
+      
+      # Returns a Hash of permissions for the Aleph sub library passed into the constructor.
       def permissions
         rv = {}
         return rv unless @response and self.error.nil?

data/lib/exlibris/aleph/patron.rb

@@ -1,8 +1,11 @@
 module Exlibris
   module Aleph
+    # ==Overview
+    # Provides access to the Aleph Patron REST API.
     class Patron < Rest
-      attr_accessor :patron_id
-
+      attr_reader :patron_id
+      
+      # Creates an instance of Exlibris::Aleph::Patron for the given :patron_id
       def initialize(patron_id, uri)
         @patron_id = patron_id
         raise "Initialization error in #{self.class}. Missing patron id." if @patron_id.nil?
@@ -11,7 +14,8 @@ module Exlibris
       end
 
       # Place a hold on the specificed item.
-      # Raises errors if 
+      # Raises an error if there was a problem placing the hold.
+      # Returns a HTTParty::Response.
       def place_hold(adm_library, bib_library, bib_id, item_id, params)
         pickup_location = params[:pickup_location]
         raise "Error in place hold.  Missing pickup location." if pickup_location.nil?
@@ -40,29 +44,38 @@ module Exlibris
         return @response
       end
 
-      def get_address()
+      # Call the patronInformation/address Aleph Patron REST API
+      # Returns a HTTParty::Response.
+      def address()
         @response = self.class.get(self.uri+ "/patronInformation/address")
         return nil unless error.nil?
         return @response
       end
 
+      # Call the circulationActions/loans Aleph Patron REST API
+      # Returns a HTTParty::Response.
       def loans()
         @response = self.class.get(@uri+ "/circulationActions/loans?view=full")
         raise "Error getting loans through Aleph REST APIs. #{error}" unless error.nil?
         return @response
       end
 
+      # Renew the specified item.
+      # Will renew all if item not specified.
+      # Returns a HTTParty::Response.
       def renew_loans(item_id="")
-        # Will renew all if specific item not specified
         @response = self.class.post(@uri+ "/circulationActions/loans/#{item_id}")
         raise "Error renewing loan(s) through Aleph REST APIs. #{error}" unless error.nil?
         return @response
       end
-
+      
+      # Returns the note associated with the request.
       def note
         return (not @response.first.last.kind_of?(Hash) or @response.first.last["create_hold"].nil?) ? "" : ": #{@response.first.last["create_hold"]["note"]}" if @response.instance_of?(Hash)
       end
-
+      
+      # Returns the error associated with the request.
+      # Returns nil if no error.
       def error
         return nil if reply_code == "0000"
         return "#{reply_text}#{note}"

data/lib/exlibris/aleph/railtie.rb

@@ -0,0 +1,9 @@
+module Exlibris
+  module Aleph
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load "tasks/exlibris-aleph_tasks.rake"
+      end
+    end
+  end
+end

data/lib/exlibris/aleph/record.rb

@@ -1,6 +1,11 @@
 module Exlibris
   module Aleph
+    # ==Overview
+    # Provides access to the Aleph Record REST API.
     class Record < Rest
+      attr_reader :bib_library, :record_id
+
+      # Creates an instance of Exlibris::Aleph::Record for the given :bib_library and :record_id
       def initialize(bib_library, record_id, uri)
         @record_id = record_id
         raise "Initialization error in #{self.class}. Missing record id." if @record_id.nil?
@@ -18,6 +23,7 @@ module Exlibris
       # Returns an XML string representation of a bib.  
       # Every method call refreshes the data from the underlying API.
       # Raises and exception if there are errors.
+      # Returns a HTTParty::Response.
       def bib
         @response = self.class.get(@uri+ "?view=full")
         raise "Error getting bib from Aleph REST APIs. #{error}" unless error.nil?
@@ -27,6 +33,7 @@ module Exlibris
       # Returns an array of items. Each item is represented as an HTTParty hash. 
       # Every method call refreshes the data from the underlying API.
       # Raises an exception if the response is not valid XML or there are errors.
+      # Returns a HTTParty::Response.
       def items
         @items = []
         self.class.format :xml
@@ -46,6 +53,7 @@ module Exlibris
       # Returns an XML string representation of holdings 
       # Every method call refreshes the data from the underlying API.
       # Raises and exception if there are errors.
+      # Returns a HTTParty::Response.
       def holdings
         @response = self.class.get(@uri+ "/holdings?view=full")
         raise "Error getting holdings from Aleph REST APIs. #{error}" unless error.nil?

data/lib/exlibris/aleph/rest.rb

@@ -1,17 +1,27 @@
 module Exlibris
   module Aleph
     require 'httparty'
+    # ==Overview
+    # Base implementation for Aleph REST APIs.  
+    # Not intended for use on its own, but should
+    # instead be extended by implementing classes.
     class Rest
       include HTTParty
       format :xml
+      # Create and instance of Exlibris::Aleph::Rest for the given Aleph URI.
       def initialize(uri)
         @uri = uri
         raise "Initialization error in #{self.class}. Missing URI." if @uri.nil?
       end
+
+      # Returns the error associated with the request.
+      # Returns nil if no error.
       def error
         return nil if reply_code == "0000" 
         return "#{reply_text}"
       end
+
+      # Returns the reply code associate with the request.
       def reply_code
         return "No response." if @response.nil?
         return (not @response.first.last.kind_of?(Hash) or @response.first.last["reply_code"].nil?) ? "Unexpected response hash." : @response.first.last["reply_code"] if @response.instance_of?(Hash)
@@ -19,6 +29,8 @@ module Exlibris
         return (response_match.nil?) ? "Unexpected response string." : response_match[1] if @response.instance_of?(String)
         return "Unexpected response type."
       end
+
+      # Returns the reply text associate with the request.
       def reply_text
         return "No response." if @response.nil?
         return (not @response.first.last.kind_of?(Hash) or @response.first.last["reply_text"].nil?) ? "Unexpected response hash." : @response.first.last["reply_text"] if @response.instance_of?(Hash)

data/lib/exlibris/aleph/tab_helper.rb

@@ -1,32 +1,51 @@
-# This guy is a singleton, get one with Exlibris::Aleph::TabHelper.instance
 module Exlibris
   module Aleph
     require 'singleton'
     require 'yaml'
+    require 'rails'
+    # ==Overview
+    # Exlibris::Aleph::TabHelper assumes a mount of Aleph tab files and provides
+    # a way to access the various tab settings for patrons, patron_permissions,
+    # items, item_permission (both by item status and by item processing status), 
+    # collections and pickup locations.
+    # It also provides convenience methods for common tasks like getting the 
+    # pickup location for a given combination of item status, item process status
+    # and borrower status or getting an item's web text.
+    # To initialize Exlibris::Aleph::TabHelper call Exlibris::Aleph::TabHelper.init
+    # in an initializer.
     class TabHelper
       include Singleton
-      attr_reader :sub_libraries, :updated_at
-      @@tabs = { 
+      attr_reader :updated_at
+      @@alephe_tabs = {
+        :sub_libraries => :TabSubLibrary
+      }
+      @@adm_tabs = { 
         :patrons => :PcTabExpFieldExtended, 
         :patron_permissions => :Tab31, 
         :items => :TabWwwItemDesc, 
         :item_permissions_by_item_status => :Tab15ByItemStatus, 
         :item_permissions_by_item_process_status => :Tab15ByItemProcessStatus, 
         :collections => :Tab40, 
-        :pickup_locations =>  :Tab37}
+        :pickup_locations => :Tab37 }
+      @@tabs = @@alephe_tabs.keys + @@adm_tabs.keys
       @@adms = []
       @@tab_path = nil
       @@yml_path = nil
       @@log_path = nil
-
-      def self.init(tab_path, yml_path, log_path, adms)
-        @@tab_path = tab_path
-        @@adms = adms
-        @@yml_path = yml_path
-        @@log_path = log_path
-        Dir.mkdir(yml_path) unless Dir.exist?(yml_path)
-        @@adms.each { |adm| Dir.mkdir(File.join(yml_path, adm)) unless Dir.exist?(File.join(yml_path, adm)) }
-        Dir.mkdir(log_path) unless Dir.exist?(log_path)
+      
+      # Initialize TabHelper based on path to tabs, path to store yml configs,
+      # path for log file, and the ADMs for the Aleph implementation
+      #   Exlibris::Aleph::TabHelper.init("/mnt/aleph_tab", ["ADM50", "ADM51"])
+      def self.init(tab_path, adms, refresh_time = ->{1.day.ago})
+        @@tab_path, @@adms, @@refresh_time = tab_path, adms, refresh_time
+        # Set yml path and log path and make directories.
+        @@yml_path, @@log_path = File.join(Rails.root, "config/aleph"), File.join(Rails.root, "log")
+        Dir.mkdir(@@yml_path) unless @@yml_path.nil? or Dir.exist?(@@yml_path) 
+        Dir.mkdir(File.join(@@yml_path, "alephe")) unless @@yml_path.nil? or Dir.exist?(File.join(@@yml_path, "alephe"))
+        @@adms.each { |adm| 
+          Dir.mkdir(File.join(@@yml_path, adm)) unless @@yml_path.nil? or Dir.exist?(File.join(@@yml_path, adm)) 
+        } unless @@adms.nil?
+        Dir.mkdir(@@log_path) unless @@log_path.nil? or Dir.exist?(@@log_path)
         # Make readers for each class variable
         class_variables.each do |class_variable|
           define_method "#{class_variable}".sub('@@', '') do
@@ -35,58 +54,61 @@ module Exlibris
         end
       end
       
+      # Refreshes the yml files that are used to parse the tables.
       def self.refresh_yml
-        tab = Exlibris::Aleph::Config::TabSubLibrary.new({
-          :aleph_library => "ALEPHE", :aleph_mnt_path => @@tab_path}).to_h
-        File.open(File.join(@@yml_path, "#{:sub_libraries}.yml"), 'w') { |out| YAML.dump( tab, out ) } unless tab.empty?
-        @@tabs.each do |tab_name, tab_class|
+        @@alephe_tabs.each do |key, klass|
+          tab = Exlibris::Aleph::Config.const_get(klass).new({
+            :aleph_library => "ALEPHE", :aleph_mnt_path => @@tab_path}).to_h
+          File.open( File.join(@@yml_path, "alephe", "#{key}.yml"), 'w' ) { |out| YAML.dump( tab, out ) } unless tab.empty?
+        end
+        @@adm_tabs.each do |key, klass|
           @@adms.each do |adm|
-            tab = Exlibris::Aleph::Config.const_get(tab_class).new({
+            tab = Exlibris::Aleph::Config.const_get(klass).new({
               :aleph_library => adm, :aleph_mnt_path => @@tab_path}).to_h
-            File.open( File.join(@@yml_path, adm, "#{tab_name}.yml"), 'w' ) { |out| YAML.dump( tab, out ) } unless tab.empty?
+            File.open( File.join(@@yml_path, adm, "#{key}.yml"), 'w' ) { |out| YAML.dump( tab, out ) } unless tab.empty?
           end
         end
       end
       
+      # Private initialzize method for the singleton.
       def initialize
         raise ArgumentError.new("No tab path was specified.") if @@tab_path.nil?
         raise ArgumentError.new("No yml path was specified.") if @@yml_path.nil?
         raise ArgumentError.new("No log path was specified.") if @@log_path.nil?
-        raise ArgumentError.new("No ADMs were specified.") if @@adms.empty?
+        raise ArgumentError.new("No ADMs were specified.") if @@adms.nil? or @@adms.empty?
+        raise ArgumentError.new("No refresh time was specified.") if @@refresh_time.nil?
         self.class.refresh_yml
         @helper_log = Logger.new(File.join(@@log_path, "tab_helper.log"))
         @helper_log.level = Logger::WARN
-        @patrons = {}
-        @patron_permissions = {}
-        @items = {}
-        @item_permissions_by_item_status = {}
-        @item_permissions_by_item_process_status = {}
-        @collections = {}
-        @pickup_locations = {}
-        @sub_libraries = {}
-        @@tabs.each_key { |tab| self.class.send(:attr_reader, tab) }
+        @@tabs.each { |tab|
+          # Default to empty hash
+          instance_variable_set("@#{tab}".to_sym, {})
+          # Define reader w/ refresh
+          self.class.send(:define_method, tab) {
+            return instance_variable_get("@#{tab}".to_sym) unless refresh?
+            refresh and return instance_variable_get("@#{tab}".to_sym)
+          }
+        }
         refresh
       end
-  
-      def sub_library_text(params)
-        # raise_required_parameter_error :sub_library_code if params[:sub_library_code].nil?
-        sub_library = @sub_libraries[params[:sub_library_code]]
+
+      # Returns the sub library display text for the given sub library code
+      def sub_library_text(code)
+        sub_library = @sub_libraries[code]
         return sub_library[:text] unless sub_library.nil?
       end
   
-      def sub_library_adm(params)
-        # raise_required_parameter_error :sub_library_code if params[:sub_library_code].nil?
-        sub_library = @sub_libraries[params[:sub_library_code]]
+      # Returns the ADM associated with the given sub library code
+      def sub_library_adm(code)
+        sub_library = @sub_libraries[code]
         return sub_library[:library] unless sub_library.nil?
       end
   
+      # Returns an array of pickup locations based on the given params.
+      # Available param keys are:
+      #   :adm_library_code, :sub_library_code, :item_status_code,
+      #   :item_process_status_code, :bor_status, :availability_status
       def item_pickup_locations(params)
-        # raise_required_parameter_error :adm_library_code if params[:adm_library_code].nil?
-        # raise_required_parameter_error :sub_library_code if params[:sub_library_code].nil?
-        # raise_required_parameter_error :item_status_code if params[:item_status_code].nil?
-        # raise_required_parameter_error :item_process_status_code if params[:item_process_status_code].nil?
-        # raise_required_parameter_error :bor_status if params[:bor_status].nil?
-        # raise_required_parameter_error :availability_status if params[:availability_status].nil?
         adm_locations = pickup_locations[params[:adm_library_code]]
         sub_locations = adm_locations[params[:sub_library_code]] unless adm_locations.nil?
 
@@ -178,25 +200,31 @@ module Exlibris
           return [params[:sub_library_code]]
       end
   
+      # Returns collection text for the given params.
+      # Available param keys are:
+      #   :adm_library_code, :sub_library_code, :collection_code
       def collection_text(params)
-        # raise_required_parameter_error :adm_library_code if params[:adm_library_code].nil?
-        # raise_required_parameter_error :sub_library_code if params[:sub_library_code].nil?
-        # raise_required_parameter_error :collection_code if params[:collection_code].nil?
         adm = collections[params[:adm_library_code]]
         sub = adm[params[:sub_library_code]] unless adm.nil?
         coll = sub[params[:collection_code]] unless sub.nil?
         return coll[:text] unless coll.nil?
       end
   
+      # Returns web display text for the given params.
+      # Available param keys are:
+      #   :adm_library_code, :sub_library_code, :item_status_code, :item_process_status_code, :item_status, :item_process_status
       def item_web_text(params)
         adm = items[params[:adm_library_code]]
-        item = (adm[params[:item_process_status]].nil?) ? adm[params[:item_status]] : adm[params[:item_process_status]] unless (params[:item_status].nil? and params[:item_process_status]) or adm.nil?
+        item = (adm[params[:item_process_status]].nil?) ? adm[params[:item_status]] : adm[params[:item_process_status]] unless (params[:item_status].nil? and params[:item_process_status].nil?) or adm.nil?
         permissions = item_permissions(params) if item.nil?
         item = adm[permissions[:text]] unless permissions.nil? or adm.nil?
         return item[:web_text] unless item.nil?
         return permissions[:text] unless permissions.nil?
       end
   
+      # Returns item permissions for the given params.
+      # Available param keys are:
+      #   :adm_library_code, :sub_library_code, :item_status_code, :item_process_status_code
       def item_permissions(params)
         unless params[:item_process_status_code].nil?
           adm_permissions = 
@@ -227,23 +255,25 @@ module Exlibris
         return {}
       end
   
+      private
       def refresh?
-        return true if (@updated_at.nil? or @updated_at < 1.day.ago)
+        return (@updated_at.nil? or @updated_at < @@refresh_time.call)
       end  
 
       def refresh
-        @updated_at = Time.now()
-        @sub_libraries = YAML.load_file(File.join(@@yml_path, "#{:sub_libraries}.yml"))
-        @@tabs.each_key do |tab_name|
+        @@alephe_tabs.each_key do |key|
+          instance_variable_set("@#{key}".to_sym, YAML.load_file(File.join(@@yml_path, "alephe", "#{key}.yml")))
+        end
+        @@adm_tabs.each_key do |key|
           @@adms.each do |adm|
-            tab = instance_variable_get("@#{tab_name}".to_sym)
-            tab[adm] = YAML.load_file(File.join(@@yml_path, adm, "#{tab_name}.yml"))
-            instance_variable_set("@#{tab_name}".to_sym, tab)
+            tab = instance_variable_get("@#{key}".to_sym)
+            tab[adm] = YAML.load_file(File.join(@@yml_path, adm, "#{key}.yml"))
+            instance_variable_set("@#{key}".to_sym, tab)
           end
         end
+        @updated_at = Time.now()
       end
 
-      private
       def raise_required_parameter_error(parameter)
         raise "Initialization error in #{self.class}. Missing required parameter: #{parameter}."
       end

data/lib/exlibris/aleph/version.rb

@@ -1,5 +1,5 @@
 module Exlibris
   module Aleph
-    VERSION = "0.0.2"
+    VERSION = "0.1.0"
   end
 end

data/lib/exlibris-aleph.rb

@@ -14,7 +14,8 @@ PATH = File.dirname(__FILE__) + "/exlibris/aleph/"
   'rest',
   'record',
   'patron',
-  'bor_auth'
+  'bor_auth',
+  'railtie'
 ].each do |library|
-  require PATH + library
+  require PATH + library if defined?(Rails)
 end

data/lib/tasks/exlibris-aleph_tasks.rake

@@ -1,13 +1,15 @@
-# desc "Explaining what the task does"
-# task :exlibris:aleph do
-#   # Task goes here
-# end
 namespace :exlibris do
   namespace :aleph do
+    desc "Initialize rake environment"
+    task :initialize do
+      Dir.glob("config/initializers/*.rb").each do |initializer|
+          require File.expand_path(File.join(Rails.root, initializer), __FILE__)
+      end
+    end
 
     desc "Refresh Aleph YAML Config"
-    task :refresh, [:aleph_mnt_path] => :environment do |t, args|
+    task :refresh => :initialize do
       Exlibris::Aleph::TabHelper.refresh_yml
     end
   end
-emd
+end

data/test/dummy/config/aleph/NYU50/collections.yml

@@ -755,6 +755,10 @@ NYHS:
     :collection_code: ADMIN
     :sub_library: NYHS
     :text: AdminOffice
+  ALMA:
+    :collection_code: ALMA
+    :sub_library: NYHS
+    :text: Almanacs
   ARCH:
     :collection_code: ARCH
     :sub_library: NYHS