Library Answers: Los Rios Common Questions

Get an API Key

Instructions for requesting an OCLC API key (WSKey) can be found at How do I request a WSKey?

You should be able to sign in to WSKey Management using the same credentials you use for WorldShare Record Manager. If not, check your permissions in WorldShare Admin.

When you arrive at WSKey Management - Request a Key:

1. Click Request a custom key
2. Please select Type of Request: Production
3. On the next page, select Machine-to-Machine (M2M) app
4. Select Services: WorldCat Metadata API
5. WSKey Name: WorldCat [your college]
6. What is the reason for this request? something like: "I will be managing various WorldCat activities using Library Open Workflows from Ex Libris."
7. Read any terms and conditions / policies, check the boxes, and click Accept.

The key should be provided to you within a few business days.

Key settings

Once OCLC has created the API key, go to WSKey Management and select the key. You will see that it has a Client ID and a Secret. You will need both of these values for setting things up in LibOW. (It is possible to change these values; if you change them after setting up LibOW, you would need to then make changes in any matching LibOW credentials.)

You can leave Redirect URI and CORS Domain blank; note we might find in the future that these are useful or needed.

Under UseAllowed, we are having success with having the following selected: CCG and Lite. Authorization Code and Authorization Code + PKCE are un-selected. Note this is just reflecting how we are currently set up and we might later decide to change these settings.

Create credentials in LibOW

Currently there is no dedicated OCLC/WorldCat credential type in LibOW. So we use the generic OAuth2 Credential type.

1. Click Create Credential.
2. Type oauth2 and scroll down to the OAuth2 API option (with no words preceding OAuth2).

   

3. Select OAuth2 API and click Continue.
4. Fill in values (note, it's possible that if you use different settings in your key than listed above, some of these might need to change):
   • Grant type: Client Credentials
   • Access Token URL: https://oauth.oclc.org/token
   • Client ID: your ID from the OCLC API key's page in WSKey Management
   • Secret: the Secret from the OCLC API key's page in WSKey Management
   • Scope: WorldCatMetadataAPI

     Note: it is possible to set a more limited scope. Available scopes are listed when you view your WSKey.

   • Authentication: Header
   • Ignore SSL Issues: off / unselected
   • Allowed HTTP Request Domains: All

     Note: it may be desirable to limit these in the future.

5. Click the title at the top to give the credential a distinct name.
6. Click the Save button at the top of the window. Note that some credential types will check that your access works, but this one won't.

The finished credential should look something like this:

Note that while this OAuth2 process requires a token to be stored and periodically refreshed, we don't have to worry about that part. This single credential will automatically store and refresh the token behind the scenes.

Use the credentials in a workflow

Currently, just as there is no dedicated OCLC API credential type in LibOW, there are no dedicated OCLC/WorldCat nodes. Instead we need to use the regular HTTP Request node to make queries.

Check OCLC's API reference for details on what can be done. There are a lot of possibilities! Currently we are unsetting holdings in a worfklow using the "Unset the holding on a Bibliographic record for an institution by OCLC Number" API, documented at the WorldCat Metadata API page. (We are doing this because Ex Libris's built-in OCLC publishing job does not handle withdrawals well in a multi-library Alma.)

Here are the elements for that API specifically. Note, other APIs will require other settings! You need to check the API reference for clues on what is needed.

• Method: POST
• URL: https://metadata.api.oclc.org/worldcat/manage/institution/holdings/{{ $json['OCLC Control Number (035a)'] }}/unset

  Note the expression between holdings/ and /unset comes from the previous node, which retrieved an Analytics report. LibOW evaluates the expression, which outputs an OCLC control number. So what goes in that expression would depend upon how the particular workflow is set up.

• Authentication: Generic Credential Type
• Generic Auth Type: OAuth2 API

  when you select this, you will see any available customized credentials in the next drop-down

• OAuth2 API: [the credential that matches the API key you want to use]
• Send Query Parameters: slide to active
• Query Parameters - Name: oclcNumber
• Query Parameters - Number: [the same expression you used in the URL that evaluates to the OCLC number]
• Send Headers - slide to active
• Specify Headers: using fields below
• Header Parameters - Name: Accept
• Header Parameters - Value: application/json
• Send Body: inactive

I set an option to include the response, Include Response Headers and Status, simply because as I was testing this I found it helpful. But it's probably not necessary.

In the node Settings tab, I set Retry on Fail to 5 max. tries, Wait Between tries set to 5000 ms. Everything else at default.

Here is a screenshot of the node for this workflow: