Add to folio/okapi gem: method for getting HRID given barcode

[ndushay]

@lwrubel commented on Mon Feb 06 2023

For some registration-related workflows, we have a barcode and need to look up an HRID for the parent instance.

Barcodes live in item records. The [/inventory/items API] is what libsys recommends using for querying inventory by a field. FOLIO API docs for inventory/items queries

An example query param: query=barcode==36105132232385

Presumably there is only one item record for a barcode. The item record has an HRID in the the hrid field in the single item initems array. Example:

{'items': [{'id': 'e5140df0-3f48-5f95-9d58-92d1f5d998a0',
   '_version': '1',
   'status': {'name': 'Available', 'date': '2022-11-19T11:55:32.020+00:00'},
   'administrativeNotes': [],
   'title': '"A tender age" : cultural anxieties over the child in the twelfth and thirteenth centuries / William F. Maclehose.',
   'callNumber': 'HQ792 .E8 M33 2008',
   'hrid': 'ai7839423_1_1',
   'contributorNames': [{'name': 'MacLehose, William F'}],
   'formerIds': [],
   'discoverySuppress': None,
   'holdingsRecordId': '19cd22f5-98e9-5d25-99fe-dbd8734daa8b',
   'barcode': '36105132232385',
   'notes': [{'itemNoteTypeId': 'e9f6de86-e564-4095-a61a-38c9e0e6b2fc',
     'note': 'EDI receipt',
     'staffOnly': True}],
   'circulationNotes': [],
   'tags': {'tagList': []},
   'yearCaption': [],
   'electronicAccess': [],
   'statisticalCodeIds': [],
   'purchaseOrderLineIdentifier': None,
   'materialType': {'id': '1a54b431-2e4f-452d-9cae-9cee66c9a892',
    'name': 'book'},
   'permanentLoanType': {'id': '2b94c631-fca9-4892-a730-03ee529ffe27',
    'name': 'Can circulate'},
   'permanentLocation': {'id': '4573e824-9273-4f13-972f-cff7bf504217',
    'name': 'Green Stacks'},
   'metadata': {'createdDate': '2022-11-19T12:08:04.292+00:00',
    'createdByUserId': '7c0a8571-e809-4fc5-9d14-69414d23c841',
    'updatedDate': '2022-11-19T12:08:04.292+00:00',
    'updatedByUserId': '7c0a8571-e809-4fc5-9d14-69414d23c841'},
   'links': {'self': 'http://okapi-test.stanford.edu/inventory/items/e5140df0-3f48-5f95-9d58-92d1f5d998a0'},
   'effectiveCallNumberComponents': {'callNumber': 'HQ792 .E8 M33 2008',
    'prefix': None,
    'suffix': None,
    'typeId': '95467209-6d7b-468b-94df-0f5d7ad2747d'},
   'effectiveShelvingOrder': 'HQ 3792 E8 M33 42008',
   'isBoundWith': False,
   'effectiveLocation': {'id': '4573e824-9273-4f13-972f-cff7bf504217',
    'name': 'Green Stacks'}}],
 'totalRecords': 1}

The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

---

@peetucket commented on Mon Feb 13 2023

I assume we can move this issue to the folio_client repo?

[peetucket]

Can someone say more about this statement and what it means for implementation?

The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

At the moment, I have code working that parses the returned JSON for a given barcode query and returns the value in the hrid field of the single element items array as noted.

[ndushay]

Can someone say more about this statement and what it means for implementation?

The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

At the moment, I have code working that parses the returned JSON for a given barcode query and returns the value in the hrid field of the single element items array as noted.

Does the item hrid field value look like a1341324_1_1 ? what we want is a1341324 as the result, as that will be the Folio INSTANCE hrid. What you may be seeing is the Folio ITEM hrid :-P

[peetucket]

1. The random example record I pulled from okapi-test.stanford.edu didn't have the suffix, but I can strip if present. I just looked for barcode "123456" and it returned "it00000000002" in the referenced field, which i then changed to "in00000000002" in the response.
2. I am also changing any ai prefix to a and any it prefix to in (they seem mutually exclusive, so need for logic around knowing if we are post migration or not)?

^^^ note: updated my comment after looking through the code

[ndushay]

hrmm -ask in folio slack channel -- share query being used and that we're hoping for instance HRID

[ndushay]

Peter, I suspect "it" as the prefix means "item"; perhaps there's an easy extrapolation to the instance HRID, but perhaps there isn't.

It would be great if you could look up a barcode we have in SDR, for which we have a known ckey already, in addition to a barcode natively added to Folio.

@lwrubel have any insights about identifier returned?

[ndushay]

aha: For records created natively in folio: "The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

For migrated records, I see in Laura's example output above 'hrid': 'ai7839423_1_1', -- this would become `a7839423' for the Folio instance record.

[shelleydoljack]

aha: For records created natively in folio: "The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

This is incorrect. The instance/holding/item HRID numbers are separate and do not correspond to each other, i.e. an instance could have one holding and multiple items and each item would increase this HRID by one. They are more like accession numbers, in a sense.

The _n_n suffix is created by the tools we use to migrate data since we don't really have a holdings HRID or item HRID coming out of Symphony.

It would be better to query barcode at /search/instances?query=(items.barcode=36105049264422) and take the id returned and send a request to /inventory/instances/15065378-03ee-5fdf-b21f-ca4170e64b57 to get the instance hrid.

[lwrubel]

Thanks for giving us a better API endpoint for looking up a barcode, @shelleydoljack. @peetucket, when I do a query to the /search/instances? endpoint like the example above, the response I get looks like below.

{'totalRecords': 1,
 'instances': [{'id': '15065378-03ee-5fdf-b21f-ca4170e64b57',
   'title': 'Conversational Spanish for beginners : [by] Gregory G. La Grone.',
   'contributors': [{'name': 'LaGrone, Gregory G. (Gregory Gough), 1912-1983',
     'contributorTypeId': '9f0a2cf0-7a9b-45a2-a403-f68d2850d07c',
     'contributorNameTypeId': '2b94c631-fca9-4892-a730-03ee529ffe2a',
     'primary': True}],
   'publication': [{'publisher': 'H. Holt', 'dateOfPublication': '[1944]'}],
   'staffSuppress': False,
   'discoverySuppress': False,
   'isBoundWith': False,
   'electronicAccess': [],
   'notes': [],
   'items': [{'effectiveCallNumberComponents': {'callNumber': 'TX 465.2 .L179'},
     'effectiveShelvingOrder': 'TX 3465.2 L179 11',
     'notes': []}],
   'holdings': []}]}

And then the instance lookup using /inventory/instances/{uuid} looks like this:

{'id': '15065378-03ee-5fdf-b21f-ca4170e64b57',
 '_version': '1',
 'hrid': 'a5617360',
 'source': 'MARC',
 'title': 'Conversational Spanish for beginners : [by] Gregory G. La Grone.',
 'administrativeNotes': ['Identifier(s) from previous system: a5617360'],
 'indexTitle': 'Conversational spanish for beginners : [by] gregory g. la grone.',
 'parentInstances': [],
 'childInstances': [],
 'isBoundWith': False,
 'alternativeTitles': [],
 'editions': [],
 'series': [],
 'identifiers': [{'identifierTypeId': 'c858e4f2-2b6b-4385-842b-60732ee14abb',
   'value': '44003749'},
  {'identifierTypeId': '7e591197-f335-4afb-bc6d-a6d76ca3bace',
   'value': '(OCoLC-M)1082020'},
  {'identifierTypeId': '7e591197-f335-4afb-bc6d-a6d76ca3bace',
   'value': '(OCoLC-I)275796609'},
  {'identifierTypeId': '439bfbae-75bc-4f74-9fc7-b2a2d47ce3ef',
   'value': 'ocm01082020'}],
 'contributors': [{'contributorNameTypeId': '2b94c631-fca9-4892-a730-03ee529ffe2a',
   'name': 'LaGrone, Gregory G. (Gregory Gough), 1912-1983',
   'contributorTypeId': '9f0a2cf0-7a9b-45a2-a403-f68d2850d07c',
   'contributorTypeText': 'Contributor',
   'authorityId': None,
   'primary': True}],
 'subjects': ['Spanish language Conversation and phrase books',
  'Spanish language Grammar'],
 'classifications': [{'classificationNumber': 'PC4121 .L3',
   'classificationTypeId': 'ce176ace-a53e-4b4d-aa89-725ed7b2edac'},
  {'classificationNumber': '468.242',
   'classificationTypeId': '42471af9-7d25-4f3a-bf78-60d29dcf463b'}],
 'publication': [{'publisher': 'H. Holt',
   'place': 'New York',
   'dateOfPublication': '[1944]',
   'role': None}],
 'publicationFrequency': [],
 'publicationRange': [],
 'electronicAccess': [],
 'instanceTypeId': '30fffe0e-e985-4144-b2e2-1e8179bdb41f',
 'instanceFormatIds': [],
 'physicalDescriptions': ['viii, 219, lv p. ; 20 cm.'],
 'languages': ['spa', 'eng'],
 'notes': [{'instanceNoteTypeId': '6a2533a7-4de2-4e64-8466-074c2fa9308c',
   'note': 'Maps on lining-papers',
   'staffOnly': False},
  {'instanceNoteTypeId': 'fcf323dc-96d1-49a4-ae80-a9033a059cf9',
   'note': 'Cubberley textbook collection',
   'staffOnly': False}],
 'modeOfIssuanceId': '9d18a02f-5897-4c31-9106-c9abb5c7ae8b',
 'catalogedDate': '2004-04-29',
 'previouslyHeld': False,
 'staffSuppress': False,
 'discoverySuppress': False,
 'statisticalCodeIds': [],
 'statusUpdatedDate': '2023-02-11T23:43:13.876+0000',
 'metadata': {'createdDate': '2023-02-11T23:43:13.916+00:00',
  'createdByUserId': '3e2ed889-52f2-45ce-8a30-8767266f07d2',
  'updatedDate': '2023-02-11T23:43:13.916+00:00',
  'updatedByUserId': '3e2ed889-52f2-45ce-8a30-8767266f07d2'},
 'tags': {'tagList': []},
 'natureOfContentTermIds': [],
 'publicationPeriod': {'start': 1944},
 'precedingTitles': [],
 'succeedingTitles': []}

[peetucket]

1. So in the example posted above by Laura, the resulting hrid would be a5617360 ?
2. So does this mean that once I retrieve the hrid via the two queries as noted above, there is no need to strip suffixes and/or change prefixes like this?

   The parent instance HRID is not in the item record, but can be derived by stripping the _n_n suffix on the item record HRID and changing the ai prefix to a. For records created post-migration, we would change the prefix from it to in.

[shelleydoljack]

Yes, the instance HRID is a5617360.

Yes? Are you stripping prefixes? I would advise against that since the prefix is there to avoid collision with the other HRIDs in the system (Lanes' HRIDs and post-migration FOLIO assigned HRIDs).

[peetucket]

I was referencing the end part of the original ticket description, which is likely no longer relevant given this new way of looking of hrids. Just want to verify this for the implementation.

[lwrubel]

Belatedly confirming that since this is now implemented with a /search/instances query and looking up the instance HRID by its UUID there's no need to strip anything from any identifiers.