Editing Resource Web Addresses - Talis Aspire APIs Documentation

Recipes :: Editing Resource Web Addresses

Background

There are cases where you know that the web address on an item needs to be updated. It might need to be a partial update, for example a change of domain name, or it might be that the link needs to be replaced with an entirely new link.

Terminology

Web Address
- A URL on a resource which links out to an external website.
Online Resource
- The view online button is visible to users on the reading list. This online_resource property identifies what has been selected for the student to be directed to, when they click the button. Only one source can be selected at any one time. This could be one of a number of types:
  - doi - DOI
  - openURL - Open URL
  - uri — Web Address
- Where the source is uri there is an additional link property which defines the URL to direct the user to.

Where the URL is stored

First you need to know that resources are stored separately to items and that a resource may be used by many items on different lists.

This topic is covered in more detail in the concepts section.

URLs are stored in the web_addresses field.

Updating the web address

The exact steps you take may include all or some of these steps depending on what you want to achieve.

Important: If you want to replace the web address for the view online button, you must update the web address and the online resource at the same time, as they are different properties. If you do not do this, the view online button may direct students to an incorrect link.

Identify which items you would like to update:
1. You can use the All List Items report from Talis Aspire Reading Lists, or the f_rl_items view in Advanced MIS to identify items that you would like to update. Learn more about this in the knowledge base.
2. Store the item’s ID from your report. You will need this to look up the resource.
For each item:
1. Get the draft item details using getDraftItem. We will use the draft item endpoints in case the item you are trying to edit only appears on a draft list. Learn more about the list lifecycle
  1. Find the resource ID from data.relationships.resource.data.id.
2. Then get the resource detail using getBibliographicResource.
  1. Make a note of the resource’s ID. data.id
3. You can also combine steps one and two in a single API call using getDraftItem and the include=resource parameter to also get the resource details. This is a JSON API efficiency and is known as a compound document.
```
https://rl.talis.com/3/{shortCode}/draft_items/{itemGuid}?include=resource
```
  1. In this case the resource will be in the included section of the response and will be referenced using a type of resource and an id that is found in the key data.relationships.resource.data.id.
4. See if the resource has a web address that you want to update.
  1. There may be multiple addresses in the attributes.web_addresses key in an array.
  2. When you update this property you will replace the original array with a new array.
  3. The contents of the new array could be the original array with the new web address added, or the old web address removed and replaced by your new web address.
5. See if the resource has a view online button online_resource which needs to be added or updated.
  1. If you want the view online button to point to your new web address, update the online_resource.
6. If you need to make a change, then you need to use an updateBibliographicResource request to update only the fields that you are interested in.
  1. This example JSON body would update the resource with the new web address and make sure that the view online button was also set to the same address:
```
{
   "data": {
         "type": "resources",
         "id": "<<the id of the resource you are updating>>",
         "attributes": {
            "web_addresses": [
               "<<new url>>"
            ],
            "online_resource": {
               "source": "uri",
               "link": "<<new url>>"
            }
         }
      }
}
```