Adding support for updating patron details

[lahmann]

Most libraries of the finc-community using Libero do allow updates of certain patron details. At least Koha does allow to update patron details as well. Especially smaller libraries might not afford a separate identity management system and therefore rely on the functionalities of the ILS to update patron details. Although some patron details certainly should not be allowed to be changed (such as the library-card-id or the name), changing other details such as email or address are often performed tasks - e.g. by often moving students. From our perspective this functionality provided all essentials tasks of day-to-day business could be performed without accessing the ILS (WebOpac etc.) but only via a Third-Party software using a DAIA/PAIA service.

Therefore we would like to propose the addition of

a) the scope write_patron b) the patron response fields canupdatename, canupdateemail and canupdateaddress of type boolean c) the core action update:

purpose
  : Update patron details
HTTP verb and URL
  : GET https://example.org/core/**{uri_escaped_patron_identifier}**/update
scope
  : write_patron
request fields
  :  name      occ    data type       description
    --------- ------ --------------- ----------------------------------------------
     name      0..1   string          new name of the patron
     email     0..1   email           new email address of the patron
     address   0..1   string          new freeform address of the patron
    --------- ------ --------------- ----------------------------------------------
response fields
  :  name     occ    data type     description
    -------- ------ ----------- -------------------
     patron   1..1   string      patron identifier
    -------- ------ ----------- -------------------

The server MUST check 

* the access token 
* whether the user bearing the access token has scope `write_patron`
* whether the requested fields are allowed to update

A PAIA server MAY reject this method and return an [error
response](#error-response) with error code `access_denied` (403) or error code
`not_implemented` (501). On success, the patron identifier is returned.

Although there has been a discussion on a similar issue (e.g. #29) and that the PAIA specification states to use other specialized APIs such as LDAP for additional patron details, this recommendation will only apply if a library already is using an identity management system which provides e.g. a LDAP interface. As argued above, small institutions usually lack such dedicated infrastructure. By supporting this functionality it would become much easier to establish PAIA services even for small libraries with heavily ILS-centralized workflows as this would allow the clean separation of public Third-Party frontend (i.e. discovery interface) and non-public ILS-backend mitigated by a (DAIA/)PAIA service.

[ndege]

I would like to participate in and underline this issue request. Any treatment will be helpful to make progress in our development and thereof move forwards with necessary design decisions for our running projects. Thanks.

[nichtich]

We discussed this internally and came to a similar result. I only agree with a). The current, unpublished draft is this (I added the example URL in response to @lahmann):

patron (ändern)
HTTP-Method: HTTP PATCH
URL: http://example.org/api/core/{patron_id}
Scope: write_patron

Only fields ocurring the the request are modified, for instance only the email:

{"email":"user@example.org"}

Unknown fields may result in a different error than than 403 or 501. PAIA implementations may choose to add custom fields although I am not happy with such extensions. Maybe custom fields need to start with x- or so.

[lahmann]

Thanks for your response and sorry for the long silence.

Your draft looks promising though I have some comments: 1.) The action patron is confusing as requesting patron details is done via the core method core/{patron_id} and any patron related subsequent method is called via core/{patron_id}/{method}. I wonder whether the conceptual thought behind the patron action to be dealing with the patron itself rather than with actions being performed by the patron might be more confusing than helpful. 2.) It should be possible to limit the scope to write any patron detail/field. If you are not happy with the above mentioned additional fields in the patron response what about having a method that reports the fields that are allowed to be updated?

[nichtich]

Thank's I have changed the example URL in response to 1).

For 2): do you want many scopes, such as write_patron_email, write_patron_name...?

A generic way to edit arbitrary key-values structures with fine-grained rights is of limited use for clients because the meaning of a fields is inherently unknown. The use case of having arbitrary fields does not look convincing to me because specifications are about avoiding arbitrary data structures. Can't we start with the existing patron fields (name, email, address, expires, status, type) or are there practical examples of missing fields?

[lahmann]

Thanks for getting back to this issue!

2.) I think it would be enough to add scopes for the three patron information fields (name, email, address - write_patron_name, write_patron_email, write_patron_address). A use case having the user to allow to change her expire, status and type values is not known to me - if these values are subject to change this usually happens via the IDM/ILS as those properties are very likely linked to service privileges.

[nichtich]

This may require #56 for browser-based clients (CORS is tricky).

[nichtich]

How about scope write_patron_details for email, name, and address and write_patron_account for types, state, and expires?

[nichtich]

For better separation I think about making this a third module in addition to PAIA core and PAIA auth. The URLs, however are in the core namespace because they work on the same identifiers.

PAIA accounts

Update an existing patron account with known patron_id:

HTTP-Method: HTTP PATCH
URL: http://example.org/api/core/{patron_id}

Create a new patron account with known patron_id or update an existing account with full data:

HTTP-Method: HTTP PUT
URL: http://example.org/api/core/{patron_id}

Add a new patron account with unknown patron_id

HTTP-Method: HTTP POST
URL: http://example.org/api/core/

Delete a patron account with known patron_id

HTTP-Method: HTTP DELETE
URL: http://example.org/api/core/{patron_id}

Scopes:

• PATCH
  • for patron data (name, email, address): write_patron_info
  • for selected of these fields: write_patron_name, write_patron_email, write_patron_address
  • for account data (status, types, expires): write_patron
• PUT
  • to update existing accounts: write_patron
  • to create new accounts: manage_patron
• POST/PUT and DELETE to create and delete accounts: manage_patron

This proposal should be reduced to not become too complex!

[lahmann]

Thanks for the update!

I like the proposal for updating the patron data and I think having scopes for each defined patron data-field is favorable as grouping name, email and address into one scope appears to be logical for no reason apart from keeping the specification slick.

Regarding the additional functionality to add a new patron account, despite the fact that I am not opposed to the idea of adding additional account managing functionality to PAIA, one could argue that such functionality might widen the scope for PAIA a bit too far. E.g. for scenarios DELETE and PUT with manage_patron (creating a patron account with known id) there is no actual use case known to me at our institution: accounts usually are not deleted by the user but by library staff after checking account balance etc. so this is an administrative task very likely not performed via a PAIA client. Creating a new user account is usually combined with checking the patron's id and handing out a library-card; creating a user account with a known id also seems to be more like an administrative task than actually an action performed via a PAIA client.

Therefore I would like to suggest to drop the proposed actions using the manage_patron scope in favor of a less complex PAIA specification. Of course only if the proposed actions are not the result of actual needs at your institution.

[nichtich]

@lahmann @ndege See http://gbv.github.io/paia/paia.html#update-patron for the current draft to be included in PAIA 1.4.0. Please shout out if something is missing or unclear!