Class: EBSCO::EDS::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/ebsco/eds/session.rb

Overview

Sessions are used to query and retrieve information from the EDS API.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Session

Creates a new session.

This can be done in one of two ways:

1. Environment variables

  • EDS_AUTH - authentication method: ‘ip’ or ‘user’

  • EDS_PROFILE - profile ID for the EDS API

  • EDS_USER - user id attached to the profile

  • EDS_PASS - user password

  • EDS_GUEST - allow guest access: ‘y’ or ‘n’

  • EDS_ORG - name of your institution or company

Example

Once you have environment variables set, simply create a session like this:

session = EBSCO::EDS::Session.new

2. Options

  • :auth

  • :profile

  • :user

  • :pass

  • :guest

  • :org

Example

session = EBSCO::EDS::Session.new {
  :auth => 'user',
  :profile => 'edsapi',
  :user => 'joe'
  :pass => 'secret',
  :guest => false,
  :org => 'Acme University'
}

Raises:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/ebsco/eds/session.rb', line 68

def initialize(options = {})

  @session_token = ''
  @citation_token = ''
  @auth_token = ''
  @config = {}
  @guest = true
  @api_hosts_list = ''
  @api_host_index = 0

  eds_config = EBSCO::EDS::Configuration.new
  if options[:config]
    @config = eds_config.configure_with(options[:config])
    # return default if there is some problem with the yaml file (bad syntax, not found, etc.)
    @config = eds_config.configure if @config.nil?
  else
    @config = eds_config.configure(options)
  end

  # these properties aren't in the config
  if options.has_key? :user
    @user = options[:user]
  elsif ENV.has_key? 'EDS_USER'
    @user = ENV['EDS_USER']
  end

  if options.has_key? :pass
    @pass = options[:pass]
  elsif ENV.has_key? 'EDS_PASS'
    @pass = ENV['EDS_PASS']
  end

  if options.has_key? :profile
    @profile = options[:profile]
  elsif ENV.has_key? 'EDS_PROFILE'
    @profile = ENV['EDS_PROFILE']
  end
  raise EBSCO::EDS::InvalidParameter, 'Session must specify a valid api profile.' if blank?(@profile)

  # these config options can be overridden by environment vars
  @auth_type              =  (ENV.has_key? 'EDS_AUTH') ? ENV['EDS_AUTH'] : @config[:auth]
  @org                    =  (ENV.has_key? 'EDS_ORG') ? ENV['EDS_ORG'] : @config[:org]
  @cache_dir              =  (ENV.has_key? 'EDS_CACHE_DIR') ? ENV['EDS_CACHE_DIR'] : @config[:eds_cache_dir]
  @auth_expire            =  (ENV.has_key? 'EDS_AUTH_CACHE_EXPIRES_IN') ? ENV['EDS_AUTH_CACHE_EXPIRES_IN'] : @config[:auth_cache_expires_in]
  @info_expire            =  (ENV.has_key? 'EDS_INFO_CACHE_EXPIRES_IN') ? ENV['EDS_INFO_CACHE_EXPIRES_IN'] : @config[:info_cache_expires_in]
  @retrieve_expire        =  (ENV.has_key? 'EDS_RETRIEVE_CACHE_EXPIRES_IN') ? ENV['EDS_RETRIEVE_CACHE_EXPIRES_IN'] : @config[:retrieve_cache_expires_in]
  @search_expire          =  (ENV.has_key? 'EDS_SEARCH_CACHE_EXPIRES_IN') ? ENV['EDS_SEARCH_CACHE_EXPIRES_IN'] : @config[:search_cache_expires_in]
  @export_format_expire   =  (ENV.has_key? 'EDS_EXPORT_FORMAT_CACHE_EXPIRES_IN') ? ENV['EDS_EXPORT_FORMAT_CACHE_EXPIRES_IN'] : @config[:export_format_cache_expires_in]
  @citation_styles_expire =  (ENV.has_key? 'EDS_CITATION_STYLES_CACHE_EXPIRES_IN') ? ENV['EDS_CITATION_STYLES_CACHE_EXPIRES_IN'] : @config[:citation_styles_cache_expires_in]


  @log_level =  (ENV.has_key? 'EDS_LOG_LEVEL') ? ENV['EDS_LOG_LEVEL'] : @config[:log_level]

  (ENV.has_key? 'EDS_GUEST') ?
      if %w(n N no No false False).include?(ENV['EDS_GUEST'])
        @guest = false
      else
        @guest = true
      end :
      @guest = @config[:guest]

  (ENV.has_key? 'EDS_USE_CACHE') ?
      if %w(n N no No false False).include?(ENV['EDS_USE_CACHE'])
        @use_cache = false
      else
        @use_cache = true
      end :
      @use_cache = @config[:use_cache]

  (ENV.has_key? 'EDS_DEBUG') ?
      if %w(y Y yes Yes true True).include?(ENV['EDS_DEBUG'])
        @debug = true
      else
        @debug = false
      end :
      @debug = @config[:debug]

  (ENV.has_key? 'EDS_HOSTS') ? @api_hosts_list = ENV['EDS_HOSTS'].split(',') : @api_hosts_list = @config[:api_hosts_list]

  (ENV.has_key? 'EDS_RECOVER_FROM_BAD_SOURCE_TYPE') ?
      if %w(y Y yes Yes true True).include?(ENV['EDS_RECOVER_FROM_BAD_SOURCE_TYPE'])
        @recover_130 = true
      else
        @recover_130 = false
      end :
      @recover_130 = @config[:recover_from_bad_source_type]

  # use cache for auth token, info, search and retrieve calls?
  if @use_cache
    cache_dir = File.join(@cache_dir, 'faraday_eds_cache')
    @cache_store = ActiveSupport::Cache::FileStore.new cache_dir
  end

  @max_retries = @config[:max_attempts]

  if options.has_key? :auth_token
    @auth_token = options[:auth_token]
  else
    @auth_token = create_auth_token
  end

  if options.key? :session_token
    @session_token = options[:session_token]
  else
    @session_token = create_session_token
  end

  if options.key? :citation_token
    @citation_token = options[:citation_token]
  else
    @citation_token = create_citation_token
  end

  @info = EBSCO::EDS::Info.new(do_request(:get, path: @config[:info_url]), @config)
  @current_page = 0
  @search_options = nil

  if @debug
    if options.key? :caller
      puts '*** CREATE SESSION CALLER: ' + options[:caller].inspect
      puts '*** CALLER OPTIONS: ' + options.inspect
    end
    puts '*** AUTH TOKEN: ' + @auth_token.inspect
    puts '*** SESSION TOKEN: ' + @session_token.inspect
    puts '*** CITATION TOKEN: ' + @citation_token.inspect
  end

end

Instance Attribute Details

#auth_token ⇒ Object

The authentication token. This is passed along in the x-authenticationToken HTTP header.



28
29
30
 
# File 'lib/ebsco/eds/session.rb', line 28

def auth_token
  @auth_token
end

#citation_token ⇒ Object

:nodoc:



31
32
33
 
# File 'lib/ebsco/eds/session.rb', line 31

def citation_token
  @citation_token
end

#config ⇒ Object (readonly)

The session configuration.



33
34
35
 
# File 'lib/ebsco/eds/session.rb', line 33

def config
  @config
end

#info ⇒ Object

Contains search Info available in the session profile. Includes the sort options, search fields, limiters and expanders available to the profile.



24
25
26
 
# File 'lib/ebsco/eds/session.rb', line 24

def info
  @info
end

#search_options ⇒ Object

Contains the search Options sent as part of each request to the EDS API such as limiters, expanders, search modes, sort order, etc.



26
27
28
 
# File 'lib/ebsco/eds/session.rb', line 26

def search_options
  @search_options
end

#session_token ⇒ Object

The session token. This is passed along in the x-sessionToken HTTP header.



30
31
32
 
# File 'lib/ebsco/eds/session.rb', line 30

def session_token
  @session_token
end

Instance Method Details

#add_actions(actions) ⇒ Object

:category: Search & Retrieve Methods Add actions to an existing search session Returns search Results.

Examples

results = session.add_actions('addfacetfilter(SubjectGeographic:massachusetts)')



550
551
552
553
 
# File 'lib/ebsco/eds/session.rb', line 550

def add_actions(actions)
  @search_options.add_actions(actions, @info)
  search()
end

#add_expander(val) ⇒ Object

:category: Expander Methods Adds expanders and sets the page number back to 1. Multiple expanders should be comma separated. Returns search Results.

Examples

results = session.add_expander('thesaurus,fulltext')



769
770
771
 
# File 'lib/ebsco/eds/session.rb', line 769

def add_expander(val)
  add_actions "AddExpander(#{val})"
end

#add_facet(facet_id, facet_val) ⇒ Object

:category: Facet Methods Adds a facet filter to the search request. Sets the page number back to 1. Returns search Results.

Examples

results = session.add_facet('Publisher', 'wiley-blackwell')
results = session.add_facet('SubjectEDS', 'water quality')



688
689
690
691
 
# File 'lib/ebsco/eds/session.rb', line 688

def add_facet(facet_id, facet_val)
  facet_val = eds_sanitize(facet_val)
  add_actions "AddFacetFilter(#{facet_id}:#{facet_val})"
end

#add_limiter(id, val) ⇒ Object

:category: Limiter Methods Adds a limiter to the currently defined search and sets the page number back to 1. Returns search Results.

Examples

results = session.add_limiter('FT','y')



729
730
731
 
# File 'lib/ebsco/eds/session.rb', line 729

def add_limiter(id, val)
  add_actions "AddLimiter(#{id}:#{val})"
end

#add_publication(pub_id) ⇒ Object

:category: Publication Methods Specifies a publication to search within. Sets the pages number back to 1. Returns search Results.

Examples

results = session.add_publication('eric')



793
794
795
 
# File 'lib/ebsco/eds/session.rb', line 793

def add_publication(pub_id)
  add_actions "AddPublication(#{pub_id})"
end

#add_query(query) ⇒ Object

:category: Search & Retrieve Methods Add a query to the search request. When a query is added, it will be assigned an ordinal, which will be exposed in the search response message. It also removes any specified facet filters and sets the page number to 1. Returns search Results.

Examples

results = session.add_query('AND,California')



531
532
533
 
# File 'lib/ebsco/eds/session.rb', line 531

def add_query(query)
  add_actions "AddQuery(#{query})"
end

#clear_expanders ⇒ Object

:category: Expander Methods Removes all specified expanders and sets the page number back to 1. Returns search Results.



760
761
762
 
# File 'lib/ebsco/eds/session.rb', line 760

def clear_expanders
  add_actions 'ClearExpanders()'
end

#clear_facets ⇒ Object

:category: Facet Methods Removes all specified facet filters. Sets the page number back to 1. Returns search Results.



677
678
679
 
# File 'lib/ebsco/eds/session.rb', line 677

def clear_facets
  add_actions 'ClearFacetFilters()'
end

#clear_limiters ⇒ Object

:category: Limiter Methods Clears all currently specified limiters and sets the page number back to 1. Returns search Results.



720
721
722
 
# File 'lib/ebsco/eds/session.rb', line 720

def clear_limiters
  add_actions 'ClearLimiters()'
end

#clear_queries ⇒ Object

:category: Search & Retrieve Methods Clears all queries and facet filters, and set the page number back to 1; limiters and expanders are not modified. Returns search Results.



521
522
523
 
# File 'lib/ebsco/eds/session.rb', line 521

def clear_queries
  add_actions 'ClearQueries()'
end

#clear_search ⇒ Object

:category: Search & Retrieve Methods Clear all specified query expressions, facet filters, limiters and expanders, and set the page number back to 1. Returns search Results.



514
515
516
 
# File 'lib/ebsco/eds/session.rb', line 514

def clear_search
  add_actions 'ClearSearch()'
end

#dbid_in_profile(dbid) ⇒ Object

:category: Profile Settings Methods Determine if a database ID is available in the profile. Returns Boolean.



1073
1074
1075
 
# File 'lib/ebsco/eds/session.rb', line 1073

def dbid_in_profile(dbid)
  get_available_database_ids.include? dbid
end

#do_jump_request(method, path:, payload: nil, attempt: 0) ⇒ Object

:nodoc:



1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
 
# File 'lib/ebsco/eds/session.rb', line 1008

def do_jump_request(method, path:, payload: nil, attempt: 0) # :nodoc:

  if attempt > @config[:max_page_jump_attempts]
    raise EBSCO::EDS::ApiError, 'EBSCO API error: Multiple attempts to perform request failed.'
  end
  begin
    if @debug
      if payload.instance_variable_defined?(:@Actions)
        puts 'JUMP ACTION: ' + payload.Actions.inspect if @debug
      end
      puts 'JUMP ATTEMPT: ' + attempt.to_s if @debug
    end
    # turn off caching
    resp = jump_connection.send(method) do |req|
      case method
        when :get
          req.url path
        when :post
          req.url path
          unless payload.nil?
            req.body = JSON.generate(payload)
          end
        else
          raise EBSCO::EDS::ApiError, "EBSCO API error: Method #{method} not supported for endpoint #{path}"
      end
    end
    resp
  rescue Error => e
    if e.respond_to? 'fault'
      error_code = e.fault[:error_body]['ErrorNumber'] || e.fault[:error_body]['ErrorCode']
      unless error_code.nil?
        case error_code
          when '138'
            sleep Random.new.rand(1..3)
            do_jump_request(method, path: path, payload: payload, attempt: attempt+1)
          else
            raise e
        end
      end
    end

  end
end

#do_request(method, path:, payload: nil, attempt: 0) ⇒ Object

–

INTERNAL METHODS

++



817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
 
# File 'lib/ebsco/eds/session.rb', line 817

def do_request(method, path:, payload: nil, attempt: 0) # :nodoc:

  if attempt > @config[:max_attempts]
    raise EBSCO::EDS::ApiError, 'EBSCO API error: Multiple attempts to perform request failed.'
  end
  begin

    conn = connection

    config_path = path.dup

    # use a citation api connection?
    if path.include?(@config[:citation_exports_url]) || path.include?(@config[:citation_styles_url])
      conn = citation_connection
    end

    resp = conn.send(method) do |req|
      case method
        when :get
          unless payload.nil?
            qs = CGI.unescape(payload.to_query(nil))
            config_path << '?' + qs
          end
         req.url config_path
        when :post
          unless payload.nil?
            json_payload = JSON.generate(payload)
            config_path << get_cache_id(path, json_payload) if @use_cache
            req.body = json_payload
          end
          req.url config_path
        else
          raise EBSCO::EDS::ApiError, "EBSCO API error: Method #{method} not supported for endpoint #{config_path}"
      end
    end
    resp.body
  rescue Error => e

    # try alternate EDS hosts
    if e.is_a?(EBSCO::EDS::InternalServerError) || e.is_a?(EBSCO::EDS::ServiceUnavailable) || e.is_a?(EBSCO::EDS::ConnectionFailed)
      if @api_hosts_list.length > @api_host_index+1
        @api_host_index = @api_host_index+1
        do_request(method, path: path, payload: payload, attempt: attempt+1)
      else
        raise EBSCO::EDS::ApiError, 'EBSCO API error: Unable to establish a connection to any EDS host.'
      end
    end

    if e.respond_to? 'fault'

      error_code = e.fault[:error_body]['ErrorNumber'] || e.fault[:error_body]['ErrorCode']
      unless error_code.nil?
        case error_code
          # session token missing
          when '108', '109'
            @session_token = create_session_token
            do_request(method, path: path, payload: payload, attempt: attempt+1)
          # auth token invalid
          when '104', '107'
            # delete the auth cache to make sure we have an unexpired auth token
            if @use_cache
              puts 'DELETING AUTH CACHE...' if @debug
              @cache_store.delete_matched('https://' + @api_hosts_list[@api_host_index] + @config[:uid_auth_url])
            end
            @auth_token = nil
            @auth_token = create_auth_token
            do_request(method, path: path, payload: payload, attempt: attempt+1)

          # trying to paginate in results list beyond 250 results
          when '138'

            is_jump_retry = false
            is_orig_retry = false

            # create a jump request payload
            jump_payload = payload.clone

            # retry failed jump requests (known API issue)
            if jump_payload.instance_variable_defined?(:@Comment)
              if jump_payload.Comment == 'jump_request'
                is_jump_retry = true
                puts '138 JUMP RETRY ================================================================' if @debug
                do_jump_request(method, path: path, payload: jump_payload, attempt: attempt+1)
              elsif jump_payload.Comment == 'jump_request_orig'
                is_orig_retry = true
                puts '138 ORIG RETRY ================================================================' if @debug
                jump_response = do_jump_request(method, path: path, payload: payload, attempt: attempt+1)
                if jump_response.success?
                  return jump_response.body
                end
              else
                puts '138 ERROR =====================================================================' if @debug
              end
            end

            # only perform these steps if it's the original 138 error
            unless is_jump_retry or is_orig_retry
              # remove these variables since they prevent a jump request (they continue to cause more 138 errors)
              if jump_payload.SearchCriteria.instance_variable_defined?(:@AutoSuggest)
                jump_payload.SearchCriteria.remove_instance_variable(:@AutoSuggest)
              end
              if jump_payload.SearchCriteria.instance_variable_defined?(:@AutoCorrect)
                jump_payload.SearchCriteria.remove_instance_variable(:@AutoCorrect)
              end
              if jump_payload.SearchCriteria.instance_variable_defined?(:@Expanders)
                jump_payload.SearchCriteria.remove_instance_variable(:@Expanders)
              end
              if jump_payload.SearchCriteria.instance_variable_defined?(:@RelatedContent)
                jump_payload.SearchCriteria.remove_instance_variable(:@RelatedContent)
              end
              if jump_payload.SearchCriteria.instance_variable_defined?(:@Limiters)
                jump_payload.SearchCriteria.remove_instance_variable(:@Limiters)
              end

              # get list of jump pages and make requests for each one before requesting the original request
              jump_pages = get_jump_pages(payload)
              # todo: truncate to @confi[:max_page_jumps]
              jump_pages.each { |page|
                jump_payload.Actions = ["GoToPage(#{page})"]
                jump_payload.Comment = 'jump_request' # comment the request so we can retry if necessary
                do_jump_request(method, path: path, payload: jump_payload, attempt: attempt+1)
              }

              # now make the original request (which can also require retries)
              payload.Comment = 'jump_request_orig'
              do_request(method, path: path, payload: payload, attempt: attempt+1)
            end

          # invalid source type, attempt to recover gracefully
          when '130'
            if @recover_130
              bad_source_type = e.fault[:error_body]['DetailedErrorDescription']
              bad_source_type.gsub!(/Value Provided\s+/, '')
              bad_source_type.gsub!(/\.\s*$/, '')
              new_actions = []
              payload.Actions.each { |action|
                if action.downcase.start_with?('addfacetfilter(sourcetype:')
                  if bad_source_type.nil?
                    # skip the source type since we don't know if it's bad or not
                  else
                    if !action.include?('SourceType:'+bad_source_type+')')
                      # not a bad source type, keep it
                      new_actions << action
                    end
                  end
                else
                  # not a source type action, add it
                  new_actions << action
                end
              }

              new_filters = []
              filter_id = 1
              payload.SearchCriteria.FacetFilters.each { |filter|
                filter['FacetValues'].each { |facet_val|
                  if facet_val['Id'] == 'SourceType'
                    if bad_source_type.nil?
                      # skip the source type since we don't know if it's bad or not
                    else
                      # not a bad sourcetype, add it
                      if !facet_val['Value'].include?(bad_source_type)
                      filter['FilterId'] = filter_id
                      filter_id += 1
                      new_filters << filter
                      end
                    end
                  else
                    # not a SourceType filter, add it
                    filter['FilterId'] = filter_id
                    filter_id += 1
                    new_filters << filter
                  end
                }
              }
              payload.SearchCriteria.FacetFilters = new_filters
              payload.Actions = new_actions
              do_request(method, path: path, payload: payload, attempt: attempt+1)
            else
              raise e
            end

          else
            raise e
        end
      end
    else
      raise e
    end
  end
end

#end ⇒ Object

:category: Search & Retrieve Methods Invalidates the session token. End Session should be called when you know a user has logged out.



504
505
506
507
508
509
 
# File 'lib/ebsco/eds/session.rb', line 504

def end
  # todo: catch when there is no valid session?
  do_request(:post, path: @config[:end_session_url], payload: {:SessionToken => @session_token})
  connection.headers['x-sessionToken'] = ''
  @session_token = ''
end

#get_available_database_ids ⇒ Object

:category: Profile Settings Methods Get a list of all available database IDs. Returns Array of IDs.



1066
1067
1068
 
# File 'lib/ebsco/eds/session.rb', line 1066

def get_available_database_ids
  get_available_databases.map{|item| item[:id]}
end

#get_available_databases ⇒ Object

– attempts to query profile capabilities dummy search just to get the list of available databases ++



1056
1057
1058
1059
1060
1061
 
# File 'lib/ebsco/eds/session.rb', line 1056

def get_available_databases # :nodoc:
  search({query: 'supercalifragilisticexpialidocious-supercalifragilisticexpialidocious',
          results_per_page: 1,
          mode: 'all',
          include_facets: false}).database_stats
end

#get_citation_exports(dbid:, an:, format: 'all') ⇒ Object

fetch the citation from the citation rest endpoint



341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/ebsco/eds/session.rb', line 341

def get_citation_exports(dbid:, an:, format: 'all')
 begin
   # only available as non-guest otherwise 148 error
   citation_exports_params = "?an=#{an}&dbid=#{dbid}&format=#{format}"
   citation_exports_response = do_request(:get, path: @config[:citation_exports_url] + citation_exports_params)
   EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: citation_exports_response, eds_config: @config)
   rescue EBSCO::EDS::NotFound => e
     custom_error_message = JSON.parse e.message.gsub('=>', ':')
     # ErrorNumber 132 - Record not found
     if custom_error_message['ErrorNumber'] == '132'
       record_not_found = {"Format"=>format, "Label"=>"", "Data"=>"", "Error"=>"Record not found"}
       EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: record_not_found, eds_config: @config)
     end
   rescue EBSCO::EDS::BadRequest => e
      custom_error_message = JSON.parse e.message.gsub('=>', ':')
      # ErrorNumber 112 - Invalid Argument Value
      if custom_error_message['ErrorNumber'] == '112'
        unknown_export_format = {"Format"=>format, "Label"=>"", "Data"=>"", "Error"=>"Invalid citation export format"}
        EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: unknown_export_format, eds_config: @config)
      else
        unknown_error = {"Format"=>format, "Label"=>"", "Data"=>"", "Error"=>custom_error_message['ErrorDescription']}
        EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: unknown_error, eds_config: @config)
      end
    end
end

#get_citation_exports_list(id_list: [], format: 'all') ⇒ Object

get citation exports for a list of result ids



401
402
403
404
405
406
407
408
409
410
411
 
# File 'lib/ebsco/eds/session.rb', line 401

def get_citation_exports_list(id_list: [], format: 'all')
  citations = []
  if id_list.any?
    id_list.each { |id|
      dbid = id.split('__',2).first
      accession = id.split('__',2).last
      citations.push get_citation_exports(dbid: dbid, an: accession, format: format)
    }
  end
  citations
end

#get_citation_styles(dbid:, an:, format: 'all') ⇒ Object

fetch the citation from the citation rest endpoint



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# File 'lib/ebsco/eds/session.rb', line 368

def get_citation_styles(dbid:, an:, format: 'all')
   begin
     citation_styles_params = "?an=#{an}&dbid=#{dbid}&styles=#{format}"
     citation_styles_response = do_request(:get, path: @config[:citation_styles_url] + citation_styles_params)
     EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: citation_styles_response, eds_config: @config)
   rescue EBSCO::EDS::NotFound => e
     custom_error_message = JSON.parse e.message.gsub('=>', ':')
     # ErrorNumber 132 - Record not found
     if custom_error_message['ErrorNumber'] == '132'
       record_not_found = {"Format"=>format, "Label"=>"", "Data"=>"", "Error"=>"Record not found"}
       EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: record_not_found, eds_config: @config)
     end
   rescue EBSCO::EDS::BadRequest => e
     custom_error_message = JSON.parse e.message.gsub('=>', ':')
     unknown_error = {"Id"=>format, "Label"=>"", "Data"=>"", "Error"=>custom_error_message['ErrorDescription']}
     EBSCO::EDS::Citations.new(dbid: dbid, an: an, citation_result: unknown_error, eds_config: @config)
   end
end

#get_citation_styles_list(id_list: [], format: 'all') ⇒ Object

get citation styles for a list of result ids



388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/ebsco/eds/session.rb', line 388

def get_citation_styles_list(id_list: [], format: 'all')
  citations = []
  if id_list.any?
    id_list.each { |id|
      dbid = id.split('__',2).first
      accession = id.split('__',2).last
      citations.push get_citation_styles(dbid: dbid, an: accession, format: format)
    }
  end
  citations
end

#get_page(page = 1) ⇒ Object

:category: Pagination Methods Get a specified page of results Returns search Results.



649
650
651
 
# File 'lib/ebsco/eds/session.rb', line 649

def get_page(page = 1)
  add_actions "GoToPage(#{page})"
end

#include_related_content(val) ⇒ Object

:category: Setter Methods A related content type to additionally search for and include with the search results. Returns search Results.

Examples

results = session.include_related_content('rs')



606
607
608
 
# File 'lib/ebsco/eds/session.rb', line 606

def include_related_content(val)
  add_actions "includerelatedcontent(#{val})"
end

#move_page(num) ⇒ Object

:category: Pagination Methods Increments the current results page number by the value specified. If the current page was 5 and the specified value was 2, the page number would be set to 7. Returns search Results.



657
658
659
 
# File 'lib/ebsco/eds/session.rb', line 657

def move_page(num)
  add_actions "MovePage(#{num})"
end

#next_page ⇒ Object

:category: Pagination Methods Get the next page of results. Returns search Results.



634
635
636
637
 
# File 'lib/ebsco/eds/session.rb', line 634

def next_page
  page = @current_page + 1
  get_page(page)
end

#prev_page ⇒ Object

:category: Pagination Methods Get the previous page of results. Returns search Results.



642
643
644
 
# File 'lib/ebsco/eds/session.rb', line 642

def prev_page
  get_page([1, @current_page - 1].sort.last)
end

#publication_match_in_profile ⇒ Object

:category: Profile Settings Methods Determine if publication matching is available in the profile. Returns Boolean.



1080
1081
1082
 
# File 'lib/ebsco/eds/session.rb', line 1080

def publication_match_in_profile
  @info.available_related_content_types.include? 'emp'
end

#remove_all_publications ⇒ Object

:category: Publication Methods Removes all publications from the search. Sets the page number back to 1. Returns search Results.



807
808
809
 
# File 'lib/ebsco/eds/session.rb', line 807

def remove_all_publications
  add_actions 'RemovePublication()'
end

#remove_expander(val) ⇒ Object

:category: Expander Methods Removes a specified expander. Sets the page number to 1. Returns search Results.

Examples

results = session.remove_expander('fulltext')



778
779
780
 
# File 'lib/ebsco/eds/session.rb', line 778

def remove_expander(val)
  add_actions "RemoveExpander(#{val})"
end

#remove_facet(group_id) ⇒ Object

:category: Facet Methods Removes a specified facet filter id. Sets the page number back to 1. Returns search Results.

Examples

results = session.remove_facet(45)



698
699
700
 
# File 'lib/ebsco/eds/session.rb', line 698

def remove_facet(group_id)
  add_actions "RemoveFacetFilter(#{group_id})"
end

#remove_facet_value(group_id, facet_id, facet_val) ⇒ Object

:category: Facet Methods Removes a specific facet filter value from a group. Sets the page number back to 1. Returns search Results.

Examples

results = session.remove_facet_value(2, 'DE', 'Psychology')



707
708
709
 
# File 'lib/ebsco/eds/session.rb', line 707

def remove_facet_value(group_id, facet_id, facet_val)
  add_actions "RemoveFacetFilterValue(#{group_id},#{facet_id}:#{facet_val})"
end

#remove_limiter(id) ⇒ Object

:category: Limiter Methods Removes the specified limiter and sets the page number back to 1. Returns search Results.

Examples

results = session.remove_limiter('FT')



738
739
740
 
# File 'lib/ebsco/eds/session.rb', line 738

def remove_limiter(id)
  add_actions "RemoveLimiter(#{id})"
end

#remove_limiter_value(id, val) ⇒ Object

:category: Limiter Methods Removes a specified limiter value and sets the page number back to 1. Returns search Results.

Examples

results = session.remove_limiter_value('LA99','French')



747
748
749
 
# File 'lib/ebsco/eds/session.rb', line 747

def remove_limiter_value(id, val)
  add_actions "RemoveLimiterValue(#{id}:#{val})"
end

#remove_publication(pub_id) ⇒ Object

:category: Publication Methods Removes a publication from the search. Sets the page number back to 1. Returns search Results.



800
801
802
 
# File 'lib/ebsco/eds/session.rb', line 800

def remove_publication(pub_id)
  add_actions "RemovePublication(#{pub_id})"
end

#remove_query(query_id) ⇒ Object

:category: Search & Retrieve Methods Removes query from the currently specified search. It also removes any specified facet filters and sets the page number to 1. Returns search Results.

Examples

results = session.remove_query(1)



541
542
543
 
# File 'lib/ebsco/eds/session.rb', line 541

def remove_query(query_id)
  add_actions "removequery(#{query_id})"
end

#research_starters_match_in_profile ⇒ Object

:category: Profile Settings Methods Determine if research starters are available in the profile. Returns Boolean.



1087
1088
1089
 
# File 'lib/ebsco/eds/session.rb', line 1087

def research_starters_match_in_profile
  @info.available_related_content_types.include? 'rs'
end

#reset_page ⇒ Object

:category: Pagination Methods Get the first page of results. Returns search Results.



664
665
666
 
# File 'lib/ebsco/eds/session.rb', line 664

def reset_page
  add_actions 'ResetPaging()'
end

#results_per_page(num) ⇒ Object

:category: Setter Methods Sets the page size on the search request. Returns search Results.

Examples

results = session.results_per_page(50)



597
598
599
 
# File 'lib/ebsco/eds/session.rb', line 597

def results_per_page(num)
  add_actions "SetResultsPerPage(#{num})"
end

#retrieve(dbid:, an:, highlight: nil, ebook: 'ebook-pdf') ⇒ Object

:category: Search & Retrieve Methods Returns a Record based a particular result based on a database ID and accession number.

Attributes

  • :dbid - The database ID (required).

  • :an - The accession number (required).

  • highlight - Comma separated list of terms to highlight in the data records (optional).

  • ebook - Preferred format to return ebook content in. Either ebook-pdf (default) or ebook-pdf.

Examples

record = session.retrieve({dbid: 'asn', an: '108974507'})



325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/ebsco/eds/session.rb', line 325

def retrieve(dbid:, an:, highlight: nil, ebook: 'ebook-pdf')
  payload = { DbId: dbid, An: an, HighlightTerms: highlight, EbookPreferredFormat: ebook }
  retrieve_response = do_request(:post, path: @config[:retrieve_url], payload: payload)
  record = EBSCO::EDS::Record.new(retrieve_response, @config)
  record_citation_exports = get_citation_exports({dbid: dbid, an: an, format: @config[:citation_exports_formats]})
  unless record_citation_exports.nil?
    record.set_citation_exports(record_citation_exports)
  end
  record_citation_styles = get_citation_styles({dbid: dbid, an: an, format: @config[:citation_styles_formats]})
  unless record_citation_styles.nil?
    record.set_citation_styles(record_citation_styles)
  end
  record
end

#search(options = {}, add_actions = false, increment_page = true) ⇒ Object

:category: Search & Retrieve Methods Performs a search.

Returns search Results.

Options

  • :query - Required. The search terms. Format: booleanOperator,fieldCode:term. Example: SU:Hiking

  • :mode - Search mode to be used. Either: all (default), any, bool, smart

  • :results_per_page - The number of records retrieved with the search results (between 1-100, default is 20).

  • :page - Starting page number for the result set returned from a search (if results per page = 10, and page number = 3 , this implies: I am expecting 10 records starting at page 3).

  • :sort - The sort order for the search results. Either: relevance (default), oldest, newest

  • :highlight - Specifies whether or not the search term is highlighted using <highlight /> tags. Either true or false.

  • :include_facets - Specifies whether or not the search term is highlighted using <highlight /> tags. Either true (default) or false.

  • :facet_filters - Facets to apply to the search. Facets are used to refine previous search results. Format: filterID,facetID:value* Example: 1,SubjectEDS:food,SubjectEDS:fiction

  • :view - Specifies the amount of data to return with the response. Either ‘title’: title only; ‘brief’ (default): Title + Source, Subjects; ‘detailed’: Brief + full abstract

  • :actions - Actions to take on the existing query specification. Example: addfacetfilter(SubjectGeographic:massachusetts)

  • :limiters - Criteria to limit the search results by. Example: LA99:English,French,German

  • :expanders - Expanders that can be applied to the search. Either: thesaurus, fulltext, relatedsubjects

  • :publication_id - Publication to search within.

  • :related_content - Comma separated list of related content types to return with the search results. Either ‘rs’ (Research Starters) or ‘emp’ (Exact Publication Match)

  • :auto_suggest - Specifies whether or not to return search suggestions along with the search results. Either true or false (default).

Examples

results = session.search({query: 'abraham lincoln', results_per_page: 5, related_content: ['rs','emp']})
results = session.search({query: 'volcano', results_per_page: 1, publication_id: 'eric', include_facets: false})



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/ebsco/eds/session.rb', line 224

def search(options = {}, add_actions = false, increment_page = true)
  # use existing/updated SearchOptions
  if options.empty?
    if @search_options.nil?
      @search_results = EBSCO::EDS::Results.new(empty_results,@config)
    else
      _response = do_request(:post, path: '/edsapi/rest/Search', payload: @search_options)
      @search_results = EBSCO::EDS::Results.new(_response, @config,
                                                @info.available_limiters, options)
      if increment_page
        @current_page = @search_results.page_number
      end
      @search_results
    end
  else
    # Only perform a search when there are query terms since certain EDS profiles will throw errors when
    # given empty queries
    if (options.keys & %w[query q]).any? || options.has_key?(:query)
      # create/recreate the search options if nil or not passing actions
      if @search_options.nil? || !add_actions
        @search_options = EBSCO::EDS::Options.new(options, @info)
      end
      _response = do_request(:post, path: '/edsapi/rest/Search', payload: @search_options)
      @search_results = EBSCO::EDS::Results.new(_response, @config,
                                                @info.available_limiters, options)
      if @search_results.stat_total_hits.to_i == 0 && @config[:smarttext_failover] == true
        @search_options.add_actions('SetSearchMode(smart)', @info)
        _response = do_request(:post, path: '/edsapi/rest/Search', payload: @search_options)
        @search_results = EBSCO::EDS::Results.new(_response, @config,
                                                @info.available_limiters, options, true)
      end
      # create temp format facet results if needed
      if options['f']
        if options['f'].key?('eds_publication_type_facet')
          format_options = options.dup
          format_options['f'] = options['f'].except('eds_publication_type_facet')
          format_search_options = EBSCO::EDS::Options.new(format_options, @info)
          format_search_options.Comment = 'temp source type facets'
          _format_response = do_request(:post, path: '/edsapi/rest/Search', payload: format_search_options)
          @search_results.temp_format_facet_results = EBSCO::EDS::Results.new(_format_response,
                                                                              @config,
                                                                              @info.available_limiters,
                                                                              format_options)
        end
      end

      # create temp content provider facet results if needed
      if options['f']
        if options['f'].key?('eds_content_provider_facet')
          content_options = options.dup
          content_options['f'] = options['f'].except('eds_content_provider_facet')
          content_search_options = EBSCO::EDS::Options.new(content_options, @info)
          content_search_options.Comment = 'temp content provider facet'
          _content_response = do_request(:post, path: '/edsapi/rest/Search', payload: content_search_options)
          @search_results.temp_content_provider_facet_results = EBSCO::EDS::Results.new(_content_response,
                                                                                        @config,
                                                                                        @info.available_limiters,
                                                                                        content_options)
        end
      end

      if increment_page
        @current_page = @search_results.page_number
      end
      @search_results
    else
      @search_results = EBSCO::EDS::Results.new(empty_results, @config)
    end
  end
end

#set_highlight(val) ⇒ Object

:category: Setter Methods Sets whether or not to turn highlighting on or off (y|n). Returns search Results.

Examples

results = session.set_highlight('n')



588
589
590
 
# File 'lib/ebsco/eds/session.rb', line 588

def set_highlight(val)
  add_actions "SetHighlight(#{val})"
end

#set_include_facets(val) ⇒ Object

:category: Setter Methods Specify to include facets in the results or not. Either ‘y’ or ‘n’. Returns search Results.

Examples

results = session.set_include_facets('n')



621
622
623
 
# File 'lib/ebsco/eds/session.rb', line 621

def set_include_facets(val)
  add_actions "SetIncludeFacets(#{val})"
end

#set_search_mode(mode) ⇒ Object

:category: Setter Methods Sets the search mode. The available search modes are returned from the info method. Returns search Results.

Examples

results = session.set_search_mode('bool')



570
571
572
 
# File 'lib/ebsco/eds/session.rb', line 570

def set_search_mode(mode)
  add_actions "SetSearchMode(#{mode})"
end

#set_sort(val) ⇒ Object

:category: Setter Methods Sets the sort for the search. The available sorts for the specified databases can be obtained from the session’s info attribute. Sets the page number back to 1. Returns search Results.

Examples

results = session.set_sort('newest')



561
562
563
 
# File 'lib/ebsco/eds/session.rb', line 561

def set_sort(val)
  add_actions "SetSort(#{val})"
end

#set_view(view) ⇒ Object

:category: Setter Methods Specifies the view parameter. The view representes the amount of data to return with the search. Returns search Results.

Examples

results = session.set_view('detailed')



579
580
581
 
# File 'lib/ebsco/eds/session.rb', line 579

def set_view(view)
  add_actions "SetView(#{view})"
end

#simple_search(query) ⇒ Object

:category: Search & Retrieve Methods Performs a simple search. All other search options assume default values.

Returns search Results.

Attributes

  • query - the search query.

Examples

results = session.simple_search('volcanoes')



308
309
310
 
# File 'lib/ebsco/eds/session.rb', line 308

def simple_search(query)
  search({:query => query})
end

#solr_retrieve_list(list: [], highlight: nil) ⇒ Object 



481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/ebsco/eds/session.rb', line 481

def solr_retrieve_list(list: [], highlight: nil)
  records = []
  if list.any?
    list.each.with_index(1) { |id, index|
      dbid = id.split('__',2).first
      accession = id.split('__',2).last
      begin
        current_rec = retrieve(dbid: dbid, an: accession, highlight: highlight, ebook: @config[:ebook_preferred_format])
        current_rec.eds_result_id = index
        records.push current_rec
      rescue EBSCO::EDS::BadRequest, EBSCO::EDS::NotFound => e
        puts "Request for #{id} in #{self.class.name}#solr_retrieve_list failed with #{e}" if @debug
      end
    }
  end
  r = empty_results(records.length)
  results = EBSCO::EDS::Results.new(r, @config)
  results.records = records
  results.to_solr
end

#solr_retrieve_previous_next(options = {}) ⇒ Object

Create a result set with just the record before and after the current detailed record



414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/ebsco/eds/session.rb', line 414

def solr_retrieve_previous_next(options = {})

  rid = options['previous-next-index']

  # set defaults if missing
  if options['page'].nil?
    options['page'] = '1'
  end
  if options['per_page'].nil?
    options['per_page'] = '20'
  end

  rpp = options['per_page'].to_i

  # determine result page and update options
  goto_page = rid / rpp
  if (rid % rpp) > 0
    goto_page += 1
  end
  options['page'] = goto_page.to_s
  pnum = options['page'].to_i

  max = rpp * pnum
  min = max - rpp + 1
  result_index = rid - min
  cached_results = search(options, false, false)
  cached_results_found = cached_results.stat_total_hits

  # last result in set, get next result
  if rid == max
    options_next = options
    options_next['page'] = cached_results.page_number+1
    next_result_set = search(options_next, false, false)
    result_next = next_result_set.records.first
  else
    unless rid == cached_results_found
      result_next = cached_results.records[result_index+1]
    end
  end

  if result_index == 0
    # first result in set that's not the very first result, get previous result
    if rid != 1
      options_previous = options
      options_previous['page'] = cached_results.page_number-1
      previous_result_set = search(options_previous, false, false)
      result_prev = previous_result_set.records.last
    end
  else
    result_prev = cached_results.records[result_index-1]
  end

  # return json result set with just the previous and next records in it
  r = empty_results(cached_results.stat_total_hits)
  results = EBSCO::EDS::Results.new(r, @config)
  next_previous_records = []
  unless result_prev.nil?
    next_previous_records << result_prev
  end
  unless result_next.nil?
    next_previous_records << result_next
  end
  results.records = next_previous_records
  results.to_solr

end