Evergreen DokuWiki

I'm going to step back a bit here and go through the Open-ILS API and fieldmapper objects needed by the staff client. The staff client talks to various services (or applications) which register methods on an OpenSRF network in the open-ils namespace. Over the wire, data is sent between these services and the staff client as JSON arrays with class hints in surrounding comments (update: we're deprecating class hints and moving toward the current JSON standard). We have Fieldmapper classes written in several languages that turn these JSON arrays into objects based on the class hints. We call these Fieldmapper Objects.

The first thing the staff client does from a network perspective is talk to open-ils.auth.

We send the login name through open-ils.auth.authenticate.init, do some md5 magic with the return value and the user supplied password, and send that back to Evergreen through open-ils.auth.authenticate.complete. If all goes well, we receive a session key that we can then use for authenticated methods to do more interesting things.

After the user is logged in, we start grabbing data that we'd like to cache in the client. Things like organization hierarchy, a list of copy locations, ID types, etc.

This method returns most of the user data for the person logged in (the user associated with the session key). This data is returned as a fieldmapper object with the shortname of "au", but otherwise known as Fieldmapper::actor::user on the server side of Evergreen. In the following table, *'s indicate "virtual" fields, which are usually just empty placeholders to hang other fieldmapper objects. A "fleshed" fieldmapper object is one where some or all of these virtual fields are filled in.

This method returns an array of Fieldmapper::permission::grp_tree (or "pgt") objects. These objects are a hierarchal set of permission groups that users may belong to, such as Patrons, Staff, Catalogers, and Circulators.

This method returns an array of Fieldmapper::config::identification_type (or "cit") objects. These classify various types of identification that can be associated with a user, such as Driver's License or SSN.

This method returns an array of Fieldmapper::config::standing (or "cst") objects. These are used to describe a user's standing for the purpose of granting library priveledges. Currently we have "Good" and "Barred".

This method returns an array of Fieldmapper::asset::copy_location (or "acpl") objects. These are copy locations associated with items. The only PINES-wide default is "Stacks".

This method returns an array of Fieldmapper::config::copy_status (or "ccs") objects. These are statuses associated with items, such as Checked Out, Lost, Missing, In Process, In Transit, etc.

This method returns a "fleshed" Fieldmapper::actor::org_unit (or "aou") object containing the whole organization tree for the consortium. The objects are linked through the parent_ou field (points to a single "aou") and the children field (contains an array of "aou" objects).

This method returns an array of Fieldmapper::actor::org_unit_type (or "aout") objects, which classify the different types of "aou"'s. We currently have "Consortium", "System", "Branch", "Bookmobile", and "Sub-lib".

This method returns a flat array of Fieldmapper::actor::org_unit (or "aou") objects associated with the sessioned user. For example, a user with a home org unit of ARL will have all the ARL-branch libraries in this list, as well as the PINES consortium as the top-level org unit.

This method returns an array of Fieldmapper::actor::stat_cat (or "actsc") objects associated with the sessioned user's home org unit. These objects are Statistical Categories defined by the libraries and intended for local reporting, and these in particular get associated with patrons.

The checkout interface needs to retrieve the "au" object for the patron. If this has not already been provided (by say, a different interface), we can use this method to retrieve the patron by their library card barcode. The "fleshed" part is the au's .cards(), .addresses(), and .stat_cat_entries() fields.

Though not strictly needed for a checkout interface, this method returns the patron's current checkouts. It actually returns an array of useful composite objects. Each object contains 3 fields (circ, copy, and record), each containing a fieldmapper object.

The circ field contains a Fieldmapper::action::open_circulation (or "aoc") object. This represents the actual transaction for the circulating item, and contains information such as what circulation rules are associated with the checkout, the due date, the library that checked the item out, etc. In the database, open_circulations are technically a view of circulations, which is why the various checkin fields are listed. They should contain null's in this case. Similarly, .xact_finish() should be null.

The copy field contains a Fieldmapper::asset::copy (or "acp") object. This represents the actual item in the database, and has information such as the item's barcode, shelving location, stat cat entries, etc.

The record field contains a Fieldmapper::metabib::virtual_record (or "mvr") object. This is basically bibliographic data about the title record to which the copy belongs. It contains information such as the title and author of the work, the ISBN, subject headings, etc.

This method does a basic permissibility test against the item and the patron. Can this patron check out this item? One of the permissibility rules is concerned with the total number of items a patron has checked out. The first prototype of the staff client called this method asychronously, so I believe the thought was that we needed an argument to tell the method how many "outstanding" or unprocessed checkout attempts were queued up, so we could potentially count that number against the total number of checked out items. We should probably revisit this to double-check what we were thinking, and see if it is still needed and/or implemented correctly.

The method returns a simple object containing a status field and a corresponding text field. A status of 0 means that the patron is permitted to checkout the item.

This method attempts the actual checkout of an item to a patron. Like the open-ils.circ.actor.user.checked_out method, it returns a composite object (circ, copy, and record) with various fieldmapper objects. The copy field holds a Fieldmapper::asset::copy (or "acp") object. The record field contains a Fieldmapper::metabib::virtual_record (or "mvr") object. However, the circ field contains an actual Fieldmapper::action::circulation (or "circ") object instead of its open circulation subclass.

Internally this method is implemented with open-ils.storage.actor.user.crazy_search, and we'll need to ask Mike why he named it such. :D The search hash contains keys that correspond to the fields to search. For example, family_name, email, or first_given_name. Each key indexes an object containing two fields, value and group. Value contains the value for the field to search for. Group contains a number 0-2, which helps crazy_search determine which table the field goes with. Group 0 are real fields directly on the "au" object. Group 1 are address fields. Group 2 are phone numbers and ID values.

Here's an example search hash:

 { 'phone' : { 'value' : '555-5555', 'group' : '2' } }

There's no single "phone" field on an "au" object. Instead, crazy search must look at day_phone, evening_phone, and other_phone. Similarly, address fields look at all addresses attached to a user.

This method returns a list of "au" id's.

Similar to open-ils.actor.user.fleshed.retrieve_by_barcode, this method takes an au id as the selection criteria, and returns an "au".