===== Bird's Eye View - API Calls and Fieldmapper Objects =====

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.

===== Authentication =====

^ Application ^ Method ^ Parameters ^ CVS ^
| open-ils.auth | open-ils.auth.authenticate.init | login name | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/c-apps/oils_auth.c|C]], [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Auth.pm|Perl]] |
| open-ils.auth | open-ils.auth.authenticate.complete | login name, md5 hash | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/c-apps/oils_auth.c|C]], [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Auth.pm|Perl]] |

The first thing the staff client does from a network perspective is talk to [[documentation:developer:zzz_archive:open-ils_auth_api:open-ils.auth]].

==== open-ils.auth.authenticate.init ====
==== open-ils.auth.authenticate.complete ====

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.

===== Data Initialization =====

^ Application ^ Method ^ Parameters ^ CVS ^
| open-ils.search | open-ils.search.actor.user.session | session key | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Search/Actor.pm|Perl]] |
| open-ils.actor | open-ils.actor.groups.retrieve | | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.actor | open-ils.actor.user.ident_types.retrieve | |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.actor | open-ils.actor.standings.retrieve | |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.search | open-ils.search.config.copy_location.retrieve.all | | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Search/Biblio.pm|Perl]] |
| open-ils.search | open-ils.search.config.copy_status.retrieve.all | | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Search/Biblio.pm|Perl]] |
| open-ils.actor | open-ils.actor.org_tree.retrieve | |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.actor | open-ils.actor.org_types.retrieve | |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.actor | open-ils.actor.org_unit.full_path.retrieve | session key |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.circ | open-ils.circ.stat_cat.actor.retrieve.all | session key, staff library id | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Circ/StatCat.pm|Perl]]|

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.

==== open-ils.search.actor.user.session ====
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.

^  ^ Fieldmapper::actor::user ^ Description ^
|au|active| Is this user account enabled? |
|au|addresses * | Virtual field containing "aua" objects |
|au|alert_message| Text string to alert to staff when this user is accessed |
|au|billing_address| Null or index into .addresses()|
|au|card|Index into .cards()|
|au|cards * |Virtual field containing the library cards (fieldmapper "ac") associated with the user|
|au|checkouts * |Virtual field containing the user's checkouts|
|au|claims_returned_count|The number of times the user has claimed an item has been returned despite indications to the contrary|
|au|create_date|The date the user was created|
|au|credit_forward_balance|The monetary credit associated with the user|
|au|day_phone|
|au|dob|Date of Birth|
|au|email|
|au|evening_phone|
|au|expire_date|The date the user's priveledges are set to expire|
|au|family_name|
|au|first_given_name|
|au|hold_requests * |Virtual field containing item hold requests ("ahr") for the user|
|au|home_ou|Contains the id for the user's home organizational unit|
|au|id|The primary key for the user record|
|au|ident_type|Users have two slots for identification.  We segregate type and value.|
|au|ident_type2|Id for a "cit" object|
|au|ident_value|
|au|ident_value2|
|au|ischanged * | Standard fieldmapper field to help process objects. |
|au|isdeleted * | "" |
|au|isnew * | "" |
|au|last_xact_id|
|au|mailing_address|Null or index into .addresses()|
|au|master_account|Is this the primary user for a group?|
|au|net_access_level|
|au|other_phone|
|au|passwd|
|au|photo_url|
|au|prefix|Mr., Mrs., etc.|
|au|profile|The primary permission/user group associated with the user.|
|au|second_given_name|
|au|settings * |
|au|standing| 
|au|stat_cat_entries * |
|au|suffix|Jr., Sr., etc.|
|au|super_user|Is this user a super user?|
|au|survey_responses * |
|au|usrgroup|
|au|usrname|OPAC/staff client login name for this user|

==== open-ils.actor.groups.retrieve ====
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.

^  ^ Fieldmapper::permission::grp_tree ^
|pgt|description|
|pgt|id|
|pgt|ischanged * |
|pgt|isdeleted * |
|pgt|isnew * |
|pgt|name|
|pgt|parent|

==== open-ils.actor.user.ident_types.retrieve ====
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.

^  ^ Fieldmapper::config::identification_type ^
|cit|id|
|cit|ischanged * |
|cit|isdeleted * |
|cit|isnew * |
|cit|name|

==== open-ils.actor.standings.retrieve ====
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".

^  ^ Fieldmapper::config::standing ^
|cst|id|
|cst|ischanged * |
|cst|isdeleted * |
|cst|isnew * |
|cst|value|

==== open-ils.search.config.copy_location.retrieve.all ====
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".

^  ^ Fieldmapper::asset::copy_location ^ Description ^
|acpl|circulate|Can items in this location circulate?|
|acpl|holdable|Are items in this location holdable?|
|acpl|id|
|acpl|ischanged * |
|acpl|isdeleted * |
|acpl|isnew * |
|acpl|name|
|acpl|opac_visible|Are items in this location visible in the OPAC?|
|acpl|owning_lib|Id for the "aou" associated with this location|

==== open-ils.search.config.copy_status.retrieve.all ====
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.

^  ^ Fieldmapper::asset::copy_status ^ Description ^
|ccs|holdable|Are items with this status holdable?|
|ccs|id|
|ccs|ischanged * |
|ccs|isdeleted * |
|ccs|isnew * |
|ccs|name|

==== open-ils.actor.org_tree.retrieve ====
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).

^  ^ Fieldmapper::actor::org_unit ^
|aou|billing_address|
|aou|children * |
|aou|holds_address|
|aou|id|
|aou|ill_address|
|aou|ischanged * |
|aou|isdeleted * |
|aou|isnew * |
|aou|mailing_address|
|aou|name|
|aou|ou_type|
|aou|parent_ou|
|aou|shortname|

==== open-ils.actor.org_types.retrieve ====
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".

^  ^ Fieldmapper::actor::org_unit_type ^
|aout|can_have_users|
|aout|can_have_vols|
|aout|children * |
|aout|depth|
|aout|id|
|aout|ischanged * |
|aout|isdeleted * |
|aout|isnew * |
|aout|name|
|aout|opac_label|
|aout|parent|

==== open-ils.actor.org_unit.full_path.retrieve ====
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.

==== open-ils.circ.stat_cat.actor.retrieve.all ====
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.

^  ^ Fieldmapper::actor::stat_cat ^
|actsc|entries * |
|actsc|id|
|actsc|ischanged * |
|actsc|isdeleted * |
|actsc|isnew * |
|actsc|name|
|actsc|opac_visible|
|actsc|owner|

===== Check Out =====

^ Application ^ Method ^ Parameters ^ CVS ^
| open-ils.actor | open-ils.actor.user.fleshed.retrieve_by_barcode | session key, barcode | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Actor.pm|Perl]] |
| open-ils.circ | open-ils.circ.actor.user.checked_out | session key, "au" id | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Circ.pm|Perl]] |
| open-ils.circ | open-ils.circ.permit_checkout | session key, item barcode, "au" id, number of open async checkout requests |[[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Circ/Rules.pm|Perl]]  |
| open-ils.circ | open-ils.circ.checkout.barcode | session key, item barcode, "au" id | [[http://open-ils.org/cgi-bin/viewcvs.cgi/ILS/Open-ILS/src/perlmods/OpenILS/Application/Circ/Rules.pm|Perl]] |

==== open-ils.actor.user.fleshed.retrieve_by_barcode ====

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.

==== open-ils.circ.actor.user.checked_out ====

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.

^  ^
|circ|
|copy|
|record|

=== circ ===

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.

^  ^ Fieldmapper::action::open_circulation ^
|aoc|checkin_lib|
|aoc|checkin_staff|
|aoc|checkin_time|
|aoc|circ_lib|
|aoc|circ_staff|
|aoc|desk_renewal|
|aoc|due_date|
|aoc|duration|
|aoc|duration_rule|
|aoc|fine_interval|
|aoc|id|
|aoc|ischanged * |
|aoc|isdeleted * |
|aoc|isnew * |
|aoc|max_fine|
|aoc|max_fine_rule|
|aoc|opac_renewal|
|aoc|phone_renewal|
|aoc|recuring_fine|
|aoc|recuring_fine_rule|
|aoc|renewal_remaining|
|aoc|stop_fines|
|aoc|stop_fines_time|
|aoc|target_copy|
|aoc|usr|
|aoc|xact_finish|
|aoc|xact_start|

=== copy ===

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.

^  ^ Fieldmapper::asset::copy ^
|acp|barcode|
|acp|call_number|
|acp|circ_as_type|
|acp|circ_lib|
|acp|circ_modifier|
|acp|circulate|
|acp|copy_number|
|acp|create_date|
|acp|creator|
|acp|deposit|
|acp|deposit_amount|
|acp|edit_date|
|acp|editor|
|acp|fine_level|
|acp|holdable|
|acp|id|
|acp|ischanged * |
|acp|isdeleted * |
|acp|isnew * |
|acp|loan_duration|
|acp|location|
|acp|opac_visible|
|acp|price|
|acp|ref|
|acp|stat_cat_entries * |
|acp|status|

=== record ===

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.

^  ^ Fieldmapper::metabib::virtual_record ^
|mvr|author * |
|mvr|call_numbers * |
|mvr|copy_count * |
|mvr|doc_id * |
|mvr|doc_type * |
|mvr|edition * |
|mvr|isbn * |
|mvr|ischanged * |
|mvr|isdeleted * |
|mvr|isnew * |
|mvr|online_loc * |
|mvr|pubdate * |
|mvr|publisher * |
|mvr|serials * |
|mvr|series * |
|mvr|subject * |
|mvr|synopsis * |
|mvr|tcn * |
|mvr|title * |
|mvr|types_of_resource * |

==== open-ils.circ.permit_checkout ====

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.

^  ^
| status |
| text |

==== open-ils.circ.checkout.barcode ====

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.

^  ^
| circ |
| copy |
| record |

=== circ ===

^  ^ Fieldmapper::action::circulation ^
|circ|checkin_lib|
|circ|checkin_staff|
|circ|checkin_time|
|circ|circ_lib|
|circ|circ_staff|
|circ|desk_renewal|
|circ|due_date|
|circ|duration|
|circ|duration_rule|
|circ|fine_interval|
|circ|id|
|circ|ischanged * |
|circ|isdeleted * |
|circ|isnew * |
|circ|max_fine|
|circ|max_fine_rule|
|circ|opac_renewal|
|circ|phone_renewal|
|circ|recuring_fine|
|circ|recuring_fine_rule|
|circ|renewal_remaining|
|circ|stop_fines|
|circ|stop_fines_time|
|circ|target_copy|
|circ|usr|
|circ|xact_finish|
|circ|xact_start|

===== Check In =====

^ Application ^ Method ^ Parameters ^ CVS ^
| open-ils.actor | open-ils.actor.user.fleshed.retrieve | session key, "au" id |  |
| open-ils.circ | open-ils.circ.checkin.barcode | session key, barcode, renewal?, backdate |  |
| open-ils.circ | open-ils.circ.hold.capture_copy.barcode | session key, item barcode, retrieve? | |

==== open-ils.actor.user.fleshed.retrieve ====
==== open-ils.circ.checkin.barcode ====
==== open-ils.circ.hold.capture_copy.barcode ====

===== Patron Search =====

^ Application ^ Method ^ Parameters ^ CVS ^
| open-ils.actor | open-ils.actor.patron.search.advanced | session key, criteria hash | 
| open-ils.actor | open-ils.actor.user.fleshed.retrieve | session key, au id |

==== open-ils.actor.patron.search.advanced ====

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.

==== open-ils.actor.user.fleshed.retrieve ====

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