Replicate 'Your Account' functionality with Alma

[kelynch]

Use the switch created in #2362

The following sections of the account page need to be reimplemented for alma:

• patron blocks (remove; we can't get these from alma)
• charged items
• available held items
• hold requests
• fines / fees

Relevant areas of the code:

• account controller
  • tests note this controller is not well-tested in the actions that will require migration
  • voyager patron client
  • voyager account
  • account helper

Areas of the page not affected:

• "Outstanding digitization requests" - this is illiad functionality

Implementation notes:

• use alma-rb. there may be places where we need to submit PRs upstream
• Alma API documentation
• Ensure the case where the patron log-in by barcode is working and has test coverage
• There is some javascript involved in these pages to submit forms without refreshing the page
  • because of pagination required to get all loans, requests, or fees, we may need to move more logic into javascript.
• Note there is a use case for renewing a LOT of items at once (like all 500 books that a person has checked out)
  • We won't be able to accommodate this with the alma api; it only allows one renewal at a time. We should implement a "renew this item" button on each row to avoid hitting that endpoint rapid-fire.
• The fees may have a decimal value; make sure that's coming through from bibdata.
• Test a renew request when the patron account has limits.
• Provide useful feedback when we've hit the api concurrency limit (ask user to wait a moment and try again)

Other Notes:

• What are recalls? Is there functionality here that needs to be migrated?
  • This functionality was removed as part of covid-related policy changes. Assume we do not need to re-implement for now.

[kelynch]

Example from alma_rb gem for accessing user objects:

require 'alma'

Alma.configure do |config|
  config.apikey = 'X'
  # ...
end

$primary_identifier = "john.doe"

u = Alma::User.find($primary_identifier)

# Methods 
$ ls u
Alma::User#methods: 
  []        loans                  preferred_name        save!         
  []=       loggable               preferred_suffix      to_json       
  email     method_missing         renew_all_loans       total_fines   
  fines     preferred_email        renew_loan            total_loans   
  has_key?  preferred_first_name   renew_multiple_loans  total_requests
  id        preferred_last_name    requests              validate      
  keys      preferred_middle_name  response            

[hackartisan]

account_controller#index

First fetches patron "first_name", "last_name", "barcode" from bibdata using the netit.

Then it hits voyager to get the account object with the following properties:

• avail_items has keys:
  • itemID
  • itemTitle
  • expireDate
  • pickuplocation
  • in helper:
  • holdRecallID
  • holdType
• request_items has keys:
  • itemID
  • itemTitle
  • expireDate
  • pickuplocation
  • queuePosition
  • in helper:
  • holdRecallID
  • holdType
• fines_fees has keys:
  • date
  • title
  • postingType
  • amount
  • balance
  • there's a total but it's just accessed as "last"?
• charged_items has keys:
  • itemId
  • renewable
  • title
  • dueDate
  • in helper:
  • renew_status
  • callNumber
  • locationCode
  • statusCode
  • [:messages]['message']
  • [:renew_status]['status']
• borrowing_blocks has keys:
  • patronGroupName
  • blockCount
  • blockReason

[hackartisan]

Block info needs to be added to the bibdata response so it can be pulled from the patron without an additional API call. Block data from alma looks like

      "user_block": [
        {
          "segment_type": "Internal",
          "block_type": {
            "value": "LOAN"
          },
          "block_description": {
            "value": "CONSORTIA"
          },
          "block_status": "string",
          "block_note": "string",
          "created_by": "string",
          "created_date": "2024-05-30T09:30:10Z",
          "expiry_date": "2019-12-18T14:36:48.659Z"
        }
      ],

How does this map onto our current values?

• patronGroupName
• blockCount
• blockReason

Here's some example block data from voyager:

            <myac:borrowingBlocks>
                <myac:title>Blocks</myac:title>
                <myac:clusterBorrowingBlocks>
                    <myac:cluster>
                        <myac:clusterName>Princeton University Library</myac:clusterName>
                        <myac:ubSiteId>1@PRINCETONDB20050302104001</myac:ubSiteId>
                    </myac:cluster>
                    <myac:borrowingBlock>
                        <myac:blockReason>odue_recall_limit_patron</myac:blockReason>
                        <myac:blockCount>1</myac:blockCount>
                        <myac:blockCode>21</myac:blockCode>
                        <myac:blockLimit>1</myac:blockLimit>
                        <myac:itemType xsi:nil="true" />
                        <myac:pendingHoldCount xsi:nil="true" />
                        <myac:patronGroupName>Faculty and Professional Staff</myac:patronGroupName>
                    </myac:borrowingBlock>
                </myac:clusterBorrowingBlocks>
            </myac:borrowingBlocks>

[hackartisan]

avail_items and request_items I think would both come from the user requests GET endpoint.

Data coming back looks like: https://developers.exlibrisgroup.com/alma/apis/docs/xsd/rest_user_requests.xsd/?tags=GET

• itemID: we get a holding_id will that work? This is for using to cancel the request. Maybe there is a request id.
• itemTitle: chapter_or_article_title
• expireDate: not given? we get last_interest_date, booking_start_date, and booking_end_date. Not sure if any of those are relevant here
• pickuplocation: pickup_location_library and pickup_location_circulation_desk
• queuePosition: not given. I do see it in the alma patron UI. Is there another way to get this? Probably can just not display this anymore.

[hackartisan]

charged_items will come from the user loans get endpoint

use expand=renewable to get renewable value.

loans object

loan object

looks like these will need to be filtered for active loans (see loan_status) value of loan object.

• itemId: we get barcode, mms_id, holding_id, item_id. Is item_id what we want? This value will be used for renewal; figure out what the renew endpoint uses.
• renewable: renewable
• title: title
• dueDate: due_date

[hackartisan]

fines_fees will come from the user fines endpoint. Returns active fees by default. Is that what we want?

fees object

fee object

• date: creation_time
• title: title
• postingType: type description (but from the example it looks like the api only sends the type value? maybe we can ask them to add the description)
• amount: original_amount
• balance: balance

[kevinreiss]

Yes, active fees would be what we want to display. We didn't have the option to display past fees in Voyager so that would be new functionality that could potentially added to allow users to see their paid/cancelled fines.

[hackartisan]

https://github.com/tulibraries/alma_rb/blob/main/lib/alma/user.rb#L9 this expand option is making me think there's an undocumented option on https://developers.exlibrisgroup.com/alma/apis/docs/users/R0VUIC9hbG1hd3MvdjEvdXNlcnM=/ to get everything we need in 1 call. If so we'd pull it through the bibdata endpoint.

update: that expand only gives the total numbers / amounts. But if we pull that we can use it to determine whether we need to hit the other endpoints.

[hackartisan]

• request cancel endpoint takes request_id and returns 204 No Content on success.
• renew loan takes loan_id and returns the loan object

[hackartisan]

This issue is blocked pending a decision on whether to use alma's "library card" page instead of reimplementing this in blacklight.

Arguments in favor of using the alma page:

1. The local implementation requires 5 API calls to build the display page. Note that this is 1/5th of the concurrency limit for API calls.
2. There is functionality we cannot implement via the API, such as:
   1. "renew all" (the api only provides single renewal, and again the concurrency limit)
   2. up-front account limit notifications (e.g. "You can't renew this because you have too many fines" in the API is just "renewable: false")
3. There is functionality that will be time-consuming to re-develop and maintain locally, such that it starts to make more sense to use the existing page which already does everything we want.
   4. paginated /sortable loans list, fees, and requests. (note we'd probably need to do this in javascript)
4. Using the alma page would release developer time as we move toward go-live.
5. Penn went this route and advised us it's a good way to go.

There are a few considerations we need to iron out:

1. We'll need to do at least a little custom styling on this page, if only to get rid of the big vacation-y icons that display in the content areas when there's no data.
   2. documentation on how to do this: https://knowledge.exlibrisgroup.com/Alma/Product_Documentation/010Alma_Online_Help_(English)/070Alma-Summon_Integration/050Display_Configuration/020Branding_the_Services_Page
   3. We will want a repo to put the CSS file/s in, with a little readme. We may use libapps for this with a directory called either "alma" or "summon"
2. Information Architecture for linking to the account page
   2. We can't customize the header any more than we've already done, so IA will likely depend on opening the library card in a new tab and trusting users to be able to get back to the catalog when they're done.
3. What do we do with guest accounts? Options:
   2. Get them netids (preferred)
   3. Provide them with usernames / passwords directly in Alma, managed by circulation
   4. Provide a minimal UI for them in blacklight
   5. Just not provide an online account service for guests

Work for this issue is in progress on branch 2025-alma-account if/when we pick it up again.

[hackartisan]

closing in favor of #2401