User Tools

You are here: start » public » bc_services_card
Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
public:bc_services_card [2023/03/24 20:35]
jeff [Patron information in Evergreen] 		public:bc_services_card [2024/05/09 05:04] (current)
Line 7: Line 7:
 Patrons are normally registered via the EG staff client, by staff at the circ desk ([[https://docs.evergreen-ils.org/eg/docs/latest/circulation/circulation_patron_records_web_client.html#_registering_new_patrons|docs]]). We also have custom scripts for importing patron records from student management systems for a few post-secondary libraries. There's no official API or process specifically intended to enable third-party applications to create/import/validate patron records (EG needs more third-party-friendly APIs generally), but there's a feature request to include a standard import script: [[https://bugs.launchpad.net/evergreen/+bug/1786524|LP#1786524]] Patrons are normally registered via the EG staff client, by staff at the circ desk ([[https://docs.evergreen-ils.org/eg/docs/latest/circulation/circulation_patron_records_web_client.html#_registering_new_patrons|docs]]). We also have custom scripts for importing patron records from student management systems for a few post-secondary libraries. There's no official API or process specifically intended to enable third-party applications to create/import/validate patron records (EG needs more third-party-friendly APIs generally), but there's a feature request to include a standard import script: [[https://bugs.launchpad.net/evergreen/+bug/1786524|LP#1786524]]
  
-Several other Evergreen consortia (PINES and KCLS) use Quipu's eCARD product which has some overlap with BC Services Card use cases. There's been some effort to bring their Quipu integration into mainline Evergreen, ideally in a generic way that could also support similar products: [[https://bugs.launchpad.net/evergreen/+bug/1902937|LP#1902937]]+Several other Evergreen consortia (PINES and KCLS) use Quipu's eCARD product which has some overlap with BC Services Card use cases. There's been some effort to bring their Quipu integration into mainline Evergreen, ideally in a generic way that could also support similar products: [[https://bugs.launchpad.net/evergreen/+bug/1902937|LP#1902937]] (there's some discussion here of account renewal requirements at non-Sitka libraries which may be of interest too).
  
 Evergreen also has a patron self-registration feature ([[https://docs.evergreen-ils.org/eg/docs/latest/circulation/circulation_patron_records_web_client.html#_patron_self_registration|main docs]] / [[https://docs.evergreen-ils.org/eg/docs/latest/admin/patron_self_registration.html|admin docs]]). <del>We're not using it, but</del> it's a good fit for this project; if nothing else, it provides a model for how to go about creating patron-initiated "pending" accounts in EG. Evergreen also has a patron self-registration feature ([[https://docs.evergreen-ils.org/eg/docs/latest/circulation/circulation_patron_records_web_client.html#_patron_self_registration|main docs]] / [[https://docs.evergreen-ils.org/eg/docs/latest/admin/patron_self_registration.html|admin docs]]). <del>We're not using it, but</del> it's a good fit for this project; if nothing else, it provides a model for how to go about creating patron-initiated "pending" accounts in EG.
Line 34: Line 34:
  
  
-==== Using the Evergreen API ====+===== User stories for BCSC integration ===== 
 + 
 +  - As a new patron, I want to register for a library card online so that I can access library resources more easily. 
 +  - As circulation staff, I want new patrons to pre-register for an account online so that the registration process is more efficient and accessible and patron information is entered quickly and reliably. 
 +  - As circulation staff, I want to auto-validate current patrons when I renew their accounts so that I don't have to do it manually at the circ desk. 
 +  - As a library manager, I want patron accounts to be pre-registered/validated to reduce workload at the circ desk and improve reliability of patron information. 
 +  - As a Co-op service manager, I want patron data to be validated so that I can use it as a basis for other services. 
 +  - As a malicious user, I want to create fake or unauthorized patron accounts so that I can access library resources illegitimately. 
  
-//(this section is a work in progress)//+===== Creating a patron self-registration application =====
  
 Suppose we wanted to create an application that allowed patrons to request a library card using their BC Services Card. That is, instead of using EG's native patron self-registration UI, we'd have an external app that presents the user with a registration form, populates with their personal data based on their BC Services Card, and then submits that data to Evergreen to create a "pending" patron account (which would then be reviewed and approved by library staff within Evergreen, just like native self-registration). Suppose we wanted to create an application that allowed patrons to request a library card using their BC Services Card. That is, instead of using EG's native patron self-registration UI, we'd have an external app that presents the user with a registration form, populates with their personal data based on their BC Services Card, and then submits that data to Evergreen to create a "pending" patron account (which would then be reviewed and approved by library staff within Evergreen, just like native self-registration).
  
-How does our application submit the patron data to Evergreen?+How does our application submit the patron data to Evergreen? Our best bet is to use the existing infrastructure for native patron self-registration as much as possible -- that is, create pending patron accounts in the same way that Evergreen itself does.
  
 Native self-reg uses the ''open-ils.actor.user.stage.create'' API. This endpoint accepts the following parameters: Native self-reg uses the ''open-ils.actor.user.stage.create'' API. This endpoint accepts the following parameters:
Line 50: Line 58:
  
 Only the first parameter (user) is required, the others are optional. The object classes (stgu, stgma, stgsc, stgs) are defined by the [[https://docs.evergreen-ils.org/eg/docs/latest/development/intro_opensrf.html#_accepting_and_returning_evergreen_objects|fieldmapper]]. Only the first parameter (user) is required, the others are optional. The object classes (stgu, stgma, stgsc, stgs) are defined by the [[https://docs.evergreen-ils.org/eg/docs/latest/development/intro_opensrf.html#_accepting_and_returning_evergreen_objects|fieldmapper]].
-===== User stories for BCSC integration ===== 
  
-  - As a new patron, I want to register for a library card online so that I can access library resources more easily. +How do we use this API? There are a few possibilities: 
-  - As circulation staff, I want new patrons to pre-register for an account online so that the registration process is more efficient and accessible and patron information is entered quickly and reliably. + 
-  - As circulation staff, I want to auto-validate current patrons when I renew their accounts so that I don't have to do it manually at the circ desk. +1. We could use it directly, by submitting HTTP requests to the [[https://wiki.evergreen-ils.org/doku.php?id=osrfhttp:opensrf_gateway|OpenSRF gateway]], like so: 
-  - As a library manager, I want patron accounts to be pre-registered/validated to reduce workload at the circ desk and improve reliability of patron information. + 
-  - As a Co-op service manager, I want patron data to be validated so that I can use it as a basis for other services. +<code>https://<domain>/osrf-gateway-v1?service=open-ils.actor&method=open-ils.actor.user.stage.create&param=[<user object>]</code>  
-  - As a malicious user, I want to create fake or unauthorized patron accounts so that I can access library resources illegitimately.+ 
 +For this to work, our application would need to know how to instantiate Evergreen-specific fieldmapper objects (stgu, etc.) that will be accepted as such when passed to EG via the gateway, which is non-trivial. This is a brittle approach for an external application. 
 + 
 +2. We could build BC Services Card integration directly into Evergreen. This is probably not a good idea, since it requires developers to be knowledgeable about both Evergreen and BC Services Card. Also, we want to leave the door open to using our hypothetical patron self-registration application with non-Evergreen library systems. 
 + 
 +3. We could create a thin wrapper service in Evergreen that accepts patron data as a JSON blob, translates it into native Evergreen objects, and passes the result to the ''open-ils.actor.user.stage.create'' API. This would mean that our application doesn't have to know anything about Evergreen objects or the fieldmapper. The service could also include some kind of simple "API key" type mechanism that indicates which application provided the patron data; this could be leveraged to speed up the approval process, since BC Services Card-based account requests are presumed to be trustworthy. For simplicity's sake, the service could be exposed as another Evergreen API via the OpenSRF gateway. This would obviously require some Evergreen-specific development, but implementation would not be an enormous project for a knowledgeable Evergreen developer, and the actual self-registration application could be built separately by devs who don't need to have much experience with Evergreen. 
 + 
 +4. We could skip the API and allow the application to insert patron data directly into staging.user_stage and related tables in Evergreen's Postgres database. 
 + 
 +==== Matching existing accounts ==== 
 + 
 +The staff interface for patron registration checks for duplicates during the registration process: it will present a notification if the provided name, email, or address already exists in Evergreen. The duplicate checks are performed using the ''open-ils.actor.patron.search.advanced'' API, which will return the IDs of any patron accounts where the fields you specify (e.g. email) are an exact match for the values you specify (e.g. "foo@example.com"). This API requires an auth token, which is basically the session token you receive upon authenticating. It is possible to obtain an auth token via the OpenSRF gateway ([[https://wiki.evergreen-ils.org/doku.php?id=newdevs:apis|see here]]), but you will need login credentials for a user that has permission to retrieve patron data; only patrons that are accessible to that user will be included in search results. 
 + 
 +Many BC public library patrons have their driver's license or BC Services Card number in the ident_value field, but this data is not controlled or validated and we can't guarantee its accuracy. 
 + 
 +==== Further information ==== 
 + 
 + 
 +[[https://docs.evergreen-ils.org/eg/docs/latest/integrations/web_services.html|More information about Evergreen web services (OpenSRF gateway etc.)]]. Some of this info may be outdated. 
 + 
 +[[https://docs.evergreen-ils.org/eg/docs/latest/development/intro_opensrf.html|Easing Gently into OpenSRF]] - an overview of how to write an OpenSRF service; provides a good introduction to some OpenSRF concepts and how to use them. 
 + 
 +[[https://wiki.evergreen-ils.org/doku.php?id=newdevs:start|Documentation for new Evergreen developers]] - very incomplete, but perhaps useful for orientation purposes.
  
 ---- ----
public/bc_services_card.1679690152.txt.gz · Last modified: 2023/03/24 20:35 by jeff

Page Tools

BC Libraries Coop wiki

Site Tools