Child pages
  • Patron Functionality
Skip to end of metadata
Go to start of metadata

7.  Patron Functionality

Discovery applications intended as alternatives to the OPAC will need to allow patrons to access their account information in the ILS as well as provide the circulation and delivery functionality available in the OPAC. In this section, we will define standard functions for interacting with ILS's circulation/delivery mechanisms and for accessing patron account information.

7.1 Rationale, use cases, and general issues

As an increasing number of institutions implement external discovery applications and move away from reliance on the integrated OPAC, they are remembering that patrons use the OPAC for more than just discovery - they also use it to manage their account and request delivery of discovered materials. In order for discovery applications to be used as OPAC alternatives, they need to be able to provide the same level of discovery to delivery functionality that the out-of-the-box OPAC provides. In addition, it is becoming increasingly desirable to enable patrons to access account information outside of the library web site in the online environments where they spend time: places like the campus portal, learning management systems, or even Facebook. Discovery applications will need to interact with the ILS in order to perform these functions.  There are three categories of these functions that are specified in this section: patron authentication, patron account retrieval, and circulation/delivery transactions.

Patron authentication: Discovery applications that make use of ILS patron information or allow a patron to perform some circulation activity will first need to authenticate with the ILS. This is necessary to obtain the ILS patron identifier that will be required to perform these patron account and circulation functions.  There are a few different use cases for obtaining the patron identifier from the ILS. For instance, the discovery application may utilize the ILS as the authoritative source of user information, and so may pass user credentials to the ILS, so that the ILS can verify the credentials, and provide a persistent patron id back to the discovery application. Or, the discovery application may use a different authoritative source of user data, such as a campus directory, and may need the ILS to resolve the directory id into the patron's ILS id. Or, the discovery application may need to verify that a patron has an account in the ILS.

Patron account retrieval: Discovery applications may want to retrieve information about a patron, after that patron has been authenticated in the ILS.  For instance, the discovery application may want to show a patron their library fines, current loans and status of hold requests.

Circulation/delivery: The ILS can be configured with complex circulation logic and policies that affect how an ILS handles these types of requests.  For instance, the ILS may be able to determine what the 'best' copy of a title is when a patron places a hold request.  Or the ILS may determine that an item can't be picked up at a certain location due to paging policies.  Or a consortial ILS may be able to determine from which location to place a hold request when a title is held by multiple consortial members.  To be clear, discovery applications should not try to replicate this logic.  Rather, discovery applications should request the ILS to perform these functions for them.  These functions are already implemented in the OPAC interface of the ILS.  The ILS should also expose the same logic to discovery applications via API requests.

The functions that are being discussed in this section may alter data in the ILS.  In addition, these functions will be performed with respect to individual patrons in the ILS. It is therefore very important that security and patron privacy are taken into consideration when implementing these functions.

7.2 Abstract function specifications

7.2.1  LookupPatron (minimum OPAC alternative)

Summary: 

This function looks up a patron in the ILS by an identifier, and is returned the ILS identifier for that patron, aka the patron identifier.

Parameters:

  • id: (type string; required): an identifier used to look up the patron in the ILS
  • idType: (type string; optional): the type of the identifier, as defined by the ILS, ie. barcode, local_id

Returns:

  • The ILS patron identifier that matches the lookup query is returned.
  • If no match is found, a PatronNotFound message is returned.

Exceptional conditions:

  • NotSupported: The underlying system does not support this type of request.
  • PatronNotFound: The requested patron could not be identified.

Side effects: 

None

Rationale:  

Discovery applications will need to know the patron's primary ILS identifier in order to perform other patron functions.

Notes:

  • The id types will be defined by the ILS and may vary between ILS vendors and also between ILS installations. Therefore, there should be no constraints placed on the id type field.
  • The ILS may choose whether or not to use id_type based on how ids are stored in the ILS.

Possible Bindings:

  • NCIP - Lookup User Service
    • must use either Unique User Id or Visible User Id
  • SIP2 - there is no binding for this function in the SIP2 protocol
7.2.2 AuthenticatePatron (minimum OPAC alternative)

Summary: 

The ILS authenticates a patron's login credentials and returns the identifier for the patron.

Parameters:

  • username:  (type string; required)
  • password:  (type string; required)

Returns:

  • The ILS patron identifier that matches the patron credentials.
  • If the username is not found or the password does not match, PatronNotFound message is returned.

Exceptional Conditions:

  • NotSupported - the function is not supported by the ILS.
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS. Note that this condition refers to authorization of the client application, not the end user.
  • PatronNotFound: The requested patron could not be identified.

Side effects: 

No direct required side effects, though some ILS's may consider the application to be authorized after this function is invoked.

Rationale: 

The discovery application may use the ILS as its authoritative source of user data.

Possible Bindings:

  • NCIP - Authenticate User Service
  • SIP2 - Login command
7.2.3 GetPatronInfo (minimum OPAC alternative)

Summary: 

The ILS returns specified information about the patron, based on options in the request.  This function can optionally return patron's contact information, fine information, hold request information, loan information, and messages.

Parameters:  

  • patronId:  (type string; required): the unique patron identifier in the ILS; the same identifier returned by LookupPatron and AuthenticatePatron
  • showContact:  (type boolean; default true; optional): whether or not to return patron's contact information in the response
  • showFines:  (type boolean; default false; optional): whether or not to return fine information in the response
  • showHolds:  (type boolean; default false; optional): whether or not to return hold request information in the response
  • showLoans:  (type boolean; default false; optional): whether or not to return loan information in the response
  • showRecalls:  (type boolean; default false; optional): whether or not to return recall information in the response
  • showMessages:  (type boolean; default false; optional): whether or not to return patron messages in the response

Returns:

  • Requested information is returned about the patron.
  • If no match is found on the patronId, return PatronNotFound message.
  • Response should be well formatted to include identifiers for holds and loans

Exceptional Conditions:

  • NotSupported - This function is not supported by the ILS
  • NotAuthorized - The client attempting to use this function is not authorized by the ILS
  • PatronNotFound: The requested patron could not be identified.

Side effects:

None

Rationale:

Discovery applications may need to display a patron's account information.

Notes:

  • Response needs to be well structured so that discovery application can retrieve hold and loan identifiers from the response, in order to perform RenewLoan and CancelHold functions

Possible Bindings:

  • NCIP - Lookup User Service partially implements this function
    • Has the ability to return fines, holds and loans.
    • Does not have the ability to return messages or recalls.
  • SIP2 - Patron Information command partially implements this function
    • Has the ability to return fines, holds, loans, and recalls.
    • Does not have the ablility to return messages.
7.2.4  GetPatronStatus (minimum OPAC alternative)

Summary:

This function requests the ILS to return a patron's status.

Parameters:

  • patronId:  (type string; required): the unique patron identifier in the ILS;  the same identifier returned by LookupPatron or AuthenticatePatron

Returns:

  • Returns a message with patron's borrower type, status, and expiration information
  • If no match found, returns PatronNotFound message

Exceptional Conditions:

  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS

Side effects:

None

Rationale:

Discovery applications may need to know patron's status in order to make authorization decisions.

Notes:

  • The response is really a subset of the response for the GetPatronInfo function.

Possible Bindings:

  • NCIP - Lookup User Service 
  • SIP2 - Patron Status Request command
7.2.5 [proposed] GetServices (Level 3)

Summary:
This function returns information about what services are available for a particular patron and particular item.

Parameters:

  • patronId: (type string; required): the unique patron identifier in the ILS; the same identifier returned by LookupPatron or AuthenticatePatron
  • itemId: (type string; required):system item identifier

Returns:

  • An  enumerated list of services available for a particular patron and a particular item.

Exceptional conditions:

  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS
  • PatronNotFound: The requested patron could not be identified.
  • RecordNotFound: The requested item could not be identified.

Side effects:

This function has no side effects.

Rationale: 

Currently available services to a patron at a particular moment in time for a particular patron is a complex calculation made by the ILS for every single transaction. It calculates whether the patron has the ability to perform the requested service (for example, a hold, recall, request, or check out), which may be influenced by whether the patron's account is blocked for unpaid fines or other reasons, as well as whether the patron's type in the system (for example, grad student, faculty, undergraduate) has the ability to perform the requested service for the requested item (for example, circulation policies may be calculated based on patron and item type).

Notes:

  • The response should include multiple <availableFor> elements to describe the services available to the patron. Examples of services it might be useful to identify are: loan, request, recall, in building use, reproduce (some special collections materials can't be photocopied).
  • Both NCIP and ISO Holdings (ISO 20775) specify a possible list of enumerated values that could serve as the beginning of a vocabulary for this available services. The existing values are listed below.

Possible bindings:

  • This functionality is not specified by NCIP or SIP2.
  • Web service call - this function could be implemented as an XML based web service on top of the ILS.
7.2.6 RenewLoan (minimum OPAC alternative)

Summary:

This function extends the due date for a patron's existing loan

Parameters:

  • patronId: (type string; required): the unique patron identifier in the ILS; the same identifier returned by LookupPatron or AuthenticatePatron
  • itemId: (type string; required):system item identifier
  • desired due date (type date, optional): the date the patron would like the item returned by 

Returns:

  • New loan message with the new due date.
  • If no items match the item identifier, returns RecordNotFound message.

Exceptional conditions:

  • NotRenewable - the item is not able to be renewed by the ILS
  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS
  • PatronNotFound: The requested patron could not be identified.
  • RecordNotFound: The requested item could not be identified.

Side effects:

Date and loan are both updated.

Rationale: 

Patrons will want to renew their loans through their accustomed library interface.

Notes:

In discovery applications that do not support patron and circulation functions (and thus are not OPAC alternatives), it may still be useful to hand off control to the underlying OPAC to process renewals. Such application handoff is described in section 8.

Possible bindings:

  • NCIP - Renew Item Service
  • SIP2 - Renew command
7.2.7 HoldTitle (minimum OPAC alternative)

Summary: 

Creates, for a patron, a title-level hold request on a given bibliographic record in the ILS.

Parameters:

  • patronId (type string; required): the ILS identifier for the patron for whom the request is placed
  • bibId (type string; required): the ILS identifier for the bibliographic record on which the request is placed
  • requestLocation (type string; required): IP address where the end user request is being placed
  • pickupLocation (type string; optional): an identifier indicating the location to which to deliver the item for pickup
  • neededBeforeDate (type date or time; optional): date after which hold request is no longer needed 
  • pickupExpiryDate (type date or time; optional): date after which item returned to shelf if item is not picked up 

[dak: I have dropped the concept of the 'like item group' from this functional specification.  For one, it is just  too hard to specify.  Also, it should be acceptable to return an error message that indicates that a title level hold request can not be placed on the bibliographic record, and that an item level hold request is necessary]

Returns:

  • If a hold request is successfully placed, a response message indicates where the item may be picked up and the date it expects the item to be available
  • A restricted access message - qualified success message that title is not holdable, but is accessible under certain conditions (i.e. does not circulate)
  • Title level hold not available message - message indicating the this title is not requestable, but item level hold requests may be available
  • NotHoldable message - error message that title is not holdable by this patron

Exceptional Conditions:

  • NotSupported: the function is not supported by the ILS
  • NotAuthorized: the client attempting to use this function is not authorized by the ILS
  • NotHoldable: the title cannot be held by the patron

Side effects:

A hold request is placed on a title in the ILS. 

Rationale:

Patrons will want to place hold requests on the titles that they discover. The discovery application should not have to replicate the functionality that the ILS provides in terms of determining best item. This function allows discovery application to initiate a hold request with a patron id and bib id. A title-level hold request is a hold request that is placed on the bibliographic record, rather than on an individual item record, in the ILS.

Request location is required in order to allow ILS to determine pickup locations and apply paging rules.

Possible Bindings:

  • NCIP - Request Item Service does not completely implement this function because it does not allow for specifying pickup location
  • SIP2 - Hold command
  • Web service call - this function could be implemented as an XML based web service on top of the ILS
7.2.8  HoldItem  (minimum OPAC alternative)

Summary: 

Creates, for a patron, an item-level hold request on a specific item of a bibliographic record in the ILS.

Parameters:

  • patronId (type string; required): the ILS identifier for the patron for whom the request is placed
  • bibId (type string; required): the ILS identifier for the bibliographic record on which the request is placed
  • itemId (type string; required): the ILS identifier for the specific item on which the request is placed
  • pickupLocation (type string; optional): an identifier indicating the location to which to deliver the item for pickup
  • neededBeforeDate (type date or time; optional): date after which hold request is no longer needed
  • pickup expiry date (type date or time; optional): date after which item returned to shelf if item is not picked up

Returns:

  • If a hold request is successfully placed, a response message indicates where the item may be picked up and the date it expects the item to be available
  • A restricted access message - qualified success message that title is not holdable, but is accessible under certain conditions (i.e. does not circulate)
  • NotHoldable message - error message that title is not holdable by this patron

Exceptional Conditions:

  • NotSupported: The ILS does not support this type of hold request.
  • NotHoldable: the item cannot be held by the patron

Side effects:

Hold request is placed on an item in the ILS. 

Rationale:

Patrons will want to place hold requests on the items that they discover This function allows the user to determine which item is the best option to request.

An item-level hold request is a hold request that is placed on a specific item, rather than on the bibliographic record, in the ILS.

Possible Bindings:

  • NCIP - Request Item Service does not completely implement this function because it does not allow for specifying pickup location
  • SIP2 - Hold command
  • Web service call - this function could be implemented as an XML based web service on top of the ILS
7.2.9 CancelHold (minimum OPAC alternative)

Summary: 

This function cancels an active hold request for the patron

Parameters:

  • patronId (type string; required): the unique patron identifier in the ILS; the same identifier returned by LookupPatron or AuthenticatePatron
  • itemId: (type string; required): system item identifier

Returns:

  • Confirmation message that this was successful or not.
  • If no patron records match the patron identifier, returns PatronNotFound message
  • If no items match the item identifier, returns RecordNotFound message.

Exceptional conditions:

  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS
  • NotCanceled- the hold could not be canceled by the ILS
  • PatronNotFound: The requested patron could not be identified.
  • RecordNotFound: The requested item could not be identified.

Side effects:

Hold request is canceled.

Rationale: 

Patrons will want to cancel holds as well as make them.

Possible bindings:

  • NCIP - Cancel Request Item Service
  • SIP2 - Hold command
7.2.10 RecallItem (minimum OPAC alternative)

Summary:

Initiates a recall of an item that is loaned out.

Parameters:

  • itemId (type string; required): the ILS identifier for the specific item on which the recall is placed
  • desiredDueDate (type date or time; optional)

Returns:

  • If recall is successfully placed on the item, a message will be returned indicating an estimated delivery date
  • Not eligible for recall - error message that item is not eligible for recall

Exceptional Conditions:

  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS

Rationale:

If patrons discover items they want that are on loan, they may want to recall them.

Possible Bindings:

  • NCIP - Recall Item Service
  • SIP2 - there is no binding for this function in the SIP2 protocol
7.2.11 CancelRecall  (minimum OPAC alternative)

Summary: 

This function cancels an active recall request for the patron

Parameters:

  • patronId (type string; required): the unique patron identifier in the ILS; the same identifier returned by LookupPatron or AuthenticatePatron

* itemId: (type string; required):  system item identifier

Returns:

  • Confirmation message that the recall was successfully canceled or not.
  • If no patron records match the patron identifier, returns PatronNotFound message
  • If no items match the item identifier, returns RecordNotFound message.

Exceptional conditions:

  • NotSupported - the function is not supported by the ILS
  • NotAuthorized - the client attempting to use this function is not authorized by the ILS
  • NotCanceled - the item was not able to be canceled by the ILS
  • PatronNotFound: The requested patron could not be identified.
  • RecordNotFound: The requested item could not be identified.

Side effects:

Recall is canceled

Rationale:

Patrons may need to cancel as well as make recalls.

Possible bindings:

  • NCIP - Cancel Recall Item Service
  • SIP2 - there is no binding for this function in the SIP2 protocol

7.3  Patron Functionality Binding References

  • No labels