Class: FolioClient::Inventory

Inherits:
Object
  • Object
show all
Defined in:
lib/folio_client/inventory.rb

Overview

Lookup items in the Folio inventory

Instance Method Summary collapse

Instance Method Details

#create_holdings(holdings_record:) ⇒ Hash

Post a new holdings record

Parameters:

  • holdings_record (Hash) —

    holdings record

Returns:

  • (Hash) —

    the created holdings record, including its id and other fields

Raises:

  • (ArgumentError)

See Also:



101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/folio_client/inventory.rb', line 101

def create_holdings(holdings_record:)
  required = %w[instance_id permanent_location_id source_id holdings_type_id]
  missing = required.select { |field| !holdings_record.key?(field) || holdings_record[field].blank? }
  raise ArgumentError, "Missing required fields: #{missing.join(', ')}" if missing.any?

  client.post('/holdings-storage/holdings', {
                instanceId: holdings_record['instance_id'],
                permanentLocationId: holdings_record['permanent_location_id'],
                sourceId: holdings_record['source_id'],
                holdingsTypeId: holdings_record['holdings_type_id'],
                discoverySuppress: false
              })
end

#fetch_external_id(hrid:) ⇒ String?

get instance external ID from HRID

Parameters:

  • hrid (String) —

    instance HRID

Returns:

  • (String, nil) —

    instance external ID if present, otherwise nil.

Raises:



25
26
27
28
29
30
31
32
 
# File 'lib/folio_client/inventory.rb', line 25

def fetch_external_id(hrid:)
  instance_response = client.get('/search/instances', { query: "hrid==#{hrid}" })
  record_count = instance_response['totalRecords']
  raise ResourceNotFound, "No matching instance found for #{hrid}" if instance_response['totalRecords'].zero?
  raise MultipleResourcesFound, "Expected 1 record for #{hrid}, but found #{record_count}" if record_count > 1

  instance_response.dig('instances', 0, 'id')
end

#fetch_holdings(hrid:) ⇒ Array<Hash>

Get holdings records for an instance by HRID

Parameters:

  • hrid (String) —

    instance HRID

Returns:

  • (Array<Hash>) —

    array of holdings records with permanentLocationId, _version, discoverySuppress, and other fields

See Also:



79
80
81
82
83
84
 
# File 'lib/folio_client/inventory.rb', line 79

def fetch_holdings(hrid:)
  instance_uuid = fetch_external_id(hrid: hrid)
  instance_response = client.get('/inventory-view/instances', { query: "id==#{instance_uuid}" })

  instance_response.dig('instances', 0, 'holdingsRecords') || []
end

#fetch_hrid(barcode:) ⇒ String?

get instance HRID from barcode

Parameters:

  • barcode (String) —

    barcode

Returns:

  • (String, nil) —

    instance HRID if present, otherwise nil.



9
10
11
12
13
14
15
16
17
18
19
 
# File 'lib/folio_client/inventory.rb', line 9

def fetch_hrid(barcode:)
  # find the instance UUID for this barcode
  instance = client.get('/search/instances', { query: "items.barcode==#{barcode}" })
  instance_uuid = instance.dig('instances', 0, 'id')

  return nil unless instance_uuid

  # next lookup the instance given the instance_uuid so we can fetch the hrid
  result = client.get("/inventory/instances/#{instance_uuid}")
  result['hrid']
end

#fetch_instance_info(external_id: nil, hrid: nil) ⇒ Hash

Retrieve basic information about a instance record. Example usage: get the external ID and _version for update using

optimistic locking when the HRID is available: `fetch_instance_info(hrid: 'a1234').slice('id', '_version')`
(or vice versa if the external ID is available).

Parameters:

  • external_id (String) (defaults to: nil) —

    an external ID for the desired instance record

  • hrid (String) (defaults to: nil) —

    an instance HRID for the desired instance record

Returns:

  • (Hash) —

    information about the record.

Raises:

  • (ArgumentError) —

    if the caller does not provide exactly one of external_id or hrid



41
42
43
44
45
46
47
 
# File 'lib/folio_client/inventory.rb', line 41

def fetch_instance_info(external_id: nil, hrid: nil)
  raise ArgumentError, 'must pass exactly one of external_id or HRID' unless external_id.present? || hrid.present?
  raise ArgumentError, 'must pass exactly one of external_id or HRID' if external_id.present? && hrid.present?

  external_id ||= fetch_external_id(hrid: hrid)
  client.get("/inventory/instances/#{external_id}")
end

#fetch_location(location_id:) ⇒ Hash

Get location details by UUID

Parameters:

  • location_id (String) —

    UUID of the location

Returns:

  • (Hash) —

    location data including campusId and other location information

Raises:



71
72
73
 
# File 'lib/folio_client/inventory.rb', line 71

def fetch_location(location_id:)
  client.get("/locations/#{location_id}")
end

#has_instance_status?(hrid:, status_id:) ⇒ Boolean

Returns true if instance status matches the uuid param, false otherwise.

Parameters:

  • hrid (String) —

    instance HRID

  • status_id (String) —

    uuid for an instance status code

Returns:

  • (Boolean) —

    true if instance status matches the uuid param, false otherwise

Raises:



53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/folio_client/inventory.rb', line 53

def has_instance_status?(hrid:, status_id:) # rubocop:disable Naming/PredicatePrefix
  # get the instance record and its statusId
  instance = client.get('/inventory/instances', { query: "hrid==#{hrid}" })
  raise ResourceNotFound, "No matching instance found for #{hrid}" if instance['totalRecords'].zero?

  instance_status_id = instance.dig('instances', 0, 'statusId')

  return false unless instance_status_id

  return true if instance_status_id == status_id

  false
end

#update_holdings(holdings_id:, holdings_record:) ⇒ Object

Put an updated holdings record

Parameters:

  • holdings_id (String) —

    UUID of the holdings record to update

  • holdings_record (Hash) —

    holdings record

Raises:

See Also:



93
94
95
 
# File 'lib/folio_client/inventory.rb', line 93

def update_holdings(holdings_id:, holdings_record:)
  client.put("/inventory/holdings/#{holdings_id}", holdings_record, exception_subject: "holdings record with ID #{holdings_id}")
end