Creating and managing a consortium directory entry

Create or update a directory entry for your resource sharing consortium. In order to talk to other lenders and borrowers, it is necessary to have a directory entry that describes your resource sharing consortium. This entry needs to be available for the ReShare directory to fetch via an HTTP request.

Note: If your ReShare system is hosted by a service provider, the service provider will create the directory entry that represents your consortia as part of your implementation.

An example consortium entry may look like this:

{
  "name":"Cardinal test Consortium",
  "slug":"CARDINAL",
  "foafUrl":"https://raw.githubusercontent.com/openlibraryenvironment/mod-directory/master/seed_data/test/cardinal_local_management.json",
  "url":"http://not.a.real.consortium/",
  "type":"Consortium",
  "members":[
    { "memberOrg":"us-east-1"},
    { "memberOrg":"us-west-1"}
  ],
  "friends":[
    { "foaf": "https://east-okapi.folio-dev.indexdata.com/_/invoke/tenant/reshare_east/directory/externalApi/entry/us-east-1" },
    { "foaf": "https://west-okapi.folio-dev.indexdata.com/_/invoke/tenant/reshare_west/directory/externalApi/entry/us-west-1" }
  ]
}

This example describes a consortium identified by the slug “CARDINAL”. The foafUrl entry is a URL where this config can be fetched. The members of this consortium are identified by the slugs “us-east-1”, and “us-east-2”. The friends section shows where mod-directory can fetch the root directory entries for each consortium member. The format for the friends url is okapiurl + “/_/invoke/tenant/” + your tenant id + “/directory/externalApi/entry/” + slug.

Use an http client like curl, httpie, or postman to add the consortium entry to mod-directory. This example uses curl. Assuming the okapi Url is https://reshare-okapi.example.edu, and the consortium directory entry is available at https://reshare.example.edu/consortium.json

Log in to the ReShare tenant with the tenant admin account

curl -w '\n' -X POST  \
  -H "Content-type: application/json" \
  -H "X-Okapi-Tenant:resharetenant" \
  -d'{ "username":"username","password":"password" }' \
   https://reshare-okapi.example.edu/authn/login

The response will contain a header called “x-okapi-token”, save that token, and set it as an environment variable for convenience:

export TOKEN="returned value of x-okapi-token"

Add the consortium directory entry to mod-directory

urlencode the url of your consortium config. This is the “foafUrl” field on the top level of the config. Use an online urlencoder or a command line tool. In this case https://reshare.example.edu/consortium.json becomes https%3A%2F%2Freshare.example.edu%2Fconsortium.json. Now issue the following HTTP request to get mod-directory to pick up your consortium entry:

Note the header including the $TOKEN value requested in the previous step. This is necessary to authenticate the request.

ReShare should respond with “OK” after this request is issued. Check the mod-directory UI to confirm that the ReShare tenant now shows directory entries for all members of the consortium. mod-directory will crawl the entries in the consirtium every 24 hours to pick up any changes to each institution’s directory entry.