folio.drew.edu | api notes | Rapido

create a rapido user

give rapido a few permissions

get an Okapi token

re NCIP

re OAI-PMH

re RTAC

create a rapido user

in the Users app go to Actions, New to create a user with the username: rapido - e.g. 

{
	"username":"rapido",
	"id":"0a698533-1591-48ad-a707-6fdbdc3bde92",
	"active":true,
	"patronGroup":"04987207-2f1a-4900-b98e-1145de874ee9",
	"departments":[],
	"proxyFor":[],
	"personal":{
		"lastName":"rapido",
		"firstName":"",
		"email":"Moshe.Shechter@clarivate.com",
		"addresses":[],
		"preferredContactTypeId":"002"
	},
	"createdDate":"2023-08-10T19:45:07.939+00:00",
	"updatedDate":"2023-08-10T19:45:07.939+00:00",
	"metadata":{
		"createdDate":"2023-08-10T19:45:07.920+00:00",
		"createdByUserId":"308a01e4-1108-4ea3-aa25-8b1b32cf7643",
		"updatedDate":"2023-08-10T19:45:07.920+00:00",
		"updatedByUserId":"308a01e4-1108-4ea3-aa25-8b1b32cf7643"
	}
}

then go to Settings:Developer:Passwd in the UI to give the rapido user a password

give rapido a few permissions

for NCIP

  • ncip.all
  • inventory-storage.items.collection.get
  • ui-circulation.settings.overdue-fines-policies
  • ui-circulation.settings.lost-item-fees-policies
  • automated-patron-blocks.collection.get
  • circulation-storage.circulation-rules.get
  • manualblocks.collection.get
  • ncip.post - found this, in addition to ncip.all, in github.com/folio-org/mod-ncip/blob/master/descriptors/ModuleDescriptor-template.json and so added it but acceptItem is still not working for me

for OAI-PMH
  • oai-pmh.records.collection.get

for RTAC
  • rtac.holdings.item.get

get an Okapi token

every API call requires an X-Okapi-Token which is specific to a particular username within your tenant
to get a token POST to /authn/login* like so: 

curl -i -s -X POST -H 'Content-type: application/json' -H 'X-Okapi-Tenant: $tenantId' -d '{"username":"$username", "password":"$password"}' $yourFOLIOurl/authn/login
curl will return something that looks like this 
HTTP/2 201
date: Mon, 02 Oct 2023 20:03:54 GMT
content-type: application/json
server: nginx
x-okapi-token: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhcGlhZG1pbiIsInR5cGUiOiJsZWdhY3ktYWNjZXNzIiwidXNlcl9pZCI6IjdiMjcwMDY5LTY...
refreshtoken: eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..ikmWU6th2ks8Hpkz.hBwnR8ajz5iY7-6UiVZA3N1Y-MTgJnx0Lf4AUn87Yxh3WRO...

{
  "okapiToken" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhcGlhZG1pbiIsInR5cGUiOiJsZWdhY3ktYWNjZXNzIiwidXNlcl9pZCI6IjdiMjcwMDY5LTY...",
  "refreshToken" : "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..ikmWU6th2ks8Hpkz.hBwnR8ajz5iY7-6UiVZA3N1Y-MTgJnx0Lf4AUn87Yxh3WRO..."
}
I use this Perl script, get-okapi-token.pl, to parse the token out of the above response and save to use whenever I need it.
You'll have to update the token the next time your FOLIO is updated.
* this is going to change with the release of Poppy

re the Edge APIs: I haven't figured out how to get the relevant token :(
if/when I do it will be interesting to see if the Edge endpoints are a better solution for whatever reason

re NCIP

relevant documentation includes...

  • wiki.folio.org/display/FOLIOtips/NCIP
  • github.com/folio-org/mod-ncip/blob/master/README.md
    section 3 under Preparation offers a list of "configurations you will need to establish values for in FOLIO" - here is what I did in that regard
    • (1) instance.type.name (Settings > Inventory > Instances > Resource Type)
      I created a resource type: rapido (it is the instanceTypeId, the resource type's UUID, that the instance requires - I should think that you could just use the resource type "text" if you wanted to)
    • (2) instance.source
      While an instance does require a value in the source field there is not a relevant list in Settings > Inventory > Instances, so, nothing to do here
    • (3) item.material.type.name
      I created a material type: rapido (it is the materialTypeId, the material type's UUID, that the item requires - I should think that you could just use the material type "book" if you wanted to)
    • (4) item.perm.loan.type.name
      I created a loan type: rapido (it is the permanentLoanTypeId, the loan type's UUID, that the item requires - I should think that you could just use an existing loan type, such as our "can circulate," if you wanted to)
    • (5) item.status.name
      An item's status is one of several terms that come from an enumerated list and is not something that can be added to or removed from and includes "Aged to lost", "Available", "Awaiting pickup", "Awaiting delivery", "Checked out", "Claimed returned", "Declared lost", "In process", "In process (non-requestable)", "In transit", "Intellectual item", "Long missing", "Lost and paid", "Missing", "On order", "Paged", "Restricted", "Order closed", "Unavailable", "Unknown", and "Withdrawn" - nothing to do here
    • (6) item.perm.location.code
      Note that while an item may be assigned a permanentLocation and a tempraryLocation these are not required fields - the location belongs in the holdingsRecord - if NCIP want to put a location in the item record we will use the already existing ILL location
    • (7) holdings.perm.location.code
      We will use the already existing ILL location
    • (8) instance.custom.identifier.name (Settings -> Inventory -> Instances -> Resource Identifier Types)
      I created a new one: Rapido Request ID
    • (9) checkout.service.point.code
      (Settings -> Tenant -> Service points) - we'll use the already existing ILL service point
    • (10) checkin.service.point.code
      ditto
    mod-configuration setup describes both required and optional configurations all of which correspond to the above list - each of the following /configurations/entries includes a configName (Rapido) which corresponds to the AgencyId in the NCIP request's XML:
    • {
         "id" : "1efc115a-54db-4b1e-9a50-a4635db3cf62",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "instance.type.name",
         "default" : true,
         "enabled" : true,
         "value" : "rapido"
      }
    • {
         "id" : "8a59cdfe-d2fb-4a04-a52b-4dd2c50cb19f",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "instance.source",
         "default" : true,
         "enabled" : true,
         "value" : "rapido"
      }
    • {
         "id" : "cd3adb4d-a581-46c8-81c2-c566db1f13a9",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "item.material.type.name",
         "default" : true,
         "enabled" : true,
         "value" : "rapido"
      }
    • {
         "id" : "fca487a5-373a-4719-a6ce-4446a3fc0594",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "item.perm.loan.type.name",
         "default" : true,
         "enabled" : true,
         "value" : "rapido"
      }
    • {
         "id" : "d4bd820e-52df-432c-a197-fb1418949be2",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "item.status.name",
         "default" : true,
         "enabled" : true,
         "value" : "Available"
      }
    • {
         "id" : "bd22cf2f-2cf4-417c-b8ad-5fc19aa8cf31",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "item.perm.location.code",
         "default" : true,
         "enabled" : true,
         "value" : "LO1"
      }
    • {
         "id" : "e4256230-9994-47f9-ad69-be3a86f48439",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "holdings.perm.location.code",
         "default" : true,
         "enabled" : true,
         "value" : "LO1"
      }
    • {
         "id" : "d3dcb5a1-1010-451c-b3c6-9aa9873f2706",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "instance.custom.identifier.name",
         "default" : true,
         "enabled" : true,
         "value" : "Rapido Request ID"
      }
    • {
         "id" : "168d476f-a15b-4c18-aadc-e54d788b83bb",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "checkout.service.point.code",
         "default" : true,
         "enabled" : true,
         "value" : "ILL"
      }
    • {
         "id" : "55e9093d-1523-4d66-8699-36065e3386d9",
         "module" : "NCIP",
         "configName" : "Rapido",
         "code" : "checkin.service.point.code",
         "default" : true,
         "enabled" : true,
         "value" : "ILL"
      }

    After accomplishing all of the above GET /ncipconfigcheck returned OK = w00t

    Also, POSTing a LookupUser request to /ncip returns the proper response - also w00t

    After copying the sample AcceptItem request from Basecamp I only got error messages :(

    After copying the sample AcceptItem request at FOLIO-NCIP Services: Getting Started Guide and changing all of the AgencyIds to Rapido and changing the UseridentifierValue to my barcode I enjoyed the following response... 

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns1:NCIPMessage xmlns:ns1="http://www.niso.org/2008/ncip" ns1:version="http://www.niso.org/schemas/ncip/v2_0/imp1/xsd/ncip_v2_0.xsd">
   <ns1:AcceptItemResponse>
      <ns1:RequestId>
         <ns1:AgencyId>Rapido</ns1:AgencyId>
         <ns1:RequestIdentifierType ns1:Scheme="Scheme">Request Id</ns1:RequestIdentifierType>
         <ns1:RequestIdentifierValue>a047850f-adce-48c1-84bb-fcb255baffc1</ns1:RequestIdentifierValue>
      </ns1:RequestId>
      <ns1:ItemId>
         <ns1:AgencyId>Rapido</ns1:AgencyId>
         <ns1:ItemIdentifierType ns1:Scheme="Scheme">Item Barcode</ns1:ItemIdentifierType>
         <ns1:ItemIdentifierValue>LEH-202003231237</ns1:ItemIdentifierValue>
      </ns1:ItemId>
   </ns1:AcceptItemResponse>
</ns1:NCIPMessage>
    ...and am able to find the relevant request under my name in the FOLIO UI:

    this is extremely w00t

    So, why didn't the first example work? I don't know. Please see re AcceptItem XML

re OAI-PMH

after adding the required permission (oai-pmh.records.collection.get) to the Rapido user I was able to... 

curl -X GET -G $headers -d 'metadataPrefix=oai_dc' $baseURL/oai/records?verb=ListRecords
...which returns a bunch of these: 
<record>
<header>
<identifier>oai:folio.org:fs00001020/7588f2e0-3f99-4a92-820e-e9c30a75728a</identifier>
<datestamp>2023-06-30T03:11:35Z</datestamp>
<setSpec>all</setSpec>
</header>
<metadata>
<oai_dc:dc>
<dc:title>Deleuze and Guattari /</dc:title>
<dc:creator>Bogue, Ronald,1948-</dc:creator>
<dc:type>text</dc:type>
<dc:language>eng</dc:language>
<dc:description>Bibliography: pages 180-190.</dc:description>
<dc:description>Includes index.</dc:description>
<dc:subject>Deleuze, Gilles,1925-1995.</dc:subject>
<dc:subject>Guattari, Félix,1930-1992.</dc:subject>
<dc:subject>Literature, Modern</dc:subject>
<dc:subject>Criticism.</dc:subject>
<dc:subject>Philosophy, Modern</dc:subject>
<dc:subject>Psychoanalysis and literature.</dc:subject>
<dc:subject>Deconstruction.</dc:subject>
<dc:subject>Structuralism (Literary analysis)</dc:subject>
<dc:identifier>URN:ISBN:0415020174</dc:identifier>
<dc:identifier>URN:ISBN:0415024439</dc:identifier>
<dc:rights>discovery not suppressed</dc:rights>
</oai_dc:dc>
</metadata>
</record>

this page on the wiki indicates that sets are not currently supported :(

using the metadataPrefix marc21_withholdings will provide 952s (after the 999s at the end of the MARC) which include current item information per FOLIO like so: 

<marc:datafield tag="952" ind1="f" ind2="f">
<marc:subfield code="p">can circulate</marc:subfield>
<marc:subfield code="a">Drew University</marc:subfield>
<marc:subfield code="b">University Library</marc:subfield>
<marc:subfield code="c">Circulating Collection</marc:subfield>
<marc:subfield code="d">Level B</marc:subfield>
<marc:subfield code="t">0</marc:subfield>
<marc:subfield code="e">515.243 H669i</marc:subfield>
<marc:subfield code="h">Dewey</marc:subfield>
<marc:subfield code="i">book</marc:subfield>
<marc:subfield code="m">31144001470144</marc:subfield>
</marc:datafield>

the subfields are:

  • a institution
  • b campus
  • c library
  • d location
  • e call number
  • h class scheme
  • i material type
  • m barcode
  • p loan type
  • t (I have no idea and have not been able to track down a definitive list in FOLIO's documentation)

re RTAC

FOLIO's relevant endpoint, /rtac, requires an instanceId and returns holdings information that incluces the itemId, locationName, callNumber, status, and volume. After giving the Rapido user the relevant permission (rtac.holdings.item.get) the following request... 

curl -X GET $headers $baseURL/rtac/bfed0798-d2bc-4687-8e84-8b589f73ff9c
...enjoyed this response: 
{
  "holdings" : [ {
    "id" : "b9507462-9ebf-45a1-b2d3-f69072d8473c",
    "location" : "Level E",
    "callNumber" : "843 P968aE",
    "status" : "Available",
    "volume" : "(vol.2)"
  }, {
    "id" : "ed5791c0-3bcc-4e39-b35c-1c83a96c1a3a",
    "location" : "Level E",
    "callNumber" : "843 P968aE",
    "status" : "Available",
    "volume" : "(vol.1)"
  } ]
}