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.

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:

curl -sSL -H "X-Okapi-Tenant: resharetenant" \
  -H "X-Okapi-Token: $TOKEN" \
  -H "Content-Type: application/json" -X GET \
  "https://reshare-okapi.example.edu/directory/api/addFriend?friendUrl=https%3A%2F%2Freshare.example.edu%2Fconsortium.json"

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.