<info>\r
\r
<title>Server Operations and Maintenance</title>\r
+ <indexterm><primary>receipt template editor</primary></indexterm>\r
<abstract>\r
<para>This chapter deals with basic server operations such as starting and stopping <application>Evergreen</application> as well wall \r
security, backing up and troubleshooting <application>Evergreen</application>.</para>\r
</section>\r
<section xml:id="backingup">\r
<title>Backing Up</title>\r
+ <indexterm><primary>databases</primary><secondary>backing up</secondary></indexterm>\r
+ \r
<para>Backing up your system files and data is a critical task for server and database administrators. \r
Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and\r
a complete catastrophe.</para> \r
</simplesect>\r
<simplesect>\r
<title>Backing up Evergreen Files</title>\r
+ <indexterm><primary>directories</primary><secondary>backing up</secondary></indexterm>\r
<para>When you deploy Evergreen, you will probably customize many aspects of your system including \r
the system configuration files, <application>Apache</application> configuration files, OPAC and Staff Client. In order to \r
protect your investment of time, you should carefully consider the best approach to backing up \r
</section>\r
<section xml:id="security">\r
<title>Security</title>\r
+ <indexterm><primary>security</primary></indexterm>\r
<para>As with an ILS and resource accessible from the world wide web careful consideration needs to be \r
given to the security of your <application>Evergreen</application> servers and database. While it is impossible to cover all aspects \r
of security, it is important to take several precautions when setting up production <application>Evergreen</application> site.</para>\r
</section>\r
<section xml:id="logfiles">\r
<title>Managing Log Files</title>\r
+ <indexterm><primary>logs</primary><secondary>managing</secondary></indexterm>\r
<para><application>Evergreen</application> comes with a sophisticated logging system, but it is important to manage the <application>OpenSRF</application> \r
and <application>Evergreen</application> logs. This section will provide a couple of log management techniques and tools.</para> \r
<simplesect>\r
- <title>Using the Log Rotate<indexterm><primary>logrotate</primary></indexterm> Utility to Manage Log Size</title> \r
+ <title>Using the <systemitem class="service">logrotate</systemitem> Utility to Manage Log Size</title> \r
+ <indexterm><primary>logs</primary><secondary>Log Rotate</secondary></indexterm>\r
<para>Fortunately, this is not a new problem for <systemitem class="osname">Unix</systemitem> administrators, and there are a number of ways of keeping your logs under control. \r
On <systemitem class="osname">Debian</systemitem> and <systemitem class="osname">Ubuntu</systemitem>, for example, \r
the <systemitem class="service">logrotate</systemitem> utility controls when old log files are compressed and a new log file is started. \r
</simplesect>\r
<simplesect>\r
<title>Changing Logging Level for <application>Evergreen</application></title>\r
+ <indexterm><primary>logs</primary><secondary>logging levels</secondary></indexterm>\r
<para>Change the Log Levels in your config files. Changing the level of logging will help \r
narrow down errors.</para> \r
<tip>\r
</section>\r
<section xml:id="InstallingPostgreSQL">\r
<title>Installing PostgreSQL from Source</title>\r
+ <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<para>Some <systemitem class="osname">Linux</systemitem> distributions, such as <systemitem class="osname">Debian Etch (4.0)</systemitem>, do not offer PostgreSQL \r
version 8.2 as an installable package. Before you continue, examine the software dependencies listed in <xref linkend="serversideinstall-software-dependencies"/> \r
to ensure that your Linux distribution supports the required version of PostgreSQL.</para>\r
</section>\r
<section xml:id="configuringPostgreSQL">\r
<title>Configuring PostgreSQL</title>\r
+ <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<para>The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values \r
and some suggested updates for several useful parameters:</para>\r
<table>\r
service interruptions. All of the steps in this chapter are to be completed from the command line.</para>\r
</abstract>\r
</info> \r
- <para>In the following instructions, you are asked to perform certain steps as either the root <systemitem class="username"></systemitem> or <systemitem class="username">opensrf</systemitem> user.</para>\r
+ <para>In the following instructions, you are asked to perform certain steps as either the <systemitem class="username">root</systemitem> or <systemitem class="username">opensrf</systemitem> user.</para>\r
<itemizedlist>\r
<listitem>Debian: To become the <systemitem class="username">root</systemitem> user, issue the <command>su</command> command and enter the password of the \r
<systemitem class="username">root</systemitem> user.</listitem>\r
</procedure>\r
</simplesect>\r
<simplesect>\r
- <title>Upgrading OpenSRF to 1.4</title><indexterm><primary>OpenSRF</primary><secondary>1.2</secondary></indexterm>\r
+ <title>Upgrading OpenSRF to 1.4</title><indexterm><primary>OpenSRF</primary></indexterm>\r
<procedure>\r
<step>\r
<para>As the <systemitem class="username">opensrf</systemitem> user, download and extract the source files for <application>OpenSRF</application> \r
these values for your distribution of Debian or Ubuntu:</para>\r
<itemizedlist>\r
<listitem>\r
- <para><option>debian-etch</option> for <systemitem class="osname">Debian Etch (4.0)</systemitem></para>\r
+ <para><option>debian-etch</option> for <systemitem class="osname">Debian Etch (4.0)</systemitem></para><indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
</listitem>\r
<listitem>\r
<para><option>debian-lenny</option> for <systemitem class="osname">Debian Lenny (5.0)</systemitem></para>\r
</listitem>\r
<listitem>\r
<para><option>ubuntu-hardy</option> for <systemitem class="osname">Ubuntu Hardy Heron \r
- (8.04)</systemitem></para>\r
+ (8.04)</systemitem></para><indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
</listitem>\r
<listitem>\r
<para><option>ubuntu-intrepid</option> for <systemitem class="osname">Ubuntu Intrepid Ibex \r
</screen> \r
</step>\r
<step>\r
- <para>As the postgres user on the PostgreSQL server, create a PostgreSQL user named <systemitem class="username">evergreen</systemitem> for the database cluster:</para>\r
+ <para>As the <systemitem class="username">postgres</systemitem> user on the PostgreSQL server, create a PostgreSQL user named <systemitem class="username">evergreen</systemitem> for the database cluster:</para>\r
<screen><userinput>createuser -P -s evergreen</userinput></screen>\r
<para>Enter the password for the new PostgreSQL superuser (<systemitem class="username">evergreen</systemitem>)</para> \r
</step> \r
<chapter xml:id="actiontriggers" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
<info>\r
- <title>Action Triggers</title> \r
+ <title>Action Triggers</title>\r
+ <indexterm><primary>action triggers</primary></indexterm> \r
</info>\r
<para>Action Triggers were introduced to Evergreen in 1.6. They allow administrators the ability to set up actions for specific events. They are useful for notification events such as \r
hold notifications.</para>\r
\r
<section xml:id="eventdefinitions">\r
<title>Event Definitions</title>\r
+ <indexterm><primary>action triggers</primary><secondary>event definitions</secondary></indexterm> \r
<para><guilabel>Event Definitions</guilabel> is the main tab and contains the key fields when working with action triggers. These fields include:</para>\r
<table xml:id="eventdefinitionstable">\r
<title>Action Trigger Event Definitions</title>\r
</table>\r
\r
<procedure>\r
- <title>Creating New Action Triggers</title>\r
+ <title>Creating Action Triggers</title>\r
+ <indexterm><primary>action triggers</primary><secondary>creating</secondary></indexterm> \r
<step>\r
<para>From the top menu, select\r
<menuchoice>\r
</section>\r
<section xml:id="Hooks">\r
<title>Hooks</title>\r
+ <indexterm><primary>action triggers</primary><secondary>hooks</secondary></indexterm>\r
<para><guilabel>Hooks</guilabel> define the Fieldmapper class in the core_type column off of which the rest of the field definitions <quote>hang</quote>.</para>\r
<table xml:id="Hookstable">\r
<title>Hooks</title>\r
</section> \r
<section xml:id="Reactors">\r
<title>Reactors</title>\r
+ <indexterm><primary>action triggers</primary><secondary>reactors</secondary></indexterm>\r
<para><guilabel>Reactors</guilabel> link the trigger definition to the action to be carried out.</para>\r
<table xml:id="Reactorstable">\r
<title>Action Trigger Reactors</title>\r
</section> \r
<section xml:id="Validators">\r
<title>Validators</title>\r
+ <indexterm><primary>action triggers</primary><secondary>validators</secondary></indexterm>\r
<para><guilabel>Validators</guilabel> set the validation test to be preformed to determine whether the action trigger is executed.</para>\r
<table xml:id="Validatorstable">\r
<title>Action Trigger Validators</title>\r
</section> \r
<section xml:id="ProcessingActionTriggers"> \r
<title>Processing Action Triggers</title>\r
+ <indexterm><primary>action triggers</primary><secondary>processing</secondary></indexterm>\r
<para>To run the action triggers, an Evergreen administrator will need to run the trigger processing script <command>/openils/bin/action_trigger_runner.pl \r
<option>--process-hooks</option> <option>--run-pending</option></command>. This should be set up as a cron job to run \r
periodically.</para> \r
</info>\r
<section xml:id="MakeCataloguedItemBookable">\r
<title>Make a Cataloged Item Bookable in Advance</title>\r
+ <indexterm><primary>booking reservation</primary><secondary>making a cataloged item bookable</secondary></indexterm>\r
<para>If their permission settings allow, staff members can make items bookable. Staff members\r
can do this in advance of a booking request, or they can do it on the fly.</para>\r
<para>If you know in advance of the request that an item will need to be booked, you can make\r
</section>\r
<section xml:id="MakeNon-CataloguedItemBookable">\r
<title>Create a Bookable Status for Non-Bibliographic Items</title>\r
+ <indexterm><primary>booking reservation</primary><secondary>non-bibliographic items</secondary></indexterm>\r
<para>Staff with the required permissions can create a bookable status for non-bibliographic\r
items. For example, staff can book conference rooms or laptops. You will be able to create\r
types of resources, specify the names of individual resources within each type, and set\r
</section>\r
<section xml:id="SettingBookingPermissions">\r
<title>Setting Booking Permissions</title>\r
+ <indexterm><primary>booking reservation</primary><secondary>setting booking permissions</secondary></indexterm>\r
<para>Administrators can set permissions so that staff members can view reservations, make\r
reservations, and make bibliographic or non-bibliographic items bookable.</para>\r
\r
<section xml:id="lsa-font">\r
<info>\r
<title>Global Font and Sound Settings</title>\r
+ <indexterm><primary>staff client</primary><secondary>fonts</secondary></indexterm>\r
+ \r
</info>\r
<para><guilabel>Global Font and Sound Settings</guilabel> apply to the current workstation\r
only. Use to turn staff client sounds on/off or to adjust the font size in the staff client\r
</step>\r
<step>\r
<informalfigure>\r
+ <indexterm><primary>staff client</primary><secondary>sounds</secondary></indexterm>\r
<para>To turn off the system sounds, like the noise that happens when a patron with a\r
block is retrieved check the <guilabel>disable sound</guilabel> box and click\r
<guibutton>Save to Disk</guibutton>. </para>\r
<section xml:id="lsa-printer">\r
<info>\r
<title>Printer Settings Editor</title>\r
+ <indexterm><primary>staff client</primary><secondary>printer settings</secondary></indexterm>\r
</info>\r
<para>Use the <guilabel>Printer Settings Editor</guilabel> to configure printer output for\r
each workstation.</para>\r
<section xml:id="lsa-closed">\r
<info>\r
<title>Closed Dates Editor</title>\r
+ <indexterm><primary>closed dates editor</primary></indexterm>\r
</info>\r
<para>These dates are in addition to your regular weekly closed days (see <xref\r
linkend="server-hours"/>). Both regular closed days and those entered in the\r
<listitem>\r
<formalpara>\r
<title>Due dates</title>\r
+ <indexterm><primary>closed dates editor</primary><secondary>due dates</secondary></indexterm>\r
<para>Due dates that would fall on closed days are automatically pushed forward to\r
the next open day. Likewise, if an item is checked out at 8pm, for example, and\r
would normally be due on a day when the library closes before 8pm, Evergreen\r
<listitem>\r
<formalpara>\r
<title>Overdue fines</title>\r
+ <indexterm><primary>closed dates editor</primary><secondary>fines</secondary></indexterm>\r
<para>Overdue fines are not charged on days when the library is closed.</para>\r
</formalpara>\r
</listitem>\r
<section xml:id="lsa-copy-locations">\r
<info>\r
<title>Copy Locations Editor</title>\r
+ <indexterm><primary>copy locations editor</primary></indexterm>\r
</info>\r
<procedure>\r
<step>\r
<section xml:id="lsa-library-settings">\r
<info>\r
<title>Library Settings Editor</title>\r
+ <indexterm><primary>library settings editor</primary></indexterm>\r
</info>\r
<para>With the <guilabel>Library Settings Editor</guilabel> Local System Admnistrators (LSAs)\r
can optionally customize Evergreen's behaviour for a particular library or library system.\r
<section xml:id="lsa-noncat">\r
<info>\r
<title>Non-Catalogued Type Editor </title>\r
+ <indexterm><primary>non-catalogued type editor</primary></indexterm>\r
</info>\r
\r
<para>This is where you configure your non-catalogued types that appear in the dropdown menu\r
<section xml:id="lsa-group-penalty">\r
<info>\r
<title>Group Penalty Thresholds</title>\r
+ <indexterm><primary>group penalty thresholds</primary></indexterm>\r
</info>\r
<para>Group Penalty Thresholds block circulation transactions for users who exceed maximum\r
check out limits, number of overdue items, or fines. Settings for your library are\r
\r
<simplesect xml:id="lsa-group-create">\r
<title>Creating local penalty thresholds</title>\r
-\r
+ <indexterm><primary>group penalty thresholds</primary><secondary>creating local penalty thresholds</secondary></indexterm>\r
<para>Local System Administrators can override the system defaults by creating local penalty\r
thresholds for selected patron groups.</para>\r
\r
<section xml:id="lsa-statcat">\r
<info>\r
<title>Statistical Categories Editor</title>\r
+ <indexterm><primary>statistical categories editor</primary></indexterm>\r
</info>\r
<para>This is where you configure your statistical categories (stat cats). Stat cats are a\r
way to save and report on additional information that doesn’t fit elsewhere in Evergreen's\r
</step>\r
</procedure>\r
<formalpara>\r
- <title>Copy stat cats</title>\r
+ <title>Copy Stat Cats</title>\r
+ <indexterm><primary>copy stat cats</primary></indexterm>\r
<para>The image above shows some examples of copy stat cats. You would see these when\r
editing items in the <guilabel>Copy Editor</guilabel>, also known as the <guilabel>Edit\r
Item Attributes</guilabel> screen. You might use copy stat cats to track books you\r
<informalfigure>\r
<formalpara>\r
<title>Patron stat cats</title>\r
+ <indexterm><primary>patron stat cats</primary></indexterm>\r
<para>Below are some examples of patron stat cats. Patron stat cats can be used to keep\r
track of information like the high school a patron attends, or the home library for a\r
consortium patron, e.g. Interlink. You would see these in the fifth screen of patron\r
<section xml:id="lsa-cash-reports">\r
<info>\r
<title>Cash Reports</title>\r
+ <indexterm><primary>cash reports</primary></indexterm>\r
</info>\r
<procedure>\r
<step>\r
\r
<info>\r
<title>Receipt Template Editor</title>\r
+ <indexterm><primary>receipt template editor</primary></indexterm>\r
</info>\r
\r
<para>This tip sheet will show you how to customize your receipts. This example will walk you\r
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
<info>\r
<title>Surveys</title>\r
+ <indexterm><primary>surveys</primary></indexterm>\r
</info>\r
<para>This section illustrates how to create a survey, shows where the survey responses are saved\r
in the patron record, and explains how to report on surveys.</para>\r
all interfaces. Only a few steps are required to enable or disable one or more languages.</para>\r
<simplesect>\r
<title>Enabling a Localization</title>\r
+ <indexterm><primary>languages</primary><secondary>enabling a localization</secondary></indexterm>\r
<para>To enable the translated labels for a given language to display in Evergreen, just populate the database with the translated labels and enable the localization. The \r
following example illustrates how to enable Canadian French (<emphasis role="bold">fr-CA</emphasis>) support in the database. These same steps can be used with any of the \r
languages bundled with Evergreen, or you can create and add your own localization.</para>\r
</simplesect>\r
<simplesect>\r
<title>Disabling a Localization</title>\r
+ <indexterm><primary>languages</primary><secondary>disabling a localization</secondary></indexterm>\r
<para>You might not want to offer all of the localizations that are preconfigured in Evergreen. If you choose to disable the dynamic labels for a locale, just delete those \r
entries from the table <literal>config.i18n_locale</literal> using the <command>psql</command> utility:</para>\r
<screen>\r
</info> \r
<section xml:id="migratingbibrecords">\r
<title>Migrating Bibliographic Records</title>\r
+ <indexterm><primary>migrating</primary><secondary>importing bibliographic records</secondary></indexterm>\r
<para>\r
One of the most important and challenging tasks is migrating your bibliographic records to a new system. The procedure may be different depending on the system from which you \r
are migrating and the content of the marc records exported from the existing system. The proecedures in this section deal with the process once the data from the existing system \r
http://svn.open-ils.org/trac/ILS/browser/branches/rel_1_6_1/Open-ILS/src/extras/import</link>).</para> \r
<simplesect>\r
<title>Converting MARC records to Evergreen BRE JSON format</title>\r
+ <indexterm><primary>BRE JSON</primary></indexterm>\r
<para>If you are starting with MARC records from your existing system or another source, use the marc2bre.pl script to create the JSON representation of a bibliographic \r
record entry (hence bre) in Evergreen. <filename>marc2bre.pl</filename> can perform the following functions:</para>\r
<itemizedlist> \r
</simplesect>\r
<simplesect>\r
<title>Converting Records for Import into PostgreSQL</title>\r
+ <indexterm><primary>migrating</primary><secondary>import into PostgreSQL</secondary></indexterm>\r
<para>Once you have your records in Evergreen's <systemitem>BRE JSON</systemitem> format, you then need to use <command>direct_ingest.pl</command> to convert the records \r
into the generic ingest <systemitem>JSON</systemitem> format for Open-ILS. \r
This step uses the <systemitem>open-ils.ingest</systemitem> application to extract the data that will be indexed in the database. </para>\r
</simplesect> \r
<simplesect>\r
<title>Adding Metarecords to the Database</title>\r
+ <indexterm><primary>migrating</primary><secondary>adding metarecords</secondary></indexterm>\r
<para>One you have loaded the records into PostgreSQL, you can create metarecord entries in the <link linkend="metabib.table.metarecord">metabib.metarecord</link> table by running the following <systemitem>SQL</systemitem>:</para>\r
<screen>\r
<userinput>psql evergreen</userinput>\r
</simplesect> \r
</section>\r
<section xml:id="migratingbibrecordcopies">\r
- <title>Adding Copies to Bibliographic Records</title> \r
+ <title>Adding Copies to Bibliographic Records</title>\r
+ <indexterm><primary>migrating</primary><secondary>adding copies</secondary></indexterm> \r
<para>Once you've loaded the bibliographic records in Evergreen, you can search and view the records in the staff client, but they will not be visible in the catalogue. By \r
default, bibliographic records will not be visible in the catalogue until you add a copy representing a physical manifestation of that resource. You can add a copy manually through \r
the staff client via the Holdings maintenance screen, but if you're bulk-importing MARC records you probably want to bulk load the associated copies, call numbers, and barcodes as \r
well.</para>\r
<simplesect>\r
<title>Importing volumes and copies from <systemitem>MARC21XML</systemitem> holdings</title>\r
+ <indexterm><primary>migrating</primary><secondary>importing volumes</secondary></indexterm> \r
<para>There is currently no simple method for importing holdings based on the contents of the MARC holdings field (852, as specified by \r
<link xml:href="http://www.loc.gov/marc/holdings/">http://www.loc.gov/marc/holdings/</link>). \r
However, a more or less automated method could be built that performs the following steps:</para>\r
</section>\r
<section xml:id="migratingpatrons">\r
<title>Migrating Patron Data</title>\r
+ <indexterm><primary>migrating</primary><secondary>importing patrons</secondary></indexterm>\r
<para>\r
This section will explain the task of migrating your patron data from comma delimited files<indexterm><primary>comma delimited files</primary></indexterm> into Evergreen. \r
It does not deal with the process of exporting from the non-Evergreen \r
</simplesect>\r
<simplesect>\r
<title>Batch Updating Patron Data</title>\r
+ <indexterm><primary>migrating</primary><secondary>batch updating patrons</secondary></indexterm>\r
<para>For academic libraries, doing batch updates to add new patrons to the Evergreen database is a critical task. The above procedures and \r
import script can be easily adapted to create an update script for importing new patrons from external databases. If the data import file contains only new patrons, then, \r
the above procedures will work well to insert those patrons. However, if the data load contains all patrons, a second staging table and a procedure to remove existing patrons from that second staging table may be required before importing the new patrons. Moreover, additional steps to update address information and perhaps delete \r
</simplesect> \r
</section>\r
<section xml:id="electronicresourcesvisible"> \r
- <title>Making electronic resources visible in the catalogue</title>\r
+ <title>Making Electronic Resources Visible in the Catalogue</title>\r
+ <indexterm><primary>migrating</primary><secondary>importing bibliographic records</secondary><tertiary>electronic resources </tertiary></indexterm>\r
<para>For electronic resources that should be visible in the catalogue without any copies, you must set the source column value in the record.biblio_entry row for the respective \r
bibliographic record to a value that matches the corresponding ID of the <link linkend="config.table.bib-source">config.bib_source</link> where the transcendant value is \r
<emphasis>TRUE</emphasis>. Here's a practical example:</para>\r
</section>\r
<section xml:id="emptydatabase">\r
<title>Restoring your Evergreen Database to an Empty State</title>\r
+ <indexterm><primary>databases</primary><secondary>restoring Evergreen to an empty state</secondary></indexterm>\r
+ <secondary>importing bibliographic records</secondary>\r
<para>If you've done a test import of records and you want to quickly get Evergreen back to a pristine state, you can create a clean Evergreen database schema by performing the \r
following:</para>\r
<procedure>\r
</section> \r
<section xml:id="hardwareconfigurations">\r
<info>\r
- <title>Server Hardware Configurations and Clustering</title><indexterm><primary>hardware</primary><secondary>clustering</secondary></indexterm>\r
+ <title>Server Hardware Configurations and Clustering</title>\r
+ <indexterm><primary>hardware</primary><secondary>clustering</secondary></indexterm>\r
</info>\r
<para>The hardware requirements for running a functional <application>Evergreen</application> server are minimal. It is also possible to scale up your evergreen configuration to be \r
spread your <application>Evergreen</application> resources and services over several or even many servers in a clustered approach for the purpose \r
<listitem><para>512Mb of RAM</para></listitem>\r
</itemizedlist>\r
<simplesect>\r
- <info>\r
- <title>Barcode Scanners</title> \r
- </info>\r
+ <title>Barcode Scanners</title> \r
<para><application>Evergreen</application> will work with virtually any barcode scanner<indexterm><primary>barcode scanner</primary></indexterm> – \r
if it worked with your legacy system it should work on <application>Evergreen</application>.</para>\r
</simplesect>\r
<title>Organizational Unit Types and Organizational Units</title>\r
<simplesect xml:id="orgtypes">\r
<title>Organizational Unit Types</title>\r
+ <indexterm><primary>organizational unit types</primary></indexterm>\r
<para>Organizational Unit Types are the terms used to refer to levels in the hierarchy of your \r
library system(s). Examples could include>All-Encompassing Consortium, Consortium Within a \r
Consortium, Library System, Branch, Bookmobile, Sub-Branch, Twig, etc.</para>\r
may be difficult once you have loaded records or users. </para></tip>\r
<para>The fields in the organizational unit type record include:</para>\r
<itemizedlist>\r
- <listitem>Type Name - The name of the organization unit type.</listitem>\r
- <listitem>Opac Label - This is the label displayed in the OPAC to describe the search \r
+ <listitem><guilabel>Type Name</guilabel> - The name of the organization unit type.</listitem>\r
+ <listitem><guilabel>Opac Label</guilabel> - This is the label displayed in the OPAC to describe the search \r
range and the copy count columns for results. They are <emphasis>range \r
relative</emphasis> labels.</listitem>\r
\r
- <listitem>Parent Type - The parent organizational unit type of this type.</listitem>\r
- <listitem>Can Have Volumes - Flag that allows an organizational unit of this type to contain \r
+ <listitem><guilabel>Parent Type</guilabel> - The parent organizational unit type of this type.</listitem>\r
+ <listitem><guilabel>Can Have Volumes</guilabel> - Flag that allows an organizational unit of this type to contain \r
Volumes/Call Numbers and thus Copies.</listitem>\r
- <listitem>Can Have Users - Flag that allows an Organizational unit of this type to be home to \r
+ <listitem><guilabel>Can Have Users</guilabel> - Flag that allows an Organizational unit of this type to be home to \r
Users.</listitem>\r
</itemizedlist>\r
<para>An organizational unit type can be added, edited, or removed using the staff client.</para>\r
</menuchoice>\r
</para>\r
<procedure>\r
- <title>Adding Organization Types<indexterm><primary>organization types</primary><secondary>adding</secondary></indexterm></title>\r
+ <title>Adding Organization Types<indexterm><primary>organizational unit types</primary><secondary>adding</secondary></indexterm></title>\r
<step><para>Select an organization type from the organization type tree on the left and \r
click <guibutton>New Child</guibutton>.</para></step>\r
<step><para>Make sure your new type is selected and edit the <guilabel>Type Name</guilabel>, \r
</step> \r
</procedure>\r
<procedure>\r
- <title>Deleting Organization Types<indexterm><primary>organization types</primary><secondary>deleting</secondary></indexterm></title>\r
+ <title>Deleting Organization Types</title>\r
+ <indexterm><primary>organizational unit types</primary><secondary>deleting</secondary></indexterm>\r
<step><para>Select the <guilabel>organization type</guilabel> from the <guilabel>Organization Type</guilabel> \r
tree.</para></step>\r
<step><para>Click <guibutton>Delete</guibutton>.</para></step>\r
\r
</procedure>\r
<procedure>\r
- <title>Editing Organization Types<indexterm><primary>organization types</primary><secondary>editing</secondary></indexterm></title>\r
+ <title>Editing Organization Types<indexterm><primary>organizational unit types</primary><secondary>editing</secondary></indexterm></title>\r
<step><para>Select the <guilabel>organization type</guilabel> you wish to edit from the \r
organization type tree.</para></step>\r
<step><para>Make the changes in the right pane.</para></step>\r
</simplesect>\r
\r
<simplesect xml:id="orgunits">\r
- <title>Organizational Units<indexterm><primary>organization units</primary></indexterm></title>\r
+ <title>Organizational Units</title>\r
+ <indexterm><primary>organizational units</primary></indexterm>\r
<abstract>\r
<para>Organizational Units are the specific instances of the organization unit types that \r
make up your library's hierarchy. These can include consortia, systems, branches, \r
</menuchoice>\r
</para>\r
<procedure>\r
- <title>Adding Organizational Units<indexterm><primary>organization units</primary><secondary>adding</secondary></indexterm></title>\r
+ <title>Adding Organizational Units</title>\r
+ <indexterm><primary>organization units</primary><secondary>adding</secondary></indexterm>\r
<step><para>Select an <guilabel>Organizational Unit</guilabel> from the organizational unit tree on the left and click \r
<guibutton>New Child</guibutton>.</para></step>\r
<step><para>Make sure your new unit is selected and edit the <guilabel>Organizational Unit \r
</step> \r
</procedure>\r
<procedure>\r
- <title>Deleting Organizational Units <indexterm><primary>organization units</primary><secondary>deleting</secondary></indexterm></title>\r
+ <title>Deleting Organizational Units</title>\r
+ <indexterm><primary>organization units</primary><secondary>deleting</secondary></indexterm>\r
<step><para>Select the <emphasis>organizational unit</emphasis> you wish to delete from the organizational unit tree in the left pane.</para></step>\r
<step><para>Click<guibutton>Delete</guibutton>.</para></step>\r
<step><para>Click <guibutton>OK</guibutton> on the warning alert box.</para></step>\r
</section>\r
<section xml:id="copystatus">\r
<title>Copy Status</title>\r
+ <indexterm><primary>copy status</primary></indexterm>\r
<para>To navigate to the copy status editor from the staff client menu, select \r
<menuchoice><guimenu>Admin</guimenu> <guisubmenu>Server Administration</guisubmenu> \r
<guisubmenu>Copy Statuses </guisubmenu></menuchoice></para>\r
</section>\r
<section xml:id="billingtypes">\r
<title>Billing Types</title>\r
+ <indexterm><primary>billing types</primary></indexterm>\r
<para>The billing types editor is used for creating, editing and deleting billing types.</para> \r
<para>To navigate to the billing types editor from the staff client menu, select \r
<menuchoice><guimenu>Admin</guimenu> <guisubmenu>Server Administration</guisubmenu> \r
<guisubmenu>Billing Types</guisubmenu></menuchoice></para>\r
<procedure>\r
<title>Adding Billing Types</title>\r
+ <indexterm><primary>billing types</primary><secondary>adding</secondary></indexterm>\r
<step><para>Click <guibutton>New Billing Type</guibutton>.</para></step>\r
<step><para>Enter the name of the billing type.</para></step>\r
<step><para>Select the <guilabel>Org Unit</guilabel> to use this billing type.</para></step>\r
</procedure>\r
<procedure>\r
<title>Deleting Billing Types</title>\r
+ <indexterm><primary>billing types</primary><secondary>deleting</secondary></indexterm>\r
<step><para>Check the check box of the billing type(s) you wish to delete.</para></step>\r
<step><para>Click <guibutton>Delete Selected</guibutton>.\r
<caution><para>The selected billing types will be deleted without a \r
</procedure>\r
<procedure>\r
<title>Editing Billing Types</title>\r
+ <indexterm><primary>billing types</primary><secondary>editing</secondary></indexterm>\r
<step><para>Double click on a billing types to open the editing window.</para></step> \r
<step><para>Make desired changes to the <guilabel>name</guilabel>, \r
<guilabel>Org Unit</guilabel> and <guilabel>Default Price</guilabel>.</para></step>\r
</section>\r
<section xml:id="circmodifiers">\r
<title>Circulation Modifiers</title>\r
+ <indexterm><primary>circulation modifiers</primary></indexterm>\r
<para>The circulation modifier editor is used to create, edit and delete modifier categories to control \r
circulation policies on specific groups of items.</para> \r
<para>To navigate to the circulation modifiers editor from the staff client menu, select \r
</para>\r
<procedure>\r
<title>Adding Circulation Modifiers</title>\r
+ <indexterm><primary>circulation modifiers</primary><secondary>adding</secondary></indexterm>\r
<step><para>Click <guibutton>New Circ Modifier</guibutton>.</para></step>\r
<step><para>Enter a <guilabel>Code</guilabel>, <guilabel>Name</guilabel> and \r
<guilabel>Description</guilabel>.</para></step>\r
</procedure>\r
<procedure>\r
<title>Deleting Circulation Modifiers</title>\r
+ <indexterm><primary>circulation modifiers</primary><secondary>deleting</secondary></indexterm>\r
<step><para>Check the check box(es) next to the circulation modifiers(s) you wish to \r
delete.</para></step>\r
<step><para>Click <guibutton>Delete Selected</guibutton> near the top of the page.\r
</procedure>\r
<procedure>\r
<title>Editing Circulation Modifiers</title>\r
+ <indexterm><primary>circulation modifiers</primary><secondary>editing</secondary></indexterm>\r
<step><para>Double click on the row of the circulation modifier you wish to \r
edit.</para></step> \r
<step><para>Make desired changes.</para></step>\r
</section>\r
<section xml:id="catalogingtemplates">\r
<title>Cataloging Templates</title>\r
+ <indexterm><primary>cataloging</primary><secondary>templates</secondary></indexterm>\r
<para>Cataloging templates are essential for making the cataloging process more efficient. Templates are used that that the basic structure of specific types of cataloging records can loaded when the cataloger adds a new record</para>\r
<procedure>\r
<title>Adding Cataloging Templates</title>\r
</section>\r
<section xml:id="relevancyrankings">\r
<title>Adjusting Search Relevancy Rankings</title>\r
+ <indexterm><primary>search relevancy</primary></indexterm>\r
<info>\r
<abstract>\r
<para>This section describes indexed field weighting and matchpoint weighting, which\r
</abstract>\r
</info>\r
<simplesect>\r
- <title>Indexed-field Weighting<indexterm><primary>relevancy</primary><secondary>indexed-field weighting</secondary></indexterm> </title>\r
+ <title>Indexed-field Weighting<indexterm><primary>search relevancy</primary><secondary>indexed-field weighting</secondary></indexterm> </title>\r
<para>Indexed-field weighting is configured in the Evergreen database in the weight column\r
of the <link linkend="config.table.metabib-field">config.metabib_field</link> table, which follows the other four columns in this table:\r
field_class, name, xpath, and format.</para>\r
<emphasis role="bold">jaguar</emphasis> in another indexed field. </para>\r
</simplesect>\r
<simplesect>\r
- <title>Match point Weighting<indexterm><primary>relevancy</primary><secondary>match point weighting</secondary></indexterm></title>\r
+ <title>Match point Weighting</title>\r
+ <indexterm><primary>search relevancy</primary><secondary>match point weighting</secondary></indexterm>\r
<para> Match point weighting provides another way to fine-tune Evergreen relevance ranking,\r
and is configured through floating-point multipliers in the multiplier column of the\r
search.relevance_adjustment table.</para>\r
</simplesect>\r
<simplesect>\r
<title>Combining Index Weighting and Match point Weighting</title>\r
+ <indexterm><primary>search relevancy</primary><secondary>combining index weighting and match point weighting</secondary></indexterm>\r
+ \r
<para>Index weighting and matchpoint weighting may be combined. The relevance boost of the combined \r
weighting is equal to the product of the two multiplied values. </para>\r
<para>If the relevance setting in the config.metabib_field were increased to 2, and the multiplier \r
</note>\r
</simplesect>\r
<simplesect>\r
- <title>Adjusting Relevancy for Keyword Searches<indexterm><primary>relevancy</primary><secondary>keyword searches</secondary></indexterm></title>\r
+ <title>Adjusting Relevancy for Keyword Searches</title>\r
+ <indexterm><primary>search relevancy</primary><secondary>keyword search adjusting</secondary></indexterm>\r
<para> Searching the out of the box <emphasis>keyword</emphasis> does not boost the ranking for terms appearing in, the title or subject fields since there is just one \r
keyword index which does not distinguish terms that appear in the title field from those in the notes field for example. In comparison, the title index is actually composed of \r
a number of separate indexes: title|proper, title|uniform, title|alternative, title|translated, etc, that collectively form the title index. You can see this in the \r
<para>Notifications can be set up for Holds, Overdue items and Predue items. There are two ways to configure notifications for each of these type of notifications.</para>\r
<section xml:id="Holdnotifications">\r
<title>Hold Notifications</title>\r
+ <indexterm><primary>notifications</primary><secondary>hold</secondary></indexterm>\r
<para>Hold notifications can be used that that library users are sent an email when their items are available for pickup. This notification is triggered when the item being held \r
is <emphasis>captured</emphasis> by a library staff member and the item is in the <emphasis>on holds shelf</emphasis> status. </para>\r
<simplesect> \r
<title>Overdue and Predue Notifications</title> \r
<para>Overdue and Predue email notifications can be used to inform users that they have materials which are overdue or to warn them that materials are almost overdue.</para> \r
<simplesect> \r
- <title>Activating Overdue Existing Overdue Action Triggers</title> \r
+ <title>Activating the Existing Overdue Action Triggers</title> \r
+ <indexterm><primary>notifications</primary><secondary>overdue</secondary><tertiary>activating action triggers</tertiary></indexterm>\r
<para>The easiest way to set up overdue notifications is to use the <link linkend="actiontriggers">Action Trigger</link> mechanism introduced in Evergreen 1.6.</para> \r
<procedure>\r
<step>\r
</simplesect> \r
<simplesect> \r
<title>Creating Overdue and Predue Notifications by Cloning Existing Action Triggers</title> \r
+ <indexterm><primary>notifications</primary><secondary>overdue</secondary><tertiary>creating using action triggers</tertiary></indexterm>\r
+ <indexterm><primary>notifications</primary><secondary>predue</secondary><tertiary>creating using action triggers</tertiary></indexterm>\r
<para>If you wish to add overdue notices for different periods of time or wish to create a predue notice simply clone an existing overdue note, give it a \r
unique <guilabel>Name</guilabel>, customize as needed. and save.</para>\r
<para>There are no pre-existing predue notices so they will need to be created by cloning an existing overdue notice. \r
due date, use the value <emphasis>-1 days</emphasis>.</para> \r
</simplesect>\r
<simplesect> \r
- <title>Creating Overdue and Predue Notices using the Evergreen Configuration File</title> \r
+ <title>Creating Overdue and Predue Notices using the Evergreen Configuration File</title>\r
+ <indexterm><primary>notifications</primary><secondary>overdue</secondary><tertiary>creating using the configuration file</tertiary></indexterm>\r
+ <indexterm><primary>notifications</primary><secondary>predue</secondary><tertiary>creating using the configuration file</tertiary></indexterm> \r
<para>It is also possible to create overdue and predue notices using the Evergreen configuration file <filename>/openils/conf/opensrf.xml</filename></para> \r
<procedure>\r
<step>\r
listed here:</para>\r
<table xml:id="serversideinstall-software-dependencies">\r
<title>Evergreen Software Dependencies</title>\r
+ <indexterm><primary>Evergreen software dependencies</primary></indexterm>\r
<tgroup align="left" cols="3" colsep="1" rowsep="1">\r
<colspec colname="Evergreen" colnum="1" colwidth="1.0*"/>\r
<colspec colname="OpenSRF" colnum="2" colwidth="1.0*"/>\r
take a final snapshot backup of your system(s). This can be the first in the series of regularly\r
scheduled system backups that you should probably also begin.</para>\r
<section xml:id="serversideinstallation-opensrf">\r
+ <indexterm><primary>OpenSRF</primary><secondary>installation</secondary></indexterm>\r
<title>Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or\r
<systemitem class="osname">Debian</systemitem></title>\r
+ <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
+ <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
<para>This section describes the installation of the latest version of the Open Service Request\r
Framework (OpenSRF), a major component of the Evergreen server-side software, on \r
<systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem>\r
</step>\r
<step>\r
<title>Download and Unpack Latest OpenSRF Version</title>\r
+ <indexterm><primary>OpenSRF</primary><secondary>download</secondary></indexterm>\r
<para>As the <systemitem class="username">opensrf</systemitem> user, download\r
and extract the latest version of OpenSRF. The latest version can be found here:\r
<ulink url="http://evergreen-ils.org/downloads/OpenSRF-1.4.0.tar.gz"></ulink></para>\r
<substeps>\r
<step>\r
<title>Configure OpenSRF</title>\r
+ <indexterm><primary>OpenSRF</primary><secondary>configure</secondary></indexterm>\r
<para>As the <systemitem class="username">opensrf</systemitem>\r
user, return to the OpenSRF build directory and use the\r
<command>configure</command> utility to prepare for the next\r
<filename>/etc/hosts</filename>.</para> <para>As the <systemitem class="username">root</systemitem> user, edit the file\r
<filename>/etc/hosts</filename> and add the following entries\r
for our example domains:</para>\r
+ <indexterm><primary>Jabber</primary></indexterm>\r
<screen>\r
<userinput>127.0.1.2 public.localhost public</userinput>\r
<userinput>127.0.1.3 private.localhost private</userinput>\r
</step>\r
<step>\r
<title>Stop the <systemitem class="service">ejabberd</systemitem> Service</title>\r
+ <indexterm><primary>ejabberd</primary></indexterm>\r
<para>As the <systemitem class="username">root</systemitem> user, stop the\r
<systemitem class="service">ejabberd</systemitem> service:</para>\r
<screen>\r
<para>In this section you will set up a special configuration file for each user\r
who will need to run the <command>srfsh</command> (pronounced <emphasis>surf\r
shell</emphasis>) utility.</para>\r
+ <indexterm><primary>srfsh</primary></indexterm>\r
<para>The software installation will automatically create\r
<command>srfsh</command>. This is a command line diagnostic tool for testing and\r
interacting with <application>OpenSRF</application>. It will be used in a future\r
<section xml:id="serversideinstallation-ubuntudebian">\r
<title>Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or\r
<systemitem class="osname">Debian</systemitem></title>\r
+ <indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
+ <indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
<para>This section outlines the installation process for the latest stable version of\r
Evergreen.</para>\r
<para>In this section you will download, unpack, install, configure and test the Evergreen\r
</tgroup>\r
</table>\r
</step>\r
- <step xml:id="serversideinstallation-postgresql-default">\r
+ <step xml:id="serversideinstallation-postgresql-default" performance="optional">\r
<title>(OPTIONAL) Install the PostgreSQL Server</title>\r
+ <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<para>Since the PostgreSQL server is usually a standalone server in multi-server\r
production systems, the prerequisite installer Makefile in the previous step\r
does not automatically install PostgreSQL. You must install the PostgreSQL server\r
</screen>\r
<para>For more information on installing Perl Modules vist the official\r
<link xl:href="http://www.cpan.org/">CPAN</link> site.</para>\r
+ <indexterm><primary>Perl</primary><secondary>CPAN</secondary></indexterm>\r
</step>\r
<step>\r
<title>Update the System Dynamic Library Path</title>\r
</screen>\r
</step>\r
<step performance="optional">\r
- <title>(OPTIONAL) Restart the PostgreSQL Server</title>\r
+ <title>Restart the PostgreSQL Server</title>\r
<para>If PostgreSQL is running on the same system as the rest of Evergreen, as\r
the <systemitem class="username">root</systemitem> user you must restart\r
PostgreSQL to re-read the new library paths just configured. If PostgreSQL is\r
</step>\r
<step>\r
<title>Create and Configure PostgreSQL Database</title>\r
+ <indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<para>In this step you will create the Evergreen database. In the commands\r
below, remember to adjust the path of the <emphasis role="bold">contrib</emphasis> repository to match your PostgreSQL server\r
layout. For example, if you built PostgreSQL from source the path would be\r
</step>\r
<step>\r
<title>Configure the Apache web server</title>\r
+ <indexterm><primary>web server</primary><secondary>Apache</secondary></indexterm>\r
<para>In this step you will configure the Apache web server to\r
support Evergreen software.</para>\r
<para>First, you must enable some built-in Apache modules and install\r
</listitem>\r
</itemizedlist>\r
</step>\r
- <step performance="optional">\r
- <title>(OPTIONAL) Apache Performance Modifications</title>\r
- <para>Some further configuration changes to Apache may be\r
- necessary for busy systems. These changes increase the\r
- number of Apache server processes that are started to\r
- support additional browser connections.</para>\r
- <para>As the <systemitem class="username">root</systemitem> \r
- user, edit the Apache configuration file\r
- <filename>/etc/apache2/apache2.conf</filename> and add the\r
- lines <literal>KeepAliveTimeout 1</literal> and\r
- <literal>MaxKeepAliveRequests 100</literal>, or modify any\r
- existing lines. Then locate the section related to\r
- <emphasis>prefork configuration</emphasis> and modify it\r
- to suit the load on your system:</para>\r
-<programlisting language="xml">\r
-<![CDATA[\r
-<IfModule mpm_prefork_module>\r
- StartServers 20\r
- MinSpareServers 5\r
- MaxSpareServers 15\r
- MaxClients 150\r
- MaxRequestsPerChild 10000\r
-</IfModule>\r
-]]>\r
-</programlisting>\r
- </step>\r
<step>\r
<title>Enable the Evergreen web site</title>\r
<para>Finally, you must enable the Evergreen web site. As the \r
</simplesect>\r
</section>\r
<section xml:id="serversideinstallation-virtual">\r
- <title>(OPTIONAL) Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>\r
+ <title>Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments</title>\r
<para>This section describes the installation of Evergreen software in so-called "virtualized"\r
software environments. Evergreen software runs as a native application on any of several\r
well-known x86 (32-bit) and x86-64 (64-bit) <systemitem class="osname">Linux</systemitem>\r
<link xl:href="http://virtualbox.org" xl:title="virtual box">http://virtualbox.org</link> and follow the on screen instructions to install the software.</para>\r
</simplesect>\r
<simplesect>\r
- <title>Installing <application>"VMware"</application> Virtualization Software</title>\r
+ <title>Installing VMware Virtualization Software</title>\r
+ <indexterm><primary>virtualization software</primary><secondary>VMware</secondary></indexterm>\r
<para>This section reviews installation of the\r
<application>"VMware"</application> application on <systemitem class="osname">WindowsXP Professional (SP2)</systemitem>. Find and Download the free virtual \r
machine software of from the VMware official website: <ulink url="http://downloads.vmware.com">http://downloads.vmware.com</ulink> and follow the on \r
\r
<procedure>\r
<title>VirtualBox Example</title>\r
+ <indexterm><primary>virtualization software</primary><secondary>VirtualBox</secondary></indexterm>\r
<step>\r
<para>Start VirtualBox for the first time and select\r
<menuchoice><guimenu>File</guimenu><guimenuitem>VirtualBox Media\r
</info>\r
<section xml:id="staffclientinstallation-installing-staffclient">\r
<title>Installing the Staff Client</title>\r
+ <indexterm><primary>staff client</primary><secondary>installing</secondary></indexterm>\r
<simplesect>\r
<title>Installing a Pre-Built Staff Client</title>\r
<para>You can install the pre-built Staff Client available for Windows, MAC or Linux.</para>\r
<simplesect>\r
<title>Installing on Windows</title>\r
+ <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Windows</tertiary></indexterm>\r
<para>A standard Microsoft Windows installer that contains the current version of the Staff Client is available from the downloads section of the Evergreen website \r
at <ulink url="http://www.evergreen-ils.org/downloads.php">http://www.evergreen-ils.org/downloads.php</ulink>. Download the Staff Client installer, then run it. \r
A screen that looks similar to this should appear:</para>\r
</simplesect>\r
<simplesect>\r
<title>Installing on Mac OS</title>\r
+ <indexterm><primary>staff client</primary><secondary>installing</secondary><tertiary>Mac OS</tertiary></indexterm>\r
<para>A Mac package that contains the current version of the Staff Client is available for use with XULRunner.</para>\r
<simplesect>\r
<title>Evergreen Indiana Pkg file [Evergreen v1.2.3.0]</title>\r
</simplesect>\r
<simplesect>\r
<title>Running directly using XULRunner</title>\r
+ <indexterm><primary>staff client</primary><secondary>XULRunner</secondary></indexterm>\r
+ <indexterm><primary>XULRunner</primary></indexterm>\r
<para>You must install an apropriate version of XULRunner to match the Evergreen version. See the following table for the recommended version of XULRunner:</para>\r
<table>\r
<title>Evergreen / XULRunner Dependencies</title>\r
</simplesect>\r
<simplesect xml:id="staffclientinstallation-remove-xulrunner">\r
<title>Removing previously installed XULRunner versions</title>\r
+ <indexterm><primary>XULRunner</primary><secondary>removing previous versions</secondary></indexterm>\r
<para>If you already have a newer version installed, per the release notes, you will need to remove the entire directory \r
<filename class="directory">/Library/Frameworks/XUL.framework</filename> before downgrading.</para>\r
<para>In addition, you may also need to remove the previous file <filename>/Library/Receipts/xulrunner-ver-mak.pkg</filename> .</para>\r
</simplesect>\r
<simplesect>\r
<title>Building the Staff Client on the Server</title>\r
+ <indexterm><primary>staff client</primary><secondary>building on the server</secondary></indexterm>\r
<para>A Linux Staff Client is automatically built on the server as part of the normal <emphasis>make install</emphasis> process for Evergreen server-side \r
software, using a procedure similar to this:</para>\r
<screen>\r
</procedure>\r
</simplesect>\r
<simplesect>\r
- <title>Using Wine to Install On Linux</title>\r
+ <title>Using Wine to Install on Linux</title>\r
+ <indexterm><primary>staff client</primary><secondary>using wine to install on Linux</secondary></indexterm>\r
<para>The Linux application <application>Wine</application> is another alternative if you wish to install the packaged Windows versions rather than building \r
the Staff Client manually. Wine is a Linux application that allows users to directly run Windows executables, and is a simple way for casual Linux users to use \r
the Staff Client. More information about Wine can be found at \r
</simplesect>\r
<simplesect xml:id="staffclientinstallation-workstationnames">\r
<title>Assigning Workstation Names</title>\r
+ <indexterm><primary>staff client</primary><secondary>assigning workstation names</secondary></indexterm>\r
<para>The Staff Client must be assigned to a library and given a unique name before it will connect fully to the Evergreen server. The only restriction is that \r
the workstation's name must be unique within the assigned library. Make sure to select a workstation name that you will remember later, and reflects the \r
role, purpose, and/or location of a particular computer. These names will come up later in statistical reporting, and can also be handy when troubleshooting.</para>\r
</simplesect>\r
<simplesect>\r
<title>Building the Staff Client</title>\r
+ <indexterm><primary>staff client</primary><secondary>building</secondary></indexterm>\r
<para>You can also manually build the Staff Client by using the <command>make</command> utility in the Staff Client source directory (e.g., the directory \r
<filename class="directory">/home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client</filename> for the current Evergreen version). There are a number of \r
possible options to manually build special versions of the Staff Client on a Linux system. Following is a list of environment variables that can be passed to \r
</simplesect>\r
<simplesect>\r
<title>Advanced Build Options</title>\r
+ <indexterm><primary>staff client</primary><secondary>building</secondary><tertiary>advanced build options</tertiary></indexterm>\r
<para>In addition to the basic options listed above, there are a number of advanced options for building the Staff Client. Most are target names for the \r
<command>make</command> utility and require that you build the Staff Client from its source directory. See the following table for a list of possible \r
<command>make</command> target keywords:</para>\r
<itemizedlist>\r
<listitem>\r
<para>Developer Build</para>\r
- <para>You can create a so-called "developer build" of the Staff Client by substituting "devbuild" for "build" when running <command>make</command>. \r
+ <para>You can create a so-called <emphasis>developer build</emphasis> of the Staff Client by substituting <option>devbuild</option> for <option>build</option> when running <command>make</command>. \r
The build will contain an extra configuration file that enables some developer options.</para>\r
<para>As the <systemitem class="username">opensrf</systemitem> user, run <command>make</command> from the Staff Client source directory:</para>\r
<screen>\r
</listitem>\r
<listitem>\r
<para>Compressed Javascript</para>\r
- <para>You can execute the Google "Closure Compiler" utility to automatically review and compress Javascript code after the build process completes, \r
+ <para>You can execute the Google <systemitem class="resource">Closure Compiler</systemitem> utility to automatically review and compress \r
+ Javascript code after the build process completes, \r
by substituting <option>compress-javascript</option> for "build" when running <command>make</command>. For more information see \r
<ulink url="http://code.google.com/closure/compiler/">Google Closure Compiler</ulink>.</para>\r
<para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para>\r
<userinput>cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client</userinput>\r
<userinput>make compress-javascript</userinput>\r
</screen>\r
- <para>You can also combine Javascript review and compression, and also perform a "developer build".</para>\r
+ <para>You can also combine Javascript review and compression, and also perform a <emphasis>developer build</emphasis>.</para>\r
<para>As the <systemitem class="username">opensrf</systemitem> user, run the following commands from the Staff Client source directory:</para>\r
<note><para>In the following <command>make</command> below, the order of options is important!</para></note>\r
<screen>\r
</simplesect>\r
<simplesect xml:id="staffclientinstallation-autoupdate">\r
<title>Staff Client Automatic Updates</title>\r
+ <indexterm><primary>staff client</primary><secondary>automatic updates</secondary></indexterm>\r
<para>It is possible to set up support for automatic Staff Client updates, either during the normal Evergreen server-side build process, or by manually building the \r
Staff Client with certain special options.</para>\r
- <simplesect>\r
- <title>WARNINGS</title>\r
+ <caution>\r
<para>Automatic update server certificate requirements are more strict than normal server requirements. Firefox and <application>XULRunner</application> will \r
both ignore any automatic update server that is not validated by a trusted certificate authority. Servers with exceptions added to force the Staff Client to \r
accept them <emphasis>WILL NOT WORK</emphasis>.</para>\r
</orderedlist>\r
<para>You can pre-install the signing key into the file <filename>install.rdf</filename> directly, or install it into a copy as \r
<filename>install.mccoy.rdf</filename>. If the latter exists it will be copied into the build instead of the original file <filename>install.rdf</filename>.</para>\r
- </simplesect>\r
+ </caution>\r
<simplesect>\r
<title>Autoupdate Host</title>\r
<para>The name of the automatic update host can be provided in either of two ways:</para>\r
</simplesect>\r
<simplesect>\r
<title>Building Updates</title>\r
+ <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building</tertiary></indexterm>\r
<para>Similar to building clients, the targets <option>generic-updates</option>, <option>win-updates</option>, <option>linux-updates</option>, and \r
<option>extension-updates</option> can be used individually \r
with <command>make</command> to build the update files for the Staff Client. To build all the targets at once, simply use the target <option>updates</option>.</para>\r
</simplesect>\r
<simplesect>\r
<title>Building updates with clients</title>\r
+ <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>building with clients</tertiary></indexterm>\r
<para>To save time and effort you can build updates and manual download clients at the same time by adding <option>-client</option> to each target \r
name. For instance, you can specify <option>win-updates-client</option>. You can also specify <option>updates-client</option> to build all the targets at once. \r
This does not work for <option>extension-updates</option>.</para>\r
</simplesect>\r
<simplesect>\r
<title>Activating the Update Server</title>\r
+ <indexterm><primary>staff client</primary><secondary>automatic updates</secondary><tertiary>activating the update server</tertiary></indexterm>\r
<para>This section reviews scripts associated with the update server, and requires some final adjustments to file permissions.</para>\r
<para>The Apache example configuration creates an "updates" directory that, by default, points to the directory \r
<filename class="directory">/openils/var/updates/pub</filename>. This directory contains one HTML file and several specially-named script files.</para>\r
</section>\r
<section xml:id="staffclientinstallation-running-staffclient">\r
<title>Running the Staff Client</title>\r
+ <indexterm><primary>staff client</primary><secondary>running</secondary><tertiary>linux</tertiary></indexterm>\r
<para>Run the Staff Client on a Linux system by using the application <application>XULRunner</application> (installed automatically and by default with Firefox version 3.0 and later \r
on Ubuntu and Debian distributions).</para>\r
<para>For example, if the source files for the Evergreen installation are in the directory <filename class="directory">/home/opensrf/[Evergreen Install Directory]/</filename>, start \r
</screen>\r
<simplesect xml:id="staffclientinstallation-proxy">\r
<title>Running the Staff Client over an SSH Tunnel</title>\r
+ <indexterm><primary>staff client</primary><secondary>running through an SSH tunnel</secondary></indexterm>\r
<para>The Staff Client can use an SSH tunnel as a SOCKS 5 proxy.</para>\r
<simplesect>\r
<title>Configuring a Proxy for the Staff Client</title>\r
Follow the steps in the troubleshooting guide in <xref linkend="troubleshooting"/>.</para>\r
</step>\r
<step>\r
- <para>Try to login from the <link linkend="staffclient-login">staff client</link></para>\r
+ <para>Try to login from the <link linkend="staffclient-login">staff client</link></para><indexterm><primary>staff client</primary><secondary>testing</secondary></indexterm>\r
</step>\r
<step xml:id="testing-opac">\r
<title>Testing the Catalog</title>\r
+ <indexterm><primary>OPAC</primary><secondary>testing</secondary></indexterm>\r
<para>By default, the OPAC will live at the URL <uri>http://my.domain.com/opac/</uri>.</para>\r
<para>Navigate to this URL and the front page of the OPAC should load. There is a basic text entry field with some extra search options. If you have any \r
problems loading this page, check the Apache error logs. If the page loads but does not function correctly, then check for possible javascript errors. We \r
<entry>Alpha-G Consulting</entry>\r
</row>\r
<row>\r
- <entry>Chris Sharp</entry>\r
- <entry>Georgia Public Library Service</entry>\r
- </row>\r
- <row>\r
<entry>Steve Sheppard</entry>\r
<entry>Open</entry>\r
</row>\r
would not be possible.</para> \r
</section>\r
<section xml:id="howtoParticipate">\r
- <title>How to Participate</title>\r
+ <title>How to Participate</title><indexterm><primary>Documentation Interest Group (DIG)</primary></indexterm>\r
<para>Contributing to documentation is an excellent way to support Evergreen, even if you are new to documentation. In fact, beginners often have a distinct advantage over the \r
experts, more easily spotting the places where documentation is lacking or where it is unclear.</para>\r
<para>We welcome your contribution with planning, writing, editing, testing, translating to DocBook, and other tasks. Whatever your background or experience we are keen to \r
<itemizedlist>\r
<listitem>Join the Evergreen documentation listserv: <link xl:href="http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation" \r
xl:title="Join the DIG listserv">list.georgialibraries.org/mailman/listinfo/open-ils-documentation</link> . This is the primary way we communicate with each other. \r
- Please send an email introducing yourself to the list.</listitem>\r
+ Please send an email introducing yourself to the list.</listitem><indexterm><primary>mailing lists</primary></indexterm>\r
<listitem>Add yourself to the <link xl:href="http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:digparticipants"> participant list</link> \r
if you have an Evergreen DokuWiki account, or send a request to <email>docs@evergreen-ils.org</email>.</listitem>\r
<listitem>Check out the <link xl:href="http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen-docs:outline">documentation outline</link> to see which areas need work, \r
<listitem>XML conversion – Convert existing documentation to DocBook format.</listitem>\r
<listitem>Editorial review – Ensuring the documentation is clear and follows <link xl:href="http://docs.evergreen-ils.org/style_guide/html/">Evergreen DIG style \r
guide</link> conventions.</listitem>\r
- <listitem>Style and Design – Edit the DocBook style sheets or post style tips and suggestions on the DIG list.</listitem>\r
+ <listitem>Style and Design – Edit the DocBook style sheets or post style tips and suggestions on the DIG list.</listitem><indexterm><primary>DocBook</primary></indexterm>\r
</itemizedlist>\r
</simplesect>\r
</section> \r
-<?xml version='1.0' encoding='UTF-8'?>
-<index xmlns='http://docbook.org/ns/docbook'>
-<title>Index</title>
-</index>
-
+<?xml version='1.0' encoding='UTF-8'?>\r
+<index xmlns='http://docbook.org/ns/docbook'>\r
+<title>Index</title>\r
+</index>\r
+\r
<glossdiv>\r
<title>A</title>\r
<glossentry id="Apache">\r
- <glossterm>Apache</glossterm>\r
+ <glossterm>Apache</glossterm><indexterm><primary>Apache</primary></indexterm>\r
<glossdef>\r
<para>Open-source web server software used to serve both static content and dynamic web pages in a secure and reliable way. More information is available at <ulink url="http://apache.org">apache.org</ulink>.</para>\r
</glossdef>\r
<glossdiv>\r
<title>B</title>\r
<glossentry id="Book Bags">\r
- <glossterm>Bookbags</glossterm>\r
+ <glossterm>Bookbags</glossterm><indexterm><primary>bookbags</primary></indexterm>\r
<glossdef>\r
<para>Bookbags are lists of items that can be used for any number of purposes. For example, to keep track of what books you have read, books you would like to read, \r
to maintain a class reading list, to maintain a reading list for a book club, to keep a list of books you would like for your birthday. There are an unlimited number \r
</glossdef>\r
</glossentry>\r
<glossentry id="CPAN">\r
- <glossterm>CPAN</glossterm>\r
+ <glossterm>CPAN</glossterm><indexterm><primary>Perl</primary><secondary>CPAN</secondary></indexterm>\r
<glossdef>\r
<para>An open-source archive of software modules written in <application>Perl</application>. More information is available at <ulink url="http://www.cpan.org">www.cpan.org</ulink>.</para>\r
</glossdef>\r
<glossdiv>\r
<title>D</title>\r
<glossentry id="Debian">\r
- <glossterm>Debian</glossterm>\r
+ <glossterm>Debian</glossterm><indexterm><primary>Linux</primary><secondary>Debian</secondary></indexterm>\r
<glossdef>\r
<para>One of the most popular open-source operating system using the <systemitem class="osname">Linux</systemitem> kernel that provides over 25000 useful precompiled software packages. Also known as <systemitem class="osname">Debian GNU/Linux</systemitem>. More information is available at <ulink url="http://www.debian.org">www.debian.org</ulink>.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry>\r
- <glossterm>Domain name</glossterm>\r
+ <glossterm>Domain name</glossterm><indexterm><primary>domain name</primary></indexterm>\r
<glossdef>\r
<para>A unique set of case-insensitive, alphanumeric strings separated by periods that are used to name organizations, web sites and addresses on the Internet (e.g.: <uri>www.esilibrary.com</uri>). Domain names can be reserved via third-party registration services, and can be associated with a unique IP address or suite of IP addresses.</para>\r
<glossseealso otherterm="ipaddress"/>\r
<glossdiv>\r
<title>E</title>\r
<glossentry id="ejabberd">\r
- <glossterm>ejabberd</glossterm>\r
+ <glossterm>ejabberd</glossterm><indexterm><primary>ejabberd</primary></indexterm>\r
<glossdef>\r
<para>An open-source Jabber/XMPP instant messaging server that runs under popular operating systems (e.g., <systemitem class="osname">Mac OSX</systemitem>, <systemitem class="osname">GNU/Linux</systemitem>, and <systemitem class="osname">Microsoft Windows</systemitem>). One popular use is to provide <application>XMPP</application> messaging services for a <application>Jabber</application> domain across an extendable cluster of cheap, easily-replaced machine nodes. More information is available at <ulink url="http://www.ejabberd.im/">http://www.ejabberd.im</ulink>.</para>\r
<glossseealso otherterm="Jabber"/>\r
<glossdiv>\r
<title>I</title>\r
<glossentry id="ipaddress">\r
- <glossterm>IP Address</glossterm>\r
+ <glossterm>IP Address</glossterm><indexterm><primary>IP Address</primary></indexterm>\r
<glossdef>\r
<para>(Internet Protocol address) A numerical label consisting of four numbers separated by periods (e.g., "192.168.1.15") assigned to individual members of networked computing systems. It uniquely identifies each system on the network and allows controlled communication between such systems. The numerical label scheme must adhere to a strictly defined naming convention that is currently defined and overseen by the Internet Corporation for Assigned Names and Numbers ("ICANN").</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="Item Buckets">\r
- <glossterm>Item/copy Buckets</glossterm>\r
+ <glossterm>Item/copy Buckets</glossterm><indexterm><primary>copy buckets</primary><seealso>item buckets</seealso></indexterm>\r
+ <indexterm><primary>item buckets</primary><seealso>copy buckets</seealso></indexterm>\r
<glossdef>\r
<para>Virtual <quote>containers</quote> to use in batch processing of item or copy records. They can be used to perform various cataloging/holdings maintenance tasks \r
in batch.</para>\r
<glossdiv>\r
<title>J</title>\r
<glossentry id="Jabber">\r
- <glossterm>Jabber</glossterm>\r
+ <glossterm>Jabber</glossterm><indexterm><primary>jabber</primary><seealso>XMPP</seealso></indexterm>\r
<glossdef>\r
<para>Now known as XMPP (eXtensible Messaging and Presence Protocol), it was originally named "Jabber".</para>\r
<glossseealso otherterm="XMPP"/>\r
<glossdiv>\r
<title>M</title>\r
<glossentry id="MARC">\r
- <glossterm>MARC</glossterm>\r
+ <glossterm>MARC</glossterm><indexterm><primary>MARC</primary></indexterm>\r
<glossdef>\r
<para>The MARC formats are standards for the representation and communication of bibliographic and related information in machine-readable form.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="MARCXML">\r
- <glossterm>MARCXML</glossterm>\r
+ <glossterm>MARCXML</glossterm><indexterm><primary>MARCXML</primary></indexterm>\r
<glossdef>\r
<para>Framework for working with MARC data in a XML environment.</para>\r
</glossdef>\r
</glossdef>\r
</glossentry>\r
<glossentry id="memcached">\r
- <glossterm>memcached</glossterm>\r
+ <glossterm>memcached</glossterm><indexterm><primary>memcached</primary></indexterm>\r
<glossdef>\r
<para>A general-purpose distributed memory caching system, usually with a client~server architecture spread over multiple computing systems. It reduces the number of \r
times a data source (e.g., a database) must be directly accessed by temporarily caching data in memory, therefore dramatically speeding up database-driven \r
<glossdiv>\r
<title>N</title>\r
<glossentry id="netaddr">\r
- <glossterm>Network address</glossterm>\r
+ <glossterm>Network address</glossterm><indexterm><primary>network address</primary><seealso>ip address</seealso></indexterm>\r
<glossdef>\r
<para>Also known as an IP address (Internet Protocol address).</para>\r
<glossseealso otherterm="ipaddress"/>\r
<glossdiv>\r
<title>O</title>\r
<glossentry id="OPAC">\r
- <glossterm>OPAC</glossterm>\r
+ <glossterm>OPAC</glossterm><indexterm><primary>OPAC</primary></indexterm>\r
<glossdef>\r
<para>The "Online Public Access Catalog"; an online database of a library's holdings; used to find resources in their collections; possibly searchable by keyword, \r
title, author, subject or call number.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="OpenSRF">\r
- <glossterm>OpenSRF</glossterm>\r
+ <glossterm>OpenSRF</glossterm><indexterm><primary>OpenSRF</primary></indexterm>\r
<glossdef>\r
<para>The "Open Scalable Request Framework" (pronounced 'open surf') is a stateful, decentralized service architecture that allows developers to create applications \r
for Evergreen with a minimum of knowledge of its structure.</para>\r
<glossdiv>\r
<title>P</title>\r
<glossentry id="PostgreSQL">\r
- <glossterm>PostgreSQL</glossterm>\r
+ <glossterm>PostgreSQL</glossterm><indexterm><primary>databases</primary><secondary>PostgreSQL</secondary></indexterm>\r
<glossdef>\r
<para>A popular open-source object-relational database management system that underpins Evergreen software.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="putty">\r
- <glossterm>Putty</glossterm>\r
+ <glossterm>Putty</glossterm><indexterm><primary>SSH</primary><secondary>Putty</secondary></indexterm>\r
<glossdef>\r
<para>A popular open-source telnet/ssh client for the Windows and Unix platforms. More information is available at \r
<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/putty/">http://www.chiark.greenend.org.uk/~sgtatham/putty/</ulink>.</para>\r
<glossdiv>\r
<title>S</title>\r
<glossentry id="SIP2">\r
- <glossterm></glossterm>\r
+ <glossterm>SIP</glossterm><indexterm><primary>SIP</primary></indexterm>\r
<glossdef>\r
<para>SIP, standing for Standard Interchange Protocol, was developed by the 3M Corporation to be a common protocol for data transfer between ILS' and third party \r
devices.</para>\r
</glossdef>\r
</glossentry>\r
- <glossentry id="srfsh">\r
+ <glossentry id="srfsh"><indexterm><primary>srfsh</primary></indexterm>\r
<glossterm>srfsh</glossterm>\r
<glossdef>\r
<para>A command language interpreter (shell) that executes commands read from the standard input. It is used to test the Open Service Request Framework (OpenSRF).</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="SRU">\r
- <glossterm>SRU</glossterm>\r
+ <glossterm>SRU</glossterm><indexterm><primary>SRU</primary></indexterm>\r
<glossdef>\r
<para>SRU is a standard XML-focused search protocol for Internet search queries, utilizing CQL (Contextual Query Language), a standard syntax for representing \r
queries.</para> \r
</glossdef>\r
</glossentry>\r
<glossentry id="ssh">\r
- <glossterm>SSH</glossterm>\r
+ <glossterm>SSH</glossterm><indexterm><primary>SSH</primary></indexterm>\r
<glossdef>\r
<para>An encrypted network protocol using public-key cryptography that allows secure communications between systems on an insecure network. Typically used to access \r
shell accounts but also supports tunneling, forwarding TCP ports and X11 connections, and transferring files.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="sshproxy">\r
- <glossterm>SSH proxy</glossterm>\r
+ <glossterm>SSH proxy</glossterm><indexterm><primary>SSH</primary><secondary>proxy</secondary></indexterm>\r
<glossdef>\r
<para> As used in Evergreen, a method of allowing one or more Staff Clients to communicate with one or more Evergreen servers over an insecure network by sending data through a secure SSH tunnel. It also buffers and caches all data travelling to and from Staff Clients to speed up access to resources on Evergreen servers.</para>\r
<glossseealso otherterm="ssh"/>\r
</glossdef>\r
</glossentry>\r
<glossentry id="sshtunnel">\r
- <glossterm>SSH tunnel</glossterm>\r
+ <glossterm>SSH tunnel</glossterm><indexterm><primary>SSH</primary><secondary>tunneling</secondary></indexterm>\r
<glossdef>\r
<para>An encrypted data channel existing over an SSH network connection. Used to securely transfer unencrypted data streams over insecure networks.</para>\r
<glossseealso otherterm="ssh"/>\r
</glossdef>\r
</glossentry>\r
<glossentry id="SSL Certificate">\r
- <glossterm>SSL Certificate</glossterm>\r
+ <glossterm>SSL Certificate</glossterm><indexterm><primary>SSL</primary></indexterm>\r
<glossdef>\r
<para>A special electronic document used to guarantee authenticity of a digital message. Also known as a "public key", or "identity" or "digital" certificate. It \r
combines an identity (of a person or an organization) and a unique public key to form a so-called digital signature, and is used to verify that the public key does, \r
<glossdiv>\r
<title>T</title>\r
<glossentry id="tunneling">\r
- <glossterm>tunneling</glossterm>\r
+ <glossterm>tunneling</glossterm><indexterm><primary>tunneling</primary><seealso>SSH tunneling</seealso></indexterm>\r
<glossdef>\r
<para>A method of encapsulating data provided in one network protocol (the "delivery" protocol), within data in a different network protocol (the "tunneling" \r
protocol). Used to provide a secure path and secure communications through an insecure or incompatible network. Can be used to bypass firewalls by communicating via \r
<glossdiv>\r
<title>U</title>\r
<glossentry id="Ubuntu">\r
- <glossterm>Ubuntu</glossterm>\r
+ <glossterm>Ubuntu</glossterm><indexterm><primary>Linux</primary><secondary>Ubuntu</secondary></indexterm>\r
<glossdef>\r
<para>A popular open-source operating system using the <systemitem class="osname">Linux</systemitem> kernel that was originally based on the \r
<systemitem class="osname">Debian GNU/Linux</systemitem> operating system. More information is available at <ulink url="http://www.ubuntu.com">www.ubuntu.com</ulink>.</para>\r
<glossdiv>\r
<title>V</title>\r
<glossentry id="virtualization">\r
- <glossterm>Virtualization</glossterm>\r
+ <glossterm>Virtualization</glossterm><indexterm><primary>virtualization</primary></indexterm>\r
<glossdef>\r
<para>A method of executing software in a special environment that is partitioned or separated from the real underlying hardware and software resources. In typical \r
usage, it allows a <emphasis>host</emphasis> operating system to encapsulate or emulate another operating system environment in such a way that the emulated environment \r
</glossdef>\r
</glossentry>\r
<glossentry id="virtualbox">\r
- <glossterm>VirtualBox</glossterm>\r
+ <glossterm>VirtualBox</glossterm><indexterm><primary>virtualization software</primary><secondary>VirtualBox</secondary></indexterm>\r
<glossdef>\r
<para>A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It can be installed on \r
<systemitem class="osname">Linux</systemitem>, <systemitem class="osname">Mac OS X</systemitem>, <systemitem class="osname">Windows</systemitem> or \r
</glossdef>\r
</glossentry>\r
<glossentry id="virtualpc">\r
- <glossterm>Virtual PC</glossterm>\r
+ <glossterm>Virtual PC</glossterm><indexterm><primary>virtualization software</primary><secondary>Virtual PC</secondary></indexterm>\r
<glossdef>\r
<para>A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It is installed on a Windows "host" operating system \r
and allows other "guest" (typically including <systemitem class="osname">Linux</systemitem> and <systemitem class="osname">Windows</systemitem>) operating systems to \r
</glossdef>\r
</glossentry>\r
<glossentry id="Volume Buckets">\r
- <glossterm>Volume Buckets</glossterm>\r
+ <glossterm>Volume Buckets</glossterm><indexterm><primary>volume buckets</primary></indexterm>\r
<glossdef>\r
<para>Virtual <quote>containers</quote> to use in batch processing of multiple volumes. They can be used to perform various cataloging/holdings maintenance tasks \r
in batch.</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="vmware">\r
- <glossterm>VMware</glossterm>\r
+ <glossterm>VMware</glossterm><indexterm><primary>virtualization software</primary><secondary>VMware</secondary></indexterm>\r
<glossdef>\r
<para>A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It can be installed on <systemitem class="osname">Linux</systemitem>, <systemitem class="osname">Mac OS X</systemitem>, <systemitem class="osname">Windows</systemitem> or <systemitem class="osname">Solaris</systemitem> "host" operating systems and allows other "guest" (typically including <systemitem class="osname">Linux</systemitem> and <systemitem class="osname">Windows</systemitem>) operating systems to be loaded and executed.</para>\r
<glossseealso otherterm="virtualization"/>\r
<glossdiv>\r
<title>W</title>\r
<glossentry id="wine">\r
- <glossterm>Wine</glossterm>\r
+ <glossterm>Wine</glossterm><indexterm><primary>Linux</primary><secondary>Wine</secondary></indexterm>\r
<glossdef>\r
<para>A popular open-source application that allows <systemitem class="osname">Linux</systemitem> and <systemitem class="osname">Unix</systemitem> systems to \r
run <systemitem class="osname">Windows</systemitem> executables. More information is available at <ulink url="http://www.winehq.org/">http://www.winehq.org/</ulink>.</para>\r
<glossdiv>\r
<title>X</title>\r
<glossentry id="xml">\r
- <glossterm>XML</glossterm>\r
+ <glossterm>XML</glossterm><indexterm><primary>XML</primary></indexterm>\r
<glossdef>\r
<para>The eXtensible Markup Language, a subset of SGML; a set of rules for encoding information in a way that is both human- and machine-readable. It is primarily \r
used to define documents but can also be used to define arbitrary data structures. It was originally defined by the World Wide Web Consortium (W3C).</para>\r
</glossdef>\r
</glossentry>\r
<glossentry id="XMPP">\r
- <glossterm>XMPP</glossterm>\r
+ <glossterm>XMPP</glossterm><indexterm><primary>XMPP</primary><seealso>jabber</seealso></indexterm>\r
<glossdef>\r
<para>An open-standard communications protocol, based on XML, used in message-oriented middleware. It supports the concept of a consistent <emphasis>domain</emphasis> \r
of message types that flow between software applications, possibly on different operating systems and architectures. More information is available at \r
</glossdef>\r
</glossentry>\r
<glossentry id="xpath">\r
- <glossterm>xpath</glossterm>\r
+ <glossterm>xpath</glossterm><indexterm><primary>xpath</primary></indexterm>\r
<glossdef>\r
<para>The XML Path Language, a query language based on a tree representation of an XML document. It is used to programmatically select nodes from an XML document and to \r
do minor computation involving strings, numbers and Boolean values. It allows you to identify parts of the XML document tree, to navigate around the tree, and to \r
</glossdef>\r
</glossentry>\r
<glossentry id="xul">\r
- <glossterm>XUL</glossterm>\r
+ <glossterm>XUL</glossterm><indexterm><primary>xUL</primary></indexterm>\r
<glossdef>\r
<para>The XML User Interface Language, a specialized interface language that allows building cross-platform applications that drive <application>Mozilla</application>\r
-based browsers such as <application>Firefox</application>. More information is available at \r
</glossdef>\r
</glossentry>\r
<glossentry id="xulrunner">\r
- <glossterm>xulrunner</glossterm>\r
+ <glossterm>xulrunner</glossterm><indexterm><primary>XULRunner</primary></indexterm>\r
<glossdef>\r
<para>A specialized run-time application environment that provides support for installing, upgrading and uninstalling <application>XUL</application> applications. \r
It operates with <application>Mozilla</application>-based applications such as the <application>Firefox</application> browser. More information is available at \r
<glossdiv>\r
<title>Y</title>\r
<glossentry id="YAZ">\r
- <glossterm>YAZ</glossterm>\r
+ <glossterm>YAZ</glossterm><indexterm><primary>yaz</primary></indexterm>\r
<glossdef>\r
<para>A programmers’ toolkit supporting the development of Z39.50/SRW/SRU clients and servers.</para> \r
</glossdef>\r
</glossentry>\r
- <glossentry id="yaz-client">\r
+ <glossentry id="yaz-client"><indexterm><primary>yaz</primary></indexterm>\r
<glossterm>yaz-client</glossterm>\r
<glossdef>\r
<para>Z39.50/SRU client for connecting to YAZ servers.</para>\r
<glossdiv>\r
<title>Z</title>\r
<glossentry id="Z39.50">\r
- <glossterm>Z39.50</glossterm>\r
+ <glossterm>Z39.50</glossterm><indexterm><primary>Z39.50</primary></indexterm>\r
<glossdef>\r
<para>A client–server protocol for searching and retrieving information from remote computer databases.</para>\r
</glossdef>\r
</info>\r
<orderedlist>\r
<listitem>\r
- <para><link linkend="serversideinstallation-opensrf">Install OpenSRF</link></para>\r
+ <para><link linkend="serversideinstallation-opensrf">Install OpenSRF</link></para><indexterm><primary>OpenSRF</primary></indexterm>\r
</listitem>\r
<listitem>\r
<para><link linkend="serversideinstallation-ubuntudebian">Install Evergreen server software</link></para>\r
</listitem>\r
<listitem>\r
- <para><link linkend="staffclientinstallation">Install Evergreen staff client</link></para>\r
+ <para><link linkend="staffclientinstallation">Install Evergreen staff client</link></para><indexterm><primary>staff client</primary></indexterm>\r
</listitem>\r
<listitem>\r
<para><link linkend="backingup">Establish a back up strategy for Evergreen data and files</link></para>\r
</listitem>\r
<listitem>\r
- <para><link linkend="configuringPostgreSQL">Configure PostgreSQL for better performance</link></para>\r
+ <para><link linkend="configuringPostgreSQL">Configure PostgreSQL for better performance</link></para><indexterm><primary>PostgreSQL</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="logfiles">Configure Evergreen error logging</link></para>\r
+ <para><link linkend="logfiles">Configure Evergreen error logging</link></para><indexterm><primary>logs</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="orgtypes">Set up organizational unit types</link></para>\r
+ <para><link linkend="orgtypes">Set up organizational unit types</link></para><indexterm><primary>organizational unit types</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="orgunits">Set up organizational units</link></para>\r
+ <para><link linkend="orgunits">Set up organizational units</link></para><indexterm><primary>organizational units</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="languagesandlocalization">Customize localization and languages</link> (optional)</para>\r
+ <para><link linkend="languagesandlocalization">Customize localization and languages</link> (optional)</para><indexterm><primary>localization and languages</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="circmodifiers">Add circ modifiers</link></para>\r
+ <para><link linkend="circmodifiers">Add circ modifiers</link></para><indexterm><primary>circulation modifiers</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="copystatus">Configure copy statuses</link></para>\r
+ <para><link linkend="copystatus">Configure copy statuses</link></para><indexterm><primary>copy status</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="catalogingtemplates">Add cataloguing templates</link></para>\r
+ <para><link linkend="catalogingtemplates">Add cataloguing templates</link></para><indexterm><primary>cataloguing </primary><secondary>templates</secondary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="permissions">Add user groups and assign permissions</link></para>\r
+ <para><link linkend="permissions">Add user groups and assign permissions</link></para><indexterm><primary>permissions</primary></indexterm>\r
</listitem>\r
<listitem>\r
<para><link linkend="lsa">Adjust various Local Administration Settings</link></para>\r
</listitem>\r
<listitem>\r
- <para>Adjust circulation policies and <link linkend="lsa-group-penalty">penalty threshholds</link> for groups</para>\r
+ <para>Adjust circulation policies and <link linkend="lsa-group-penalty">penalty threshholds</link> for groups</para><indexterm><primary>penalty threshholds</primary></indexterm>\r
</listitem>\r
<listitem>\r
<para><link linkend="admin-staff_accounts">Add staff users</link></para>\r
</listitem>\r
<listitem>\r
- <para><link linkend="Customizing_OPAC">Customize OPAC</link> as needed</para>\r
+ <para><link linkend="Customizing_OPAC">Customize OPAC</link> as needed</para><indexterm><primary>OPAC</primary><secondary>customizing</secondary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="migratingdata">Import data</link></para>\r
+ <para><link linkend="migratingdata">Import data</link></para><indexterm><primary>migrating</primary><secondary>importing data</secondary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="report_intro">Start the reporter service and set up reports</link></para>\r
+ <para><link linkend="report_intro">Start the reporter service and set up reports</link></para><indexterm><primary>reports</primary><secondary>starting</secondary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="notifications">Set up email notifications for holds and overdue items</link></para>\r
+ <para><link linkend="notifications">Set up email notifications for holds and overdue items</link></para><indexterm><primary>notifications</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="actiontriggers">Set up action triggers</link></para>\r
+ <para><link linkend="actiontriggers">Set up action triggers</link></para><indexterm><primary>action triggers</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="z3950">Set up z39.50 server</link> (optional)</para>\r
+ <para><link linkend="z3950">Set up Z39.50 server</link> (optional)</para><indexterm><primary>Z39.50</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="relevancyrankings">Adjust search relevancy settings</link> if required (optional)</para>\r
+ <para><link linkend="relevancyrankings">Adjust search relevancy settings</link> if required (optional)</para><indexterm><primary>search relevancy</primary></indexterm>\r
</listitem>\r
<listitem>\r
- <para><link linkend="sipserver">Install SIP server</link> (optional) - for communications with automated devices such as self check stations, autmated sorters and other devices using SIP</para>\r
+ <para><link linkend="sipserver">Install SIP server</link> (optional) - for communications with automated devices such as self check stations, autmated sorters and other devices using SIP</para><indexterm><primary>SIP</primary></indexterm>\r
</listitem>\r
</orderedlist>\r
</appendix>\r
</info> \r
<para>This documentation is just one way to learn about Evergreen and find solutions to Evergreen challenges. Below is a list of many other resources to help you find answers to almost any question \r
you might have.</para>\r
- <para><link xl:href="http://www.open-ils.org/">Evergreen Wiki</link> - Loads of information and the main portal to the Evergreen community.</para>\r
+ <para><link xl:href="http://www.open-ils.org/">Evergreen Wiki</link> - Loads of information and the main portal to the Evergreen community.</para><indexterm><primary>wiki</primary></indexterm>\r
<para><link xl:href="http://www.open-ils.org/listserv.php">Evergreen mailing lists</link> - These are excellent for initiating questions. There are several lists including:\r
<itemizedlist>\r
<listitem><link xl:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-general">General list</link> - General inquiries regarding Evergreen. If unsure about \r
- which list to use, this is a good stating point.</listitem>\r
+ which list to use, this is a good stating point.</listitem><indexterm><primary>mailing lists</primary></indexterm>\r
<listitem><link xl:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-dev">Developer list</link> - Technical questions should be asked here including \r
questions regarding installation. As well, patches can be submitted using this list and developer communication also takes place here. </listitem>\r
<listitem><link xl:href="http://libmail.georgialibraries.org/mailman/listinfo/open-ils-documentation">DIG list</link> - This list is used for questions and \r
- feedback regarding this documentation, the Documentation Interest Group and other documentation related ideas and issues.</listitem>\r
+ feedback regarding this documentation, the Documentation Interest Group and other documentation related ideas and issues.</listitem><indexterm><primary>Documentation Interest Group (DIG)</primary></indexterm>\r
</itemizedlist>\r
</para>\r
<para><link xl:href="http://evergreen-ils.org/blog/">Evergreen Blog</link> - Great for getting general news and updates about Evergreen. It is also an interesting historical read \r
<para><link xl:href="http://evergreen-ils.org/irc.php">Evergreen IRC channel</link> - Allows live chat. Many developers hang out here and will try to field technical questions. This \r
is often the quickest way to get a solution to a specific problem. Just remember that while the channel is open 24/7, there are times when no one is available in the channel. The most \r
active times for the IRC channel seem to be weekday afternoons (Eastern Standard Time). There is also an archive of logs from the chat sessions available on the \r
- <link xl:href="http://evergreen-ils.org/irc.php">IRC</link> page.</para>\r
+ <link xl:href="http://evergreen-ils.org/irc.php">IRC</link> page.</para><indexterm><primary>IRC chat</primary></indexterm>\r
<para><link xl:href="http://planet.evergreen-ils.org/">Evergreen related community blogs</link> - Evergreen related blog entries from the community.</para>\r
<para><link xl:href="http://rscel.evergreen-ils.org/">Resource Sharing Cooperative of Evergreen Libraries (RSCEL)</link> - Provides some technical documents and a means for the \r
- Evergreen community to collaborate with other libraries.</para>\r
+ Evergreen community to collaborate with other libraries.</para><indexterm><primary>Resource Sharing Cooperative of Evergreen Libraries (RSCEL)</primary></indexterm>\r
<para><link xl:href="http://evergreen-ils.org/dokuwiki/doku.php?id=evergreen_libraries">List of current Evergreen libraries</link> - Locate other libraries who are \r
using Evergreen.</para> \r
</appendix>\r
</abstract>\r
<section id="_introducing_opensrf">\r
<title>Introducing OpenSRF</title>\r
+ <indexterm><primary>OpenSRF</primary></indexterm>\r
<simpara>OpenSRF is a message routing network that offers scalability and failover\r
support for individual services and entire servers with minimal development and\r
deployment overhead. You can use OpenSRF to build loosely-coupled applications\r
Protocol</ulink> (XMPP, sometimes referred to as Jabber) - provides the base messaging\r
infrastructure between OpenSRF clients and services\r
</simpara>\r
+ <indexterm><primary>XMPP</primary></indexterm>\r
</listitem>\r
<listitem>\r
<simpara>\r
<simpara>\r
<ulink url="http://memcached.org">memcached</ulink> - provides the caching service\r
</simpara>\r
+ <indexterm><primary>memcached</primary></indexterm>\r
</listitem>\r
<listitem>\r
<simpara>\r
<ulink url="http://tools.ietf.org/html/rfc5424">syslog</ulink> - the standard UNIX logging\r
service\r
</simpara>\r
+ <indexterm><primary>syslog</primary></indexterm>\r
</listitem>\r
</itemizedlist>\r
<simpara>Unfortunately, the\r
The recommended option for would-be developers of another language binding is\r
to use the Python implementation as the cleanest basis for a port to another\r
language.</simpara>\r
+ <indexterm><primary>Python</primary></indexterm>\r
</simplesect>\r
</section>\r
<section id="writing_an_opensrf_service">\r
this for a new service if the new service needs to be accessible via the\r
public router.\r
</simpara>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>\r
</listitem>\r
</itemizedlist>\r
<simpara>Begin by defining the service itself in <literal>opensrf.xml</literal>. To register the\r
<literal>opensrf.simple-text</literal> service, add the following section to the <literal><apps></literal>\r
element (corresponding to the XPath <literal>/opensrf/default/apps/</literal>):</simpara>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>\r
<programlisting language="xml" linenumbering="unnumbered">\r
<apps>\r
<opensrf.simple-text> <co id="CO1-1"/> \r
</simplesect>\r
<simplesect id="_calling_an_opensrf_method">\r
<title>Calling an OpenSRF method</title>\r
+ <indexterm><primary>srfsh</primary></indexterm>\r
<simpara>OpenSRF clients in any supported language can invoke OpenSRF services in any\r
supported language. So let’s see a few examples of how we can call our fancy\r
new <literal>opensrf.simple-text.reverse()</literal> method:</simpara>\r
relationships to other objects, the permissions required to create, read,\r
update, or delete objects of that type, and the database table or view on which\r
they are based.</simpara>\r
+ <indexterm><primary>Fieldmapper</primary></indexterm>\r
<simpara>The Evergreen fieldmapper offers a great deal of convenience for working with\r
complex system objects beyond the basic mapping of classes to database\r
schemas. Although the result is passed over the wire as a JSON object\r
</simplesect>\r
<simplesect id="_caching_results_one_secret_of_scalability">\r
<title>Caching results: one secret of scalability</title>\r
+ <indexterm><primary>search results</primary><secondary>caching</secondary></indexterm>\r
<simpara>If you have ever used an application that depends on a remote Web service\r
outside of your control — say, if you need to retrieve results from a\r
microblogging service — you know the pain of latency and dependability (or the\r
</section>\r
<section id="_getting_under_the_covers_with_opensrf">\r
<title>OpenSRF Communication Flows</title>\r
+ <indexterm><primary>OpenSRF</primary><secondary>Communication Flows</secondary></indexterm>\r
<simpara>Now that you have seen that it truly is easy to create an OpenSRF service, we\r
can take a look at what is going on under the covers to make all of this work\r
for you.</simpara>\r
</simplesect>\r
<simplesect id="_opensrf_communication_flows_over_xmpp">\r
<title>OpenSRF communication flows over XMPP</title>\r
+ <indexterm><primary>XMPP</primary></indexterm>\r
<simpara>In a minimal OpenSRF deployment, two XMPP users named "router" connect to the\r
XMPP server, with one connected to the private XMPP domain and one connected to\r
the public XMPP domain. Similarly, two XMPP users named "opensrf" connect to\r
</simplesect>\r
<simplesect id="OpenSRFOverHTTP">\r
<title>OpenSRF communication flows over HTTP</title>\r
+ <indexterm><primary>HTTP</primary><secondary>translator</secondary></indexterm>\r
<simpara>In some contexts, access to a full XMPP client is not a practical option. For\r
example, while XMPP clients have been implemented in JavaScript, you might\r
be concerned about browser compatibility and processing overhead - or you might\r
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>\r
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
- xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="UsingtheBookingModule">\r
- <info>\r
- <title>Using the Booking Module</title>\r
- <abstract>\r
- <para>The Evergreen booking module is included in Evergreen 1.6.1.x and above. The following chapter will help staff create reservations for cataloged and non-\r
- bibliographic items; create pull lists for reserved items; capture resources; and pick up and\r
- return reservations.\r
-</para>\r
- </abstract>\r
- </info> \r
- <section xml:id="CreatingaReservation">\r
- <title>Creating a Booking Reservation</title>\r
- <para>Only staff members can create reservations. To initiate a reservation, staff can \r
- <itemizedlist>\r
- <listitem>search the catalog,</listitem>\r
- <listitem>enter a patron record,</listitem>\r
- <listitem>or use the booking module.</listitem>\r
- </itemizedlist>\r
- </para>\r
- <simplesect>\r
- <title>Search the catalog to create a reservation</title> \r
- <procedure>\r
- <step><para>In the staff client, select <menuchoice><guimenu>Search</guimenu> <guimenuitem>Search the Catalog</guimenuitem>\r
- </menuchoice></para></step>\r
- <step><para>Search for the item to be booked.</para></step>\r
- <step><para>Click <guibutton>Submit Search</guibutton>.</para></step>\r
- <step><para>A list of results will appear. Select the title of the item to be reserved.</para></step>\r
- <step><para>After clicking the title, the record summary appears. Beneath the record summary,\r
- the copy summary will appear. In the <guilabel>Actions</guilabel> column, select <guibutton>Copy Details</guibutton>.</para></step>\r
-\r
- <step><para>The <guilabel>Copy Details</guilabel> will appear in a new row. In the <guilabel>barcode</guilabel> column, click the <guilabel>book now</guilabel> \r
- link.</para></step>\r
- <step><para> A screen showing the title and barcodes of available copies will appear.</para></step>\r
- <step><para>Enter the user’s barcode in the <guilabel>Reserve to patron barcode</guilabel> box. If the patron barcode\r
- does not exist, a pop up box will appear to alert you to the error. After entering the\r
- patron’s barcode, the user’s existing reservations will appear at the bottom of the\r
- screen.</para></step>\r
- <step><para> To the right, a section titled, <guilabel>I need this resource...</guilabel> will allow you to set the dates and\r
- times for which the item should be reserved. If the date/time boxes appear in red,\r
- then the date and time set is incorrect. For example, if the time for which the\r
- reservation is set has already passed, the boxes will appear in red. The times must be\r
- set correctly for the reservation to be accomplished. If the item has already been\r
- reserved at the time for which you are trying to reserve the item, then you will receive\r
- an error message.</para></step>\r
- <step><para>Finally, select the barcode of the item that you want to reserve. If multiple copies of\r
- the item exist, choose the barcode of the copy that you want to reserve, and click\r
- <guibutton>Reserve Selected</guibutton>. If you do not select a barcode, and you click <guibutton>Reserve Selected</guibutton>, you\r
- will receive an error message. If you do not have a preference, you do not have to\r
- select a barcode, and you may click <guibutton>Reserve Any</guibutton>. One of the barcodes will be pulled\r
- from the list. </para>\r
- <note><para>An item must have a status of available or reshelving in order to\r
- be targeted for a reservation. If the item is in another status, the reservation will fail.</para></note></step>\r
- <step><para> After you have made the reservation, a message will confirm that the action succeeded. Click <guibutton>OK</guibutton>.</para></step>\r
- <step><para>The screen will refresh, and the reservation will appear below the user’s name.</para></step>\r
- </procedure>\r
- </simplesect> \r
- <simplesect>\r
- <title>Enter a patron’s record to create a reservation</title>\r
- <procedure> \r
- <step><para>Enter the barcode or patron information, and click <guibutton>Search</guibutton> to retrieve the patron’s record.</para></step>\r
- <step><para>The match(es) should appear in the right pane. Click the desired patron’s name. In the\r
- left panel, a summary of the patron’s information will appear. Click the <guibutton>Retrieve\r
- Patron</guibutton> button in the right corner to access more options in the patron’s record.</para></step>\r
- <step><para>Eight buttons will appear in the top right corner. Select <menuchoice><guimenu>Other </guimenu><guimenuitem>Booking</guimenuitem>\r
- </menuchoice> to create, cancel, pick up, and return reservations.</para></step>\r
- <step><para>The <guilabel>Copy Details</guilabel> will appear in a new row. In the <guilabel>barcode</guilabel> column, click the <guilabel>book now</guilabel> \r
- link.</para></step>\r
- <step><para> A screen showing the title and barcodes of available copies will appear.</para></step>\r
- <step><para>Enter the user’s barcode in the <guilabel>Reserve to patron barcode</guilabel> box. If the patron barcode\r
- does not exist, a pop up box will appear to alert you to the error. After entering the\r
- patron’s barcode, the user’s existing reservations will appear at the bottom of the\r
- screen.</para></step>\r
- <step><para> To the right, a section titled, <guilabel>I need this resource...</guilabel> will allow you to set the dates and\r
- times for which the item should be reserved. If the date/time boxes appear in red,\r
- then the date and time set is incorrect. For example, if the time for which the\r
- reservation is set has already passed, the boxes will appear in red. The times must be\r
- set correctly for the reservation to be accomplished. If the item has already been\r
- reserved at the time for which you are trying to reserve the item, then you will receive\r
- an error message.</para></step>\r
- <step><para>Finally, select the barcode of the item that you want to reserve. If multiple copies of\r
- the item exist, choose the barcode of the copy that you want to reserve, and click\r
- <guibutton>Reserve Selected</guibutton>. If you do not select a barcode, and you click <guibutton>Reserve Selected</guibutton>, you\r
- will receive an error message. If you do not have a preference, you do not have to\r
- select a barcode, and you may click <guibutton>Reserve Any</guibutton>. One of the barcodes will be pulled\r
- from the list. </para>\r
- <note><para>An item must have a status of available or reshelving in order to\r
- be targeted for a reservation. If the item is in another status, the reservation will fail.</para></note></step>\r
- <step><para> After you have made the reservation, a message will confirm that the action succeeded. Click <guibutton>OK</guibutton>.</para></step>\r
- <step><para>The screen will refresh, and the reservation will appear below the user’s name.</para></step>\r
- </procedure>\r
- </simplesect>\r
- <simplesect>\r
- <title>Use the booking module to create a reservation</title>\r
- <procedure> \r
- <step><para>Select <menuchoice><guimenu>Booking</guimenu><guimenuitem>Create or Edit Reservations</guimenuitem></menuchoice></para></step>\r
- <step><para>Enter the barcode of the item and click <guibutton>Next</guibutton>.</para></step>\r
- <step><para>A screen showing the name of the available resource will appear.</para></step>\r
- <step><para>Enter the user’s barcode in the <guilabel>Reserve to patron barcode</guilabel> box. If the patron barcode\r
- does not exist, a pop up box will appear to alert you to the error. After entering the\r
- patron’s barcode, the user’s existing reservations will appear.</para></step>\r
- <step><para>To the right, a section titled, <guilabel>I need this resource...</guilabel> will allow you to set the dates and\r
- times for which the item should be reserved. If the date/time boxes appear in red,\r
- then the date and time set is incorrect. For example, if the time for which the\r
- reservation is set has already passed, the boxes will appear in red. The times must be\r
- set correctly for the reservation to be accomplished. If the resource has already been\r
- reserved at the time for which you want to reserve the item, then the item will\r
- disappear.</para></step>\r
- <step><para>Finally, select the resource that you want to reserve. If multiple items or rooms exist,\r
- choose the resource that you want to reserve, and click <guibutton>Reserve Selected</guibutton>. If you do\r
- not select a resource, and you click <guibutton>Reserve Selected</guibutton>, you will receive an error\r
- message. If you do not have a preference, you may click <guibutton>Reserve Any</guibutton>, and one of the\r
- resources will be pulled from the list.</para></step>\r
- <step><para>After you have made the reservation, a message will confirm that the action \r
- succeeded. Click <guibutton>OK</guibutton>.</para></step>\r
- <step><para>The screen will refresh, and the reservation will appear below the user’s name.</para></step>\r
- </procedure>\r
- </simplesect>\r
- </section>\r
- <section xml:id="CancellingaReservation">\r
- <title>Cancelling a Reservation</title>\r
- <para>Staff members can cancel a patron’s reservation through the Create or Cancel Reservations tab available in a patron’s record. Staff members can also cancel a \r
- reservation immediately after it has been made.</para>\r
- <simplesect> \r
- <title>Enter the patron’s record to cancel a reservation</title> \r
- <procedure> \r
- <step><para>Search for and retrieve a patron’s record.</para></step>\r
- <step><para>Select <menuchoice><guimenu>Other</guimenu><guisubmenu>Booking</guisubmenu><guimenuitem>Create or Cancel Reservations</guimenuitem></menuchoice>.</para></step>\r
- <step><para>The existing reservations will appear at the bottom of the screen.</para></step>\r
- <step><para>To cancel a reservation, highlight the reservation that you want to cancel. Click <guibutton>Cancel Selected</guibutton>.</para></step>\r
- <step><para>A pop-up window will confirm that you cancelled the reservation. Click <guibutton>OK</guibutton>.</para></step>\r
- <step><para>The screen will refresh, and the cancelled reservation will disappear.</para></step>\r
- <step><para> To the right, a section titled, <guilabel>I need this resource...</guilabel> will allow you to set the dates and\r
- times for which the item should be reserved. If the date/time boxes appear in red,\r
- then the date and time set is incorrect. For example, if the time for which the\r
- reservation is set has already passed, the boxes will appear in red. The times must be\r
- set correctly for the reservation to be accomplished. If the item has already been\r
- reserved at the time for which you are trying to reserve the item, then you will receive\r
- an error message.</para></step>\r
- </procedure>\r
- </simplesect>\r
- <simplesect> \r
- <title>Cancel a reservation immediately after it has been made</title> \r
- <procedure> \r
- <step><para>Create the reservation.</para></step>\r
- <step><para>Follow steps four through six in the section, Enter the patron’s record to cancel a reservation, to cancel the reservation.</para></step>\r
- <step><para>The existing reservations will appear at the bottom of the screen.</para></step>\r
- </procedure>\r
- </simplesect>\r
- </section>\r
- <section xml:id="CreatingaPullList">\r
- <title>Creating a Pull List</title>\r
- <para>Staff members can create a pull list to retrieve items from the stacks.</para>\r
- <procedure> \r
- <step><para>To create a pull list, select <menuchoice><guimenu>Booking</guimenu><guimenuitem>Pull List</guimenuitem></menuchoice>.</para></step>\r
- <step><para>To find a pull list for your library, select a library from the dropdown box adjacent to See pull list for library.</para></step>\r
- <step><para>You can decide how many days in advance you would like to select reserved items. Enter the number of days in the box adjacent to <guilabel>Generate \r
- list</guilabel> for this many days hence. For example, if you would like to pull items that are needed today, you can enter <userinput>1</userinput> in the box, and you will retrieve items that need to be pulled today.</para></step>\r
- <step><para>Click <guibutton>Fetch</guibutton> to retrieve the pull list.</para></step> \r
- <step><para>The pull list will appear. Click Print to print the pull list.</para></step>\r
- </procedure>\r
- </section>\r
- <section xml:id="CapturingItemsforReservations">\r
- <title>Capturing Items for Reservations</title>\r
- <para>Staff members can capture items for reservations.</para>\r
- <procedure> \r
- <step><para>In the staff client, select <menuchoice><guimenu>Booking</guimenu><guimenuitem>Capture Resources</guimenuitem></menuchoice>.</para></step>\r
- <step><para>Enter the barcode of the items to be captured. Click <guibutton>Capture</guibutton>.</para></step>\r
- <step><para>A Capture Succeeded message will appear to the right. Information about the item will appear below the message. You can print this \r
- information as a receipt and add it to the item if desired.</para></step>\r
- </procedure>\r
- </section>\r
- <section xml:id="PickingUpReservations">\r
- <title>Picking Up Reservations</title>\r
- <para>Staff members can help users pick up their reservations.</para>\r
- <procedure> \r
- <step><para>In the staff client, select <menuchoice><guimenu>Booking</guimenu><guimenuitem>Pick Up Reservations</guimenuitem></menuchoice></para></step>\r
- <step><para>Enter the user’s barcode. Click <guibutton>Go</guibutton>.</para></step>\r
- <step><para>The title available for pickup will appear. Highlight the title of the item to pick up, and click <guibutton>Pick Up</guibutton>.</para></step>\r
- <step><para>The screen will refresh to show that the patron has picked up the reservation.</para></step>\r
- </procedure>\r
- </section>\r
- <section xml:id="ReturningReservations">\r
- <title>Returning Reservations</title>\r
- <para>Staff members can help users return their reservations.</para>\r
- <procedure> \r
- <step><para>In the staff client, select <menuchoice><guimenu>Booking</guimenu><guimenuitem>Return Reservations</guimenuitem></menuchoice>.</para></step>\r
- <step><para>You can return the item by patron or item barcode. Choose <guimenuitem>Resource</guimenuitem> or <guimenuitem>Patron</guimenuitem>, enter the \r
- barcode, and click <guibutton>Go</guibutton>.</para></step>\r
- <step><para>A pop up box will tell you that the item was returned. Click <guibutton>OK</guibutton>.</para></step>\r
- <step><para>The screen will refresh to show the reservations that remain out and the resources that have been returned.</para></step>\r
- </procedure>\r
- </section>\r
-</chapter>\r
- \r
</note> \r
<section xml:id="ColorScheme">\r
<title>Change the Color Scheme</title>\r
+ <indexterm><primary>OPAC</primary><secondary>customizing</secondary><tertiary>changing the color scheme</tertiary></indexterm>\r
<para>To change the color scheme of the default Evergreen skin, edit <filename>/openils/var/web/opac/theme/default/css/colors.css</filename>. From this one file you can \r
change the 4 base color scheme as well as colors of specific elements. \r
</para> \r
</section>\r
<section xml:id="customizing_opac_text">\r
<title>customizing Opac Text and Labels</title>\r
+ <indexterm><primary>OPAC</primary><secondary>customizing</secondary><tertiary>text and labels</tertiary></indexterm>\r
<para>To change text and links used throughout the OPAC, edit the following files:</para>\r
<itemizedlist>\r
<listitem><filename>/openils/var/web/opac/locale/<emphasis role="bold">[your locale]</emphasis>/lang.dtd</filename></listitem>\r
</section>\r
<section xml:id="AddedContent">\r
<title>Added Content</title>\r
+ <indexterm><primary>OPAC</primary><secondary>added content</secondary></indexterm>\r
<para>By default Evergreen includes customizable <quote>Added Content</quote> features to enhance the OPAC experience for your user. These features include Amazon book covers \r
and Google books searching. These features can be turned off or customized.</para>\r
<simplesect xml:id="bookcovers">\r
</simplesect>\r
<simplesect xml:id="googlebookslink">\r
<title>Google Books Link</title>\r
+ <indexterm><primary>OPAC</primary><secondary>added content</secondary><tertiary>Google Books</tertiary></indexterm>\r
<para>The results page will display a <emphasis role="bold">Browse in Google Books Search</emphasis> link for items in the results page which have corresponding entries\r
in <systemitem class="resource">Google Books</systemitem>. \r
This will link to Google Books content including table of contents and complete versions of the work if it exists in Google Books. Items not in Google Books will not \r
</section>\r
<section xml:id="deatailspage">\r
<title>Customizing the Details Page</title>\r
+ <indexterm><primary>OPAC</primary><secondary>customizing</secondary><tertiary>details page</tertiary></indexterm>\r
<para>There are many options when customizing the details page in Evergreen. The default settings are effective for most libraries, but it is important to understand the full potential \r
of Evergreen when displaying the details of items.</para> \r
<para>Some quick features can be turned on and off by changing variable values in the file <filename>/openils/var/web/opac/skin/default/js/rdedail.js</filename>. \r
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="customizingstaffclient">\r
<title>Customizing the Staff Client</title>\r
+ <indexterm><primary>staff client</primary><secondary>customizing</secondary></indexterm>\r
<para>This chapter will give you some guidance on customizing the staff client.</para> \r
<para>The files related to the staff client are located in the directory <filename class="directory">/openils/var/web/xul/[staff client version]/server/</filename></para> \r
<section xml:id="staffclient_Changingcolors">\r
</section>\r
<section xml:id="staffclient_Changinglabels">\r
<title>Changing Labels and Messages</title>\r
+ <indexterm><primary>staff client</primary><secondary>customizing</secondary><tertiary>labels and messages</tertiary></indexterm>\r
<para>You can customize labels in the staff client by editing the corresponding DTD files. The staff client uses the same <filename>lang.dtd</filename> used by the OPAC. This file is located in <filename class="directory">/openils/var/web/opac/locale/[<emphasis>your locale</emphasis>]</filename>. Other labels are controlled by the staff client specific <filename>lang.dtd</filename> file in <filename class="directory">/openils/var/web/xul/<emphasis>client version</emphasis>]/server/locale/[<emphasis>your locale</emphasis>]/</filename>.</para>\r
</section>\r
<section xml:id="staffclient_searchskin">\r
</section>\r
<section id="_evergreen_interface_definition_language_idl">\r
<title>Evergreen Interface Definition Language (IDL)</title>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary></indexterm>\r
<simpara>Defines properties and required permissions for Evergreen classes.\r
To reduce network overhead, a given object is identified via a\r
class-hint and serialized as a JSON array of properties (no named properties).</simpara>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
- … oils_persist:readonly tells us, if true, that the data lives in the database, but is pulled from the SELECT statement defined in the <oils_persist:source_definition> child element\r
+ … oils_persist:readonly tells us, if true, that the data lives in the database, but is pulled from the SELECT statement defined in the <oils_persist:source_definition> \r
+ child element\r
</simpara>\r
</listitem>\r
</itemizedlist>\r
The <literal>class</literal> element defines the attributes and permissions for classes,\r
and relationships between classes.\r
</simpara>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>class element</secondary></indexterm>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<simpara>\r
The <literal>fields</literal> element defines the list of fields for the class.\r
</simpara>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>fields element</secondary></indexterm>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
<simpara>\r
Each <literal>field</literal> element defines one property of the class.\r
</simpara>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>field element</secondary></indexterm>\r
<itemizedlist>\r
<listitem>\r
<simpara>\r
</callout>\r
<callout arearefs="dmCO5-8">\r
<simpara>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>permacrud element</secondary></indexterm>\r
The <literal>permacrud</literal> element defines the permissions (if any) required\r
to <emphasis role="strong">c</emphasis>reate, <emphasis role="strong">r</emphasis>etrieve, <emphasis role="strong">u</emphasis>pdate, \r
and <emphasis role="strong">d</emphasis>elete data for this\r
class. <literal>open-ils.permacrud</literal> must be defined as a controller for the class\r
for the permissions to be applied.\r
</simpara>\r
+ \r
</callout>\r
<callout arearefs="dmCO5-9">\r
<simpara>\r
</simpara>\r
</listitem>\r
<listitem>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>action element</secondary></indexterm>\r
<simpara>\r
An action element may contain a <literal><context_field></literal> element that\r
defines the linked class (identified by the <literal>link</literal> attribute) and\r
</simpara>\r
<itemizedlist>\r
<listitem>\r
+ <indexterm><primary>Evergreen Interface Definition Language (IDL)</primary><secondary>context_field element</secondary></indexterm>\r
<simpara>\r
If the <literal><context_field></literal> element contains a <literal>jump</literal> attribute,\r
then it defines a link to a link to a class with a field identifying\r
</section>\r
<section id="open_ils_cstore_literal_data_access_interfaces">\r
<title><literal>open-ils.cstore</literal> data access interfaces</title>\r
+ <indexterm><primary>cstore</primary></indexterm>\r
<simpara>For each class documented in the IDL, the <literal>open-ils.cstore</literal> service\r
automatically generates a set of data access methods, based on the\r
<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
</section>\r
<section id="_open_ils_pcrud_data_access_interfaces">\r
<title>open-ils.pcrud data access interfaces</title>\r
+ <indexterm><primary>pcrud</primary></indexterm>\r
<simpara>For each class documented in the IDL, the <literal>open-ils.pcrud</literal> service\r
automatically generates a set of data access methods, based on the\r
<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
srfsh# close open-ils.cstore</screen>\r
<simplesect id="_json_queries">\r
<title>JSON Queries</title>\r
+ <indexterm><primary>JSON</primary></indexterm>\r
<simpara>Beyond simply retrieving objects by their ID using the <literal>\*.retrieve</literal>\r
methods, you can issue queries against the <literal>\*.delete</literal> and <literal>\*.search</literal>\r
methods using JSON to filter results with simple or complex search\r
<tbody>\r
<row>\r
<entry><filename>/openils/conf/opensrf_core.xml</filename></entry>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf_core.xml</secondary></indexterm>\r
<entry>Files which controls which Evergreen services are run on the public and private routers. For a service to run, it must be registered in this file. This file also controls the loglevel and points to the log file for the services. An Evergreen restart is required for changes to take effect.</entry>\r
</row>\r
<row>\r
<entry><filename>/openils/conf/opensrf.xml</filename></entry>\r
+ <indexterm><primary>configuration files</primary><secondary>opensrf.xml</secondary></indexterm>\r
<entry>Use this file to set directory locations, the default locale, default notice settings and settings for all Evergreen services. \r
It is critical for any administrator to understand the settings in this file. An Evergreen restart is required for changes to take effect.</entry>\r
</row>\r
<row>\r
<entry><filename>/openils/conf/fm_IDL.xml</filename></entry>\r
+ <indexterm><primary>configuration files</primary><secondary>fm_IDL.xml</secondary></indexterm>\r
<entry>Used for linking the OpenSRF/Evergreen services to the Evergreen database tables. An Evergreen restart is required for changes to take \r
effect. Running autogen.sh is also required.</entry>\r
</row>\r
<row>\r
<entry><filename>/etc/apache2/eg_vhost.conf</filename></entry>\r
+ <indexterm><primary>configuration files</primary><secondary>Apache</secondary></indexterm>\r
<entry>Controls the Evergreen virtual site. Allows to configure the skin for the OPAC or configure various directories within the Apache web server. \r
An Apache restart is required for changes to this file to take effect.</entry>\r
</row>\r
<tbody>\r
<row>\r
<entry><filename>/openils/bin/autogen.sh</filename></entry>\r
+ <indexterm><primary>autogen</primary></indexterm>\r
<entry>Used to update changes to org units and the fm_IDL.xml file. Will generate web and staff client pages based on contents of files and \r
Evergreen database entries.</entry>\r
</row>\r
<row>\r
<entry><filename>/openils/bin/clark-kent.pl</filename></entry>\r
+ <indexterm><primary>reports</primary><secondary>starting</secondary></indexterm>\r
<entry>Perl script for starting the reporter.</entry>\r
</row>\r
<row>\r
<entry><filename>/openils/bin/action_trigger_runner.pl</filename></entry>\r
+ <indexterm><primary>action triggers</primary><secondary>runner</secondary></indexterm>\r
<entry>Perl script used to trigger the actions set up in the action trigger tool in the staff client.</entry>\r
</row>\r
<row>\r
</row>\r
<row>\r
<entry><filename>/openils/bin/srfsh</filename></entry>\r
+ <indexterm><primary>srfsh</primary></indexterm>\r
<entry>Used to start the OpenSRF shell.</entry>\r
</row>\r
\r
</abstract> \r
<section id="intro_to_databases">\r
<title>Introduction to SQL Databases</title>\r
+ <indexterm><primary>sql</primary></indexterm>\r
<simplesect>\r
<title>Introduction</title>\r
<simpara>Over time, the SQL database has become the standard method of storing,\r
</simplesect>\r
<simplesect id="_tables">\r
<title>Tables</title>\r
+ <indexterm><primary>sql</primary><secondary>tables</secondary></indexterm>\r
<simpara>The table is the cornerstone of a SQL database. Conceptually, a database table\r
is similar to a single sheet in a spreadsheet: every table has one or more\r
columns, with each row in the table containing values for each column. Each\r
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
<info>\r
<title>JSON Queries</title>\r
+ <indexterm><primary>JSON</primary></indexterm>\r
</info>\r
<para>The json_query facility provides a way for client applications to query the database over the network. Instead of constructing its own SQL, the application encodes a query in the \r
form of a JSON string and passes it to the json_query service. Then the json_query service parses the JSON, constructs and executes the corresponding SQL, and returns the results to \r
</simplesect>\r
<simplesect>\r
<title>Default SELECT Clauses</title>\r
+ <indexterm><primary>JSON</primary><secondary>SELECT clauses</secondary></indexterm>\r
<para>The default SELECT clause includes every column that the IDL defines it as a non-virtual field for the class in question. If a column is present in the database but \r
not defined in the IDL, json_query doesn't know about it. In the case of the example shown above, all the columns are defined in the IDL, so they all show up in the default \r
SELECT clause.</para>\r
</info>\r
<section xml:id="usingsupercat">>\r
<title>Using SuperCat</title> \r
+ <indexterm><primary>SuperCat</primary></indexterm>\r
<para>SuperCat allows Evergreen record and information retrieval from a web browser using a based on a number of open web standards and formats. The following record types are \r
supported:</para>\r
<itemizedlist>\r
</itemizedlist>\r
<simplesect>\r
<title>Return a list of ISBNs for related records</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>ISBNs</secondary></indexterm>\r
<para>Similar to the OCLC xISBN service, Evergreen can return a list of related records based on its oISBN algorithm:</para>\r
<para><uri>http://<hostname>/opac/extras/osibn/<ISBN></uri></para>\r
<para>For example, <uri>http://dev.gapines.org/opac/extras/oisbn/0439136350</uri> returns:</para>\r
</simplesect>\r
<simplesect>\r
<title>Return records</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>records</secondary></indexterm>\r
<para>SuperCat can return records and metarecords in many different formats (see <xref linkend='supportedsupercatformats' /></para>\r
<para><uri>http://<hostname>/opac/extras/supercat/retrieve/<format>/<record-type>/<bib-ID></uri></para>\r
<para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/retrieve/mods/record/555</uri> returns:</para>\r
</simplesect>\r
<simplesect>\r
<title>Return a feed of recently edited or created records</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>recent records</secondary></indexterm>\r
<para>SuperCat can return feeds of recently edited or created authority and bibliographic records:</para>\r
<para><uri>http://<hostname>/opac/extras/feed/freshmeat/<feed-type>/[authority|biblio]/[import|edit]/<limit>/<date></uri></para>\r
<para>The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.</para>\r
</simplesect>\r
<simplesect xml:id="supportedsupercatformats">\r
<title>Supported formats</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>formats</secondary></indexterm>\r
<para>SuperCat maintains a list of supported formats for records and metarecords:</para>\r
<para><uri>http://<hostname>/opac/extras/supercat/formats/<record-type></uri></para>\r
<para>For example, <uri>http://dev.gapines.org/opac/extras/supercat/formats/record</uri> returns:</para>\r
</section>\r
<section xml:id="addingsupercatformats">\r
<title>Adding new SuperCat Formats</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>formats</secondary><tertiary>adding</tertiary></indexterm>\r
<para>Adding SuperCat formats requires experience editing XSL files and familiarity with XML and Perl.</para> \r
<para>SuperCat web services are based on the OpenSRF service, <systemitem class="service">>open-ils.supercat</systemitem>.</para> \r
<para>Developers are able to add new formats by adding the <emphasis>xsl</emphasis> stylesheet for the format. By default, the location of the stylesheets is <filename class="directory">/openils/var/xsl/</filename>. You must also add the feed to the perl \r
<tip><para>Use an existing xsl stylesheet and Perl module entry as a template for your new format.</para></tip>\r
</section>\r
<section xml:id="editingsupercatformats">\r
- <title>Customizing SuperCat Formats</title> \r
+ <title>Customizing SuperCat Formats</title>\r
+ <indexterm><primary>SuperCat</primary><secondary>formats</secondary><tertiary>customizing</tertiary></indexterm> \r
<para>Editing SuperCat formats requires experience editing XSL files and familiarity with XML..</para> \r
<para>It is possible to customize existing supercat formats using XSL stylesheets. You are able to change the content to be displayed and the design of the pages.</para> \r
<para>In order to change the display of a specific format, edit the corresponding XSL file(s) for the particular format. The default location for the XSL stylesheets is \r
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>\r
-<chapter xml:id="developer_workshop" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
- xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
-\r
-<chapterinfo>\r
- <title>Evergreen development</title>\r
- <date>February 2010</date>\r
- <author>\r
- <firstname>Dan</firstname>\r
- <surname>Scott</surname>\r
- <email>dscott@laurentian.ca</email>\r
- </author>\r
- <authorinitials>DS</authorinitials>\r
-<revhistory><revision><revnumber>1.0</revnumber><date>February 2010</date><authorinitials>DS</authorinitials></revision></revhistory>\r
-</chapterinfo>\r
-<section id="_part_1_opensrf_applications">\r
-<title>Part 1: OpenSRF applications</title>\r
-<simpara>OpenSRF, pronounced "Open Surf", is the Open <emphasis role="strong">S</emphasis>ervice <emphasis role="strong">R</emphasis>equest\r
-<emphasis role="strong">F</emphasis>ramework. It was designed as an architecture on which one could\r
-easily build scalable applications.</simpara>\r
-<section id="_introduction_to_opensrf">\r
-<title>Introduction to OpenSRF</title>\r
-<simpara>The framework is built on JSON-over-XMPP. XML can be used, but JSON\r
-is much less verbose. XMPP is a standard messaging protocol that\r
-has been used as the backbone of low-latency, high-volume\r
-applications including instant messaging and Google Wave.</simpara>\r
-<simpara>OpenSRF offers scalability via its clustering architecture; a service\r
-that is a bottleneck can be moved onto its own server; or multiple\r
-instances of the service can be run on many servers. Services can\r
-themselves be clients of other services.</simpara>\r
-<simpara>OpenSRF services listen at an XMPP address such as\r
-"opensrf@private.localhost/open-ils.fielder_drone_at_localhost_7652".\r
-The initial request from an OpenSRF client is directed to the\r
-OpenSRF router, which determines whether the requested service is\r
-accessible to the client (based on the public versus private domains),\r
-and then connects the client to the service for any subsequent\r
-communication that is required.</simpara>\r
-<simpara>To significantly improve the speed at which request services can\r
-respond to common requests, OpenSRF has integrated support for the\r
-caching via the <literal>memcached</literal> daemon. For example, the contents of the\r
-configuration files are cached by the <literal>opensrf.settings</literal> service when\r
-that service starts, so that rather than having to parse the XML file\r
-every time a service checks a configuration setting, the value can be\r
-retrieved with much less overhead directly from the cache.</simpara>\r
-<note><simpara>if you change a setting in one of those configuration files, you\r
-must restart the <literal>opensrf.settings</literal> service to update its data. You must\r
-then restart any of the services that make use of that setting to make\r
-the change take effect.</simpara></note>\r
-<simpara>Supports Perl, C, and Python as services and clients, and Java as a\r
-client. JavaScript can access services via HTTP translator and\r
-gateway. JSON library converts messages to/from native structures for\r
-ease of development.</simpara>\r
-</section>\r
-<section id="_configuring_opensrf">\r
-<title>Configuring OpenSRF</title>\r
-<simpara>Walk through the configuration files, explaining <emphasis>why</emphasis> we put the values\r
-into the files that we do:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-opensrf_core.xml\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-Distinguish between public and private services for security of Web-based applications.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Deprecated HTTP gateway versus OpenSRF-over-HTTP\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-opensrf.xml\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<tip><simpara>In a clustered OpenSRF instance, these files are normally hosted on\r
-a network share so that each member of the cluster can read them.</simpara></tip>\r
-</section>\r
-<section id="_starting_opensrf_services">\r
-<title>Starting OpenSRF services</title>\r
-<note><simpara>I won’t go through this during a live session. Perhaps I can cut this\r
-out entirely…</simpara></note>\r
-<simpara>Issue the following commands as the <literal>opensrf</literal> user. If you are running OpenSRF\r
-on a single-server machine, you can use the <literal>-l</literal> flag to force the hostname\r
-to be treated as <literal>localhost</literal>.</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Start the OpenSRF router:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a start_router</screen>\r
-<important><simpara>The router must only run on a single machine in a given brick.</simpara></important>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Start all OpenSRF Perl services defined for this host:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a start_perl</screen>\r
-<tip><simpara>You can start an individual Perl service using:</simpara></tip>\r
-<screen>opensrf-perl.pl -s <service-name> -a start -p <PID-directory></screen>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Start all OpenSRF C services defined for this host:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a start_c</screen>\r
-</listitem>\r
-</orderedlist>\r
-</section>\r
-<section id="_stopping_opensrf_services">\r
-<title>Stopping OpenSRF services</title>\r
-<simpara>Issue the following commands as the <literal>opensrf</literal> user. If you are running OpenSRF\r
-on a single-server machine, you can use the <literal>-l</literal> flag to force the hostname\r
-to be treated as <literal>localhost</literal>.</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Stop the OpenSRF router:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a stop_router</screen>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Stop all OpenSRF Perl services defined for this host:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a stop_perl</screen>\r
-<tip><simpara>You can stop an individual Perl service using:</simpara></tip>\r
-<screen>opensrf-perl.pl -s <service-name> -a stop -p <PID-directory></screen>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Stop all OpenSRF C services defined for this host:\r
-</simpara>\r
-<screen>osrf_ctl.sh -a stop_c</screen>\r
-</listitem>\r
-</orderedlist>\r
-<important><simpara>PID files for OpenSRF services are stored and looked up\r
-in <literal>/openils/var/run</literal> by default with <literal>osrf_ctl.sh</literal>, and in\r
-<literal>/tmp/</literal> with <literal>opensrf-perl.pl</literal>. For a clustered server instance\r
-of Evergreen, you must store the PIDs on a directory that is local\r
-to each server, or else one of your cluster servers may try\r
-killing processes on itself that actually have PIDs on other servers.</simpara></important>\r
-</section>\r
-</section>\r
-<section id="_examining_sample_code">\r
-<title>Examining sample code</title>\r
-<simpara>Show internal documentation for methods. Do some stupid srfsh tricks\r
-(<literal>introspect</literal> for one) and show <literal>docgen.xsl</literal> in action.</simpara>\r
-<section id="_srfsh_stupid_tricks">\r
-<title>SRFSH stupid tricks</title>\r
-<screen>srfsh# introspect open-ils.auth\r
-... returns documentation for all methods registered for open-ils.auth\r
-\r
-srfsh# introspect open-ils.auth "open-ils.auth.authenticate"\r
-... returns documentation for all methods with names beginning with\r
- "open-ils.auth.authenticate" registered for open-ils.auth\r
-\r
-srfsh# open open-ils.cstore\r
-... begins a stateful connection with open-ils.cstore\r
-srfsh# request open-ils.cstore open-ils.cstore.transaction.begin\r
-... begins a transaction\r
-srfsh# request open-ils.cstore open-ils.cstore.direct.config.language_map.delete \\r
- {"code": {"like":"a%"}}\r
-... deletes all of the entries from config.language_map that have a\r
-... code beginning with "e"\r
-srfsh# request open-ils.cstore open-ils.cstore.transaction.rollback\r
-... rolls back the transaction\r
-srfsh# close open-ils.cstore\r
-... closes the stateful connection with open-ils.cstore</screen>\r
-</section>\r
-<section id="_perl">\r
-<title>Perl</title>\r
-<section id="_services">\r
-<title>Services</title>\r
-<simpara>See <literal>OpenSRF/src/perl/lib/OpenSRF/UnixServer.pm</literal> to understand how the\r
-optional methods for initializing and cleaning up OpenSRF services\r
-are invoked:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>initialize()</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>child_init()</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>child_exit()</literal>\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<simpara>Services are implemented as Perl functions. Each service needs to be registered with:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">__PACKAGE__->register_method(\r
- method => 'method name', # <co id="CO1-1"/>\r
- api_name => 'API name', # <co id="CO1-2"/>\r
- api_level => 1, # <co id="CO1-3"/>\r
- argc => # of args, # <co id="CO1-4"/>\r
- signature => { # <co id="CO1-5"/>\r
- desc => “Description”,\r
- params => [\r
- {\r
- name => 'parameter name',\r
- desc => 'parameter description',\r
- type => '(array|hash|number|string)'\r
- }\r
- ],\r
- return => {\r
- desc => 'Description of return value',\r
- type => '(array|hash|number|string)'\r
- }\r
- }\r
-);</programlisting>\r
-<calloutlist>\r
-<callout arearefs="CO1-1">\r
-<simpara>\r
-The method name is the name of the Perl method that is called when a\r
-client invokes the corresponding OpenSRF method.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO1-2">\r
-<simpara>\r
-The API name is the OpenSRF method name. By convention, each API\r
-uses the OpenSRF service name for its root, and then appends one or more\r
-levels of names to the OpenSRF service name, depending on the complexity\r
-of the service and the number of methods exposed by a given service.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO1-3">\r
-<simpara>\r
-The API level is always <literal>1</literal>.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO1-4">\r
-<simpara>\r
-The number of arguments that can be passed to the OpenSRF method is\r
-primarily for guidance purposes.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO1-5">\r
-<simpara>\r
-The signature is consumed by the various utilities (srfsh, docgen.xsl)\r
-that generate documentation about the OpenSRF service.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-<simpara>Note that arguments are converted between native data structures and JSON\r
-for us for free.</simpara>\r
-</section>\r
-<section id="_client_cheat_sheet">\r
-<title>Client cheat sheet</title>\r
-<simpara>This is the simplest possible OpenSRF client written in Perl:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
-<calloutlist>\r
-<callout arearefs="">\r
-<simpara>\r
-The <literal>OpenSRF::System</literal> module gives our program access to the core OpenSRF\r
-client functionality.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The <literal>bootstrap_client()</literal> method reads the <literal>opensrf_core.xml</literal> file and sets\r
-up communication with the OpenSRF router.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The <literal>OpenSRF::Appsession->create()</literal> instance method asks the router if it\r
-can connect to the named service. If the router determines that the service\r
-is accessible (either the opensrf credentials are on the private domain, which\r
-gives it access to all public and private services; or the service is on a\r
-public domain, which is accessible to both public and private opensrf\r
-credentials), it returns an OpenSRF session with a connection to the named service.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The <literal>OpenSRF::Appsession->request()</literal> method invokes a method of the\r
-associated service to return a request object.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The method name that you want to invoke is the first argument to <literal>request()</literal>.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The arguments to the method follow the method name.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Invoking the <literal>gather()</literal> method on the returned request object returns a\r
-single result.\r
-</simpara>\r
-<note><simpara>If the service is expected to return multiple results, you should loop\r
-over it with <literal>recv()</literal> instead. But then, that wouldn’t be the simplest\r
-possible client anymore would it?</simpara></note>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The <literal>OpenSRF::Appsession->disconnect()</literal> instance method disconnects from\r
-the service, enabling that child to go on and handle other requests.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-</section>\r
-<section id="_javascript">\r
-<title>JavaScript</title>\r
-<simpara>Historically, JavaScript has had access to OpenSRF methods via the\r
-OpenSRF HTTP gateway Apache module. You can still see this in heavy use\r
-in the OPAC and staff client as of Evergreen 1.6, but the approach has been\r
-deprecated as it has significant performance problems with large responses.\r
-The successor for the OpenSRF gateway is the OpenSRF-over-HTTP translator\r
-Apache module, which supports streaming responses for improved performance\r
-and better support for the broad range of OpenSRF attributes.</simpara>\r
-<section id="_invoking_methods_via_the_http_translator">\r
-<title>Invoking methods via the HTTP Translator</title>\r
-<simpara>The following example demonstrates the basic approach to invoking\r
-OpenSRF methods via JavaScript. It uses just three OpenSRF JavaScript\r
-libraries to simplify calls to the OpenSRF-over-HTTP translator,\r
-which became available to developers as part of the OpenSRF 1.0 /\r
-Evergreen 1.4 releases.</simpara>\r
-<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
-<calloutlist>\r
-<callout arearefs="">\r
-<simpara>\r
-opensrf.js defines most of the objects and methods required for a bare\r
-JavaScript call to the OpenSRF HTTP translator.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-JSON_v1.js converts the requests and responses between JavaScript and the\r
-JSON format that the OpenSRF translator expects.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create a client session that connects to the <literal>open-ils.resolver</literal> service.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create a request object that identifies the target method and passes the\r
-required method arguments.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Define the function that will be called when the request is sent and\r
-results are returned from the OpenSRF HTTP translator.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Loop over the returned results using the <literal>recv()</literal> method.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The content of each result is accessible via the content() method of\r
-each returned result.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-<literal>open-ils.resolver.resolve_holdings</literal> returns a hash of values, so\r
-invoking one of the hash keys (<literal>coverage</literal>) gives us access to that value.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Actually send the request to the method; the function defined by\r
-<literal>req.oncomplete</literal> is invoked as the results are returned.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-</section>\r
-</section>\r
-<section id="_exercise">\r
-<title>Exercise</title>\r
-<simpara>Build a new OpenSRF service.</simpara>\r
-<section id="_perl_2">\r
-<title>Perl</title>\r
-<simpara>The challenge: implement a service that caches responses from some\r
-other Web service (potentially cutting down on client-side latency\r
-for something like OpenLibrary / Google Books / xISBN services, and\r
-avoiding timeouts if the target service is not dependable). Our\r
-example will be to build an SFX lookup service. This has the\r
-additional advantage of enabling <literal>XmlHttpRequest</literal> from JavaScript by\r
-hosting the services on the same domain.</simpara>\r
-<simpara>Let’s start with the simplest possible implementation – a CGI script.</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
-<simpara>Hopefully you can follow what this CGI script is doing. It works,\r
-but it has all the disadvantages of CGI: the environment needs to\r
-be built up on every request, and it doesn’t remember anything\r
-from the previous times it was called, etc.</simpara>\r
-<section id="_turning_the_cgi_script_into_an_opensrf_service">\r
-<title>Turning the CGI script into an OpenSRF service</title>\r
-<simpara>So now we want to turn this into an OpenSRF service.</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Start by ripping out the CGI stuff, as we won’t need that any more.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-To turn this into an OpenSRF service, we create a new\r
-Perl module (<literal>OpenILS::Application::ResolverResolver</literal>). We no\r
-longer have to convert results between Perl and JSON values, as\r
-OpenSRF will handle that for us. We now have to register the\r
-method with OpenSRF.\r
-</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Copy the file into the <literal>/openils/lib/perl5/OpenILS/Application/</literal> directory\r
-so that OpenSRF can find it in the <literal>@INC</literal> search path.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Add the service to <literal>opensrf.xml</literal> so it gets started with the\r
-other Perl services on our host of choice:\r
-</simpara>\r
-<programlisting language="xml" linenumbering="unnumbered">...\r
-<open-ils.resolver>\r
- <keepalive>3</keepalive>\r
- <stateless>1</stateless>\r
- <language>perl</language>\r
- <implementation>OpenILS::Application::ResolverResolver</implementation>\r
- <max_requests>17</max_requests>\r
- <unix_config>\r
- <unix_sock>open-ils.resolver_unix.sock</unix_sock>\r
- <unix_pid>open-ils.resolver_unix.pid</unix_pid>\r
- <max_requests>1000</max_requests>\r
- <unix_log>open-ils.resolver_unix.log</unix_log>\r
- <min_children>5</min_children>\r
- <max_children>15</max_children>\r
- <min_spare_children>3</min_spare_children>\r
- <max_spare_children>5</max_spare_children>\r
- </unix_config>\r
- <app_settings>\r
- <cache_timeout>86400</cache_timeout>\r
- <default_url_base>http://sfx.scholarsportal.info/laurentian</default_url_base>\r
- </app_settings>\r
-</open-ils.resolver>\r
-...\r
-<!-- In the <hosts> section -->\r
-<localhost>\r
- ...\r
- <appname>open-ils.resolver</appname>\r
-</localhost></programlisting>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Add the service to <literal>opensrf_core.xml</literal> as a publicly exposed\r
-service via the HTTP gateway and translator:\r
-</simpara>\r
-<programlisting language="xml" linenumbering="unnumbered">...\r
-<!-- In the public router section -->\r
-<services>\r
- ...\r
- <service>open-ils.resolver</service>\r
-</services>\r
-...\r
-<!-- In the public gateway section -->\r
-<services>\r
-<gateway>\r
- ...\r
- <services>\r
- <service>open-ils.resolver</service>\r
- </services>\r
-</gateway></programlisting>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Restart the OpenSRF Perl services to refresh the OpenSRF\r
-settings and start the service..\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Restart Apache to enable the gateway and translator to pick up\r
-the new service.\r
-</simpara>\r
-</listitem>\r
-</orderedlist>\r
-</section>\r
-<section id="_add_caching">\r
-<title>Add caching</title>\r
-<simpara>To really make this service useful, we can take advantage of OpenSRF’s\r
-built-in support for caching via memcached. Keeping the values\r
-returned by the resolver for 1 week is apparently good.</simpara>\r
-<simpara>We will also take advantage of the <literal>opensrf.settings</literal> service that\r
-holds the values defined in the <literal>opensrf.xml</literal> configuration file to\r
-supply some of our default arguments.</simpara>\r
-<formalpara><title>Caching OpenSRF Resolver Service</title><para>\r
-<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
-</para></formalpara>\r
-</section>\r
-<section id="_pulling_application_settings_from_literal_opensrf_xml_literal">\r
-<title>Pulling application settings from <literal>opensrf.xml</literal></title>\r
-<simpara>In case you missed it in the previous diff, we also started\r
-pulling some application-specific settings from <literal>opensrf.xml</literal>\r
-during the <literal>initialize()</literal> phase for the service.</simpara>\r
-<simpara>In the following diff, we enable the service to pull the default URL from\r
-<literal>opensrf.xml</literal> rather than hard-coding it into the OpenSRF service… because\r
-that’s just the right thing to do.</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">=== modified file 'ResolverResolver.pm'\r
---- ResolverResolver.pm 2009-10-22 21:00:15 +0000\r
-+++ ResolverResolver.pm 2009-10-24 03:00:30 +0000\r
-@@ -77,6 +77,7 @@\r
- my $prefix = "open-ils.resolver_"; # Prefix for caching values\r
- my $cache;\r
- my $cache_timeout;\r
-+my $default_url_base; # Default resolver location\r
-\r
- our ($ua, $parser);\r
-\r
-@@ -86,6 +87,8 @@\r
- my $sclient = OpenSRF::Utils::SettingsClient->new();\r
- $cache_timeout = $sclient->config_value(\r
- "apps", "open-ils.resolver", "app_settings", "cache_timeout" ) || 300;\r
-+ $default_url_base = $sclient->config_value(\r
-+ "apps", "open-ils.resolver", "app_settings", "default_url_base");\r
- }\r
-\r
- sub child_init {\r
-@@ -102,14 +105,11 @@\r
- my $conn = shift;\r
- my $id_type = shift; # keep it simple for now, either 'issn' or 'isbn'\r
- my $id_value = shift; # the normalized ISSN or ISBN\r
-+ my $url_base = shift || $default_url_base;\r
-\r
- # We'll use this in our cache key\r
- my $method = "open-ils.resolver.resolve_holdings";\r
-\r
-- # For now we'll pass the argument with a hard-coded default\r
-- # Should pull these specifics from the database as part of initialize()\r
-- my $url_base = shift || 'http://sfx.scholarsportal.info/laurentian';\r
--\r
- # Big ugly SFX OpenURL request\r
- my $url_args = '?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&'\r
- . 'ctx_enc=UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/conifer&'</programlisting>\r
-<simpara>The <literal>opensrf.settings</literal> service caches the settings defined in <literal>opensrf.xml</literal>,\r
-so if you change a setting in the configuration files and want that change\r
-to take effect immediately, you have to:</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Restart the <literal>opensrf.settings</literal> service to refresh the cached settings.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Restart the affected service to make the new settings take effect.\r
-</simpara>\r
-</listitem>\r
-</orderedlist>\r
-<simpara>Next step: add org_unit settings for resolver type and URL on a per-org_unit basis.\r
-OrgUnit settings can be retrieved via\r
-<literal>OpenILS::Application::AppUtils->ou_ancestor_setting_value($org_id, $setting_name)</literal>).</simpara>\r
-<simpara>This is where we step beyond OpenSRF and start getting into the\r
-Evergreen database schema (<literal>config.org_unit_setting</literal> table).</simpara>\r
-</section>\r
-</section>\r
-<section id="_further_reading">\r
-<title>Further reading</title>\r
-<simpara>OpenSRF terminology: <ulink url="http://open-ils.org/dokuwiki/doku.php?id=osrf-devel:terms">http://open-ils.org/dokuwiki/doku.php?id=osrf-devel:terms</ulink></simpara>\r
-</section>\r
-</section>\r
-<section id="_part_2_evergreen_applications">\r
-<title>Part 2: Evergreen applications</title>\r
-<section id="_authentication">\r
-<title>Authentication</title>\r
-<simpara>Although many services offer methods that can be invoked without\r
-authentication, some methods require authentication in Evergreen.\r
-Evergreen’s authentication framework returns an <emphasis>authentication token</emphasis>\r
-when a user has successfully logged in to represent that user\r
-session. You can then pass the authentication token to various\r
-methods to ensure, for example, that the requesting user has permission\r
-to access the circulation information attached to a particular account,\r
-or has been granted the necessary permissions at a particular library\r
-to perform the action that they are requesting.</simpara>\r
-<simpara>Authentication in Evergreen is performed with the assistance of the\r
-<literal>open-ils.auth</literal> service, which has been written in C for performance\r
-reasons because it is invoked so frequently. A successful authentication\r
-request requires two steps:</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Retrieve an authentication seed value by invoking the\r
-<literal>open-ils.auth.authenticate.init</literal> method, passing the user name as\r
-the only argument. As long as the user name contains no spaces, the\r
-method returns a seed value calculated by the MD5 checksum of\r
-a string composed of the concatenation of the time() system call,\r
-process ID, and user name.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Retrieve an authentication token by invoking the\r
-<literal>open-ils.auth.authenticate.complete</literal> method, passing\r
-a JSON hash composed of a minimum of the following arguments\r
-(where <emphasis>seed</emphasis> represents the value returned by the\r
-<literal>open-ils.auth.authenticate.init</literal> method):\r
-</simpara>\r
-<programlisting language="java" linenumbering="unnumbered">{\r
- "username": username, // or "barcode": barcode,\r
- "password": md5sum(seed + md5sum(password)),\r
-}</programlisting>\r
-</listitem>\r
-</orderedlist>\r
-<simpara><literal>open-ils.auth.authenticate.complete</literal> also accepts the following\r
-additional arguments:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>type</literal>: one of "staff" (default), "opac", or "temp"\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>org</literal>: the numeric ID of the org_unit where the login is active\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>workstation</literal>: the registered workstation name\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<section id="_authentication_in_perl">\r
-<title>Authentication in Perl</title>\r
-<simpara>The following example is taken directly from <literal>OpenILS::WWW::Proxy</literal>:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered">sub oils_login {\r
- my( $username, $password, $type ) = @_;\r
-\r
- $type |= "staff";\r
- my $nametype = 'username';\r
- $nametype = 'barcode' if ($username =~ /^\d+$/o);\r
-\r
- my $seed = OpenSRF::AppSession\r
- ->create("open-ils.auth")\r
- ->request( 'open-ils.auth.authenticate.init', $username )\r
- ->gather(1);\r
-\r
- return undef unless $seed;\r
-\r
- my $response = OpenSRF::AppSession\r
- ->create("open-ils.auth")\r
- ->request( 'open-ils.auth.authenticate.complete', {\r
- $nametype => $username,\r
- password => md5_hex($seed . md5_hex($password)),\r
- type => $type\r
- })\r
- ->gather(1);\r
-\r
- return undef unless $response;\r
-\r
- return $response->{payload}->{authtoken};\r
-}</programlisting>\r
-</section>\r
-<section id="_authentication_in_javascript">\r
-<title>Authentication in JavaScript</title>\r
-<simpara>The following example provides a minimal implementation of the authentication\r
-method in JavaScript. For a more complete implementation, you would\r
-differentiate between user names and barcodes, potentially accept the\r
-org_unit and workstation name for more granular permissions, and provide\r
-exception handling.</simpara>\r
-<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
-<calloutlist>\r
-<callout arearefs="">\r
-<simpara>\r
-opensrf.js defines most of the objects and methods required for a bare\r
-JavaScript call to the OpenSRF HTTP translator.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-JSON_v1.js converts the requests and responses between JavaScript and the\r
-JSON format that the OpenSRF translator expects.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-md5.js provides the implementation of the md5sum algorithm in the\r
-<literal>hex_md5</literal> function\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create a client session that connects to the <literal>open-ils.auth</literal> service.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create a request object that invokes the <literal>open-ils.auth.authenticate.init</literal>\r
-method, providing the user name as the salt.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Set the <literal>timeout</literal> property on the request object to make it a\r
-synchronous call.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Send the request. The method returns a seed value which is assigned to\r
-the <literal>seed</literal> variable.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create the hash of parameters that will be sent in the request to the\r
-<literal>open-ils.auth.authenticate.complete</literal> method, including the password and\r
-authentication type.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Assume that the credentials being sent are based on the user name rather\r
-than the barcode. The Perl implementation tests the value of the user name\r
-variable to determine whether it contains a digit; if it does contain a\r
-digit, then it is considered a barcode rather than a user name. Ensure that\r
-your implementations are consistent!\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Create a request object that invokes the\r
-<literal>open-ils.auth.authenticate.complete</literal> method, passing the entire hash of\r
-parameters. Once again, set the <literal>timeout</literal> parameter to make the request\r
-synchronous.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-Assign the <literal>authtoken</literal> attribute of the returned payload to the\r
-<literal>authtoken</literal> variable.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-</section>\r
-</section>\r
-<section id="_evergreen_data_models_and_access">\r
-<title>Evergreen data models and access</title>\r
-<section id="_database_schema">\r
-<title>Database schema</title>\r
-<simpara>The database schema is tied pretty tightly to PostgreSQL. Although PostgreSQL\r
-adheres closely to ANSI SQL standards, the use of schemas, SQL functions\r
-implemented in both plpgsql and plperl, and PostgreSQL’s native full-text\r
-search would make it… challenging… to port to other database platforms.</simpara>\r
-<simpara>A few common PostgreSQL interfaces for poking around the schema and\r
-manipulating data are:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-psql (the command line client)\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-pgadminIII (a GUI client).\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<simpara>Or you can read through the source files in Open-ILS/src/sql/Pg.</simpara>\r
-<simpara>Let’s take a quick tour through the schemas, pointing out some highlights\r
-and some key interdependencies:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-actor.org_unit → asset.copy_location\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-actor.usr → actor.card\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-biblio.record_entry → asset.call_number → asset.copy\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-config.metabib_field → metabib.*_field_entry\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</section>\r
-<section id="_database_access_methods">\r
-<title>Database access methods</title>\r
-<simpara>You could use direct access to the database via Perl DBI, JDBC, etc,\r
-but Evergreen offers several database CRUD services for\r
-creating / retrieving / updating / deleting data. These avoid tying\r
-you too tightly to the current database schema and they funnel database\r
-access through the same mechanism, rather than tying up connections\r
-with other interfaces.</simpara>\r
-</section>\r
-<section id="_evergreen_interface_definition_language_idl">\r
-<title>Evergreen Interface Definition Language (IDL)</title>\r
-<simpara>Defines properties and required permissions for Evergreen classes.\r
-To reduce network overhead, a given object is identified via a\r
-class-hint and serialized as a JSON array of properties (no named properties).</simpara>\r
-<simpara>As of 1.6, fields will be serialized in the order in which they appear\r
-in the IDL definition file, and the is_new / is_changed / is_deleted\r
-properties are automatically added. This has greatly reduced the size of\r
-the <literal>fm_IDL.xml</literal> file and makes DRY people happier :)</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-… oils_persist:readonly tells us, if true, that the data lives in the database, but is pulled from the SELECT statement defined in the <oils_persist:source_definition> child element\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<section id="_idl_basic_example_config_language_map">\r
-<title>IDL basic example (config.language_map)</title>\r
-<programlisting language="xml" linenumbering="unnumbered"><class id="clm" controller="open-ils.cstore open-ils.pcrud"\r
- oils_obj:fieldmapper="config::language_map"\r
- oils_persist:tablename="config.language_map"\r
- reporter:label="Language Map" oils_persist:field_safe="true"> # <co id="CO5-1"/> <co id="CO5-2"/> <co id="CO5-3"/> <co id="CO5-4"/>\r
- <fields oils_persist:primary="code" oils_persist:sequence=""> # <co id="CO5-5"/>\r
- <field reporter:label="Language Code" name="code"\r
- reporter:selector="value" reporter:datatype="text"/> # <co id="CO5-6"/>\r
- <field reporter:label="Language" name="value"\r
- reporter:datatype="text" oils_persist:i18n="true"/> # <co id="CO5-7"/>\r
- </fields>\r
- <links/>\r
- <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"> # <co id="CO5-8"/>\r
- <actions>\r
- <create global_required="true" permission="CREATE_MARC_CODE"> # <co id="CO5-9"/>\r
- <retrieve global_required="true"\r
- permission="CREATE_MARC_CODE UPDATE_MARC_CODE DELETE_MARC_CODE">\r
- <update global_required="true" permission="UPDATE_MARC_CODE">\r
- <delete global_required="true" permission="DELETE_MARC_CODE">\r
- </actions>\r
- </permacrud>\r
-</class></programlisting>\r
-<calloutlist>\r
-<callout arearefs="CO5-1">\r
-<simpara>\r
-The <literal>class</literal> element defines the attributes and permissions for classes,\r
-and relationships between classes.\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-The <literal>id</literal> attribute on the <literal>class</literal> element defines the class hint that is\r
-used everywhere in Evergreen.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>controller</literal> attribute defines the OpenSRF\r
-services that provide access to the data for the class objects.\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</callout>\r
-<callout arearefs="CO5-2">\r
-<simpara>\r
-The <literal>oils_obj::fieldmapper</literal> attribute defines the name of the class that\r
-is generated by <literal>OpenILS::Utils::Fieldmapper</literal>.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO5-3">\r
-<simpara>\r
-The <literal>oils_persist:tablename</literal> attribute defines the name of the table\r
-that contains the data for the class objects.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO5-4">\r
-<simpara>\r
-The reporter interface uses <literal>reporter:label</literal> attribute values in\r
-the source list to provide meaningful class and attribute names. The\r
-<literal>open-ils.fielder</literal> service generates a set of methods that provide direct\r
-access to the classes for which <literal>oils_persist:field_safe</literal> is <literal>true</literal>. For\r
-example,\r
-</simpara>\r
-<screen>srfsh# request open-ils.fielder open-ils.fielder.clm.atomic \\r
- {"query":{"code":{"=":"eng"}}}\r
-\r
-Received Data: [\r
- {\r
- "value":"English",\r
- "code":"eng"\r
- }\r
-]</screen>\r
-</callout>\r
-<callout arearefs="CO5-5">\r
-<simpara>\r
-The <literal>fields</literal> element defines the list of fields for the class.\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-The <literal>oils_persist:primary</literal> attribute defines the column that acts as\r
-the primary key for the table.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>oils_persist:sequence</literal> attribute holds the name of the database\r
-sequence.\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</callout>\r
-<callout arearefs="CO5-6">\r
-<simpara>\r
-Each <literal>field</literal> element defines one property of the class.\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-The <literal>name</literal> attribute defines the getter/setter method name for the field.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>reporter:label</literal> attribute defines the attribute name as used in\r
-the reporter interface.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>reporter:selector</literal> attribute defines the field used in the reporter\r
-filter interface to provide a selectable list. This gives the user a more\r
-meaningful access point than the raw numeric ID or abstract code.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>reporter:datatype</literal> attribute defines the type of data held by\r
-this property for the purposes of the reporter.\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</callout>\r
-<callout arearefs="CO5-7">\r
-<simpara>\r
-The <literal>oils_persist:i18n</literal> attribute, when <literal>true</literal>, means that\r
-translated values for the field’s contents may be accessible in\r
-different locales.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO5-8">\r
-<simpara>\r
-The <literal>permacrud</literal> element defines the permissions (if any) required\r
-to <emphasis role="strong">c</emphasis>reate, <emphasis role="strong">r</emphasis>etrieve, <emphasis role="strong">u</emphasis>pdate, and <emphasis role="strong">d</emphasis>elete data for this\r
-class. <literal>open-ils.permacrud</literal> must be defined as a controller for the class\r
-for the permissions to be applied.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO5-9">\r
-<simpara>\r
-Each action requires one or more <literal>permission</literal> values that the\r
-user must possess to perform the action.\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-If the <literal>global_required</literal> attribute is <literal>true</literal>, then the user must\r
-have been granted that permission globally (depth = 0) to perform\r
-the action.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-The <literal>context_field</literal> attribute denotes the <literal><field></literal> that identifies\r
-the org_unit at which the user must have the pertinent permission.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-An action element may contain a <literal><context_field></literal> element that\r
-defines the linked class (identified by the <literal>link</literal> attribute) and\r
-the field in the linked class that identifies the org_unit where\r
-the permission must be held.\r
-</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-If the <literal><context_field></literal> element contains a <literal>jump</literal> attribute,\r
-then it defines a link to a link to a class with a field identifying\r
-the org_unit where the permission must be held.\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</listitem>\r
-</itemizedlist>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-<section id="_reporter_data_types_and_their_possible_values">\r
-<title>Reporter data types and their possible values</title>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>bool</literal>: Boolean <literal>true</literal> or <literal>false</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>id</literal>: ID of the row in the database\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>int</literal>: integer value\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>interval</literal>: PostgreSQL time interval\r
-</simpara>\r
-</listitem>\r
-\r
-<listitem>\r
-<simpara>\r
-<literal>link</literal>: link to another class, as defined in the <literal><links></literal>\r
-element of the class definition\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>money</literal>: currency amount\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>org_unit</literal>: list of org_units\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>text</literal>: text value\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>timestamp</literal>: PostgreSQL timestamp\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</section>\r
-<section id="_idl_example_with_linked_fields_actor_workstation">\r
-<title>IDL example with linked fields (actor.workstation)</title>\r
-<simpara>Just as tables often include columns with foreign keys that point\r
-to values stored in the column of a different table, IDL classes\r
-can contain fields that link to fields in other classes. The <literal><links></literal>\r
-element defines which fields link to fields in other classes, and\r
-the nature of the relationship:</simpara>\r
-<programlisting language="xml" linenumbering="unnumbered"><class id="aws" controller="open-ils.cstore"\r
- oils_obj:fieldmapper="actor::workstation"\r
- oils_persist:tablename="actor.workstation"\r
- reporter:label="Workstation">\r
- <fields oils_persist:primary="id"\r
- oils_persist:sequence="actor.workstation_id_seq">\r
- <field reporter:label="Workstation ID" name="id"\r
- reporter:datatype="id"/>\r
- <field reporter:label="Workstation Name" name="name"\r
- reporter:datatype="text"/>\r
- <field reporter:label="Owning Library" name="owning_lib"\r
- reporter:datatype="org_unit"/>\r
- <field reporter:label="Circulations" name="circulations"\r
- oils_persist:virtual="true" reporter:datatype="link"/> # <co id="CO6-1"/>\r
- </fields>\r
- <links> # <co id="CO6-2"/>\r
- <link field="owning_lib" reltype="has_a" key="id"\r
- map="" class="aou"/> # <co id="CO6-3"/>\r
- <link field="circulations" reltype="has_many" key="workstation"\r
- map="" class="circ"/>\r
- <link field="circulation_checkins" reltype="has_many"\r
- key="checkin_workstation" map="" class="circ"/>\r
- </links>\r
-</class></programlisting>\r
-<calloutlist>\r
-<callout arearefs="CO6-1">\r
-<simpara>\r
-This field includes an <literal>oils_persist:virtual</literal> attribute with the value of\r
-<literal>true</literal>, meaning that the linked class <literal>circ</literal> is a virtual class.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO6-2">\r
-<simpara>\r
-The <literal><links></literal> element contains 0 or more <literal><link></literal> elements.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO6-3">\r
-<simpara>\r
-Each <literal><link></literal> element defines the field (<literal>field</literal>) that links to a different\r
-class (<literal>class</literal>), the relationship (<literal>rel_type</literal>) between this field and the target\r
-field (<literal>key</literal>). If the field in this class links to a virtual class, the (<literal>map</literal>)\r
-attribute defines the field in the target class that returns a list of matching\r
-objects for each object in this class.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-</section>\r
-<section id="_literal_open_ils_cstore_literal_data_access_interfaces">\r
-<title><literal>open-ils.cstore</literal> data access interfaces</title>\r
-<simpara>For each class documented in the IDL, the <literal>open-ils.cstore</literal> service\r
-automatically generates a set of data access methods, based on the\r
-<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
-<simpara>For example, for the class hint <literal>clm</literal>, cstore generates the following\r
-methods with the <literal>config.language_map</literal> qualifer:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.id_list {"code" { "like": "e%" } }</literal>\r
-</simpara>\r
-<simpara>Retrieves a list composed only of the IDs that match the query.</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.retrieve "eng"</literal>\r
-</simpara>\r
-<simpara>Retrieves the object that matches a specific ID.</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.search {"code" : "eng"}</literal>\r
-</simpara>\r
-<simpara>Retrieves a list of objects that match the query.</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.create <_object_></literal>\r
-</simpara>\r
-<simpara>Creates a new object from the passed in object.</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.update <_object_></literal>\r
-</simpara>\r
-<simpara>Updates the object that has been passed in.</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.direct.config.language_map.delete "eng"</literal>\r
-</simpara>\r
-<simpara>Deletes the object that matches the query.</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</section>\r
-<section id="_open_ils_pcrud_data_access_interfaces">\r
-<title>open-ils.pcrud data access interfaces</title>\r
-<simpara>For each class documented in the IDL, the <literal>open-ils.pcrud</literal> service\r
-automatically generates a set of data access methods, based on the\r
-<literal>oils_persist:tablename</literal> class attribute.</simpara>\r
-<simpara>For example, for the class hint <literal>clm</literal>, <literal>open-ils.pcrud</literal> generates the following\r
-methods that parallel the <literal>open-ils.cstore</literal> interface:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.id_list.clm <_authtoken_>, { "code": { "like": "e%" } }</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.retrieve.clm <_authtoken_>, "eng"</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.search.clm <_authtoken_>, { "code": "eng" }</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.create.clm <_authtoken_>, <_object_></literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.update.clm <_authtoken_>, <_object_></literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.delete.clm <_authtoken_>, "eng"</literal>\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-</section>\r
-<section id="_transaction_and_savepoint_control">\r
-<title>Transaction and savepoint control</title>\r
-<simpara>Both <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> enable you to control database transactions\r
-to ensure that a set of operations either all succeed, or all fail,\r
-atomically:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.transaction.begin</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.transaction.commit</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.transaction.rollback</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.transaction.begin</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.transaction.commit</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.transaction.rollback</literal>\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<simpara>At a more granular level, <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> enable you to set database\r
-savepoints to ensure that a set of operations either all succeed, or all\r
-fail, atomically, within a given transaction:</simpara>\r
-<itemizedlist>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.savepoint.begin</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.savepoint.commit</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.cstore.savepoint.rollback</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.savepoint.begin</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.savepoint.commit</literal>\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-<literal>open-ils.pcrud.savepoint.rollback</literal>\r
-</simpara>\r
-</listitem>\r
-</itemizedlist>\r
-<simpara>Transactions and savepoints must be performed within a stateful\r
-connection to the <literal>open-ils.cstore</literal> and <literal>open-ils.pcrud</literal> services.\r
-In <literal>srfsh</literal>, you can open a stateful connection using the <literal>open</literal>\r
-command, and then close the stateful connection using the <literal>close</literal>\r
-command - for example:</simpara>\r
-<screen>srfsh# open open-ils.cstore\r
-... perform various transaction-related work\r
-srfsh# close open-ils.cstore</screen>\r
-<section id="_json_queries">\r
-<title>JSON Queries</title>\r
-<simpara>Beyond simply retrieving objects by their ID using the <literal>\*.retrieve</literal>\r
-methods, you can issue queries against the <literal>\*.delete</literal> and <literal>\*.search</literal>\r
-methods using JSON to filter results with simple or complex search\r
-conditions.</simpara>\r
-<simpara>For example, to generate a list of barcodes that are held in a\r
-copy location that allows holds and is visible in the OPAC:</simpara>\r
-<programlisting language="sh" linenumbering="unnumbered">srfsh# request open-ils.cstore open-ils.cstore.json_query #\ <co id="CO7-1"/>\r
- {"select": {"acp":["barcode"], "acpl":["name"]}, #\ <co id="CO7-2"/>\r
- "from": {"acp":"acpl"}, #\ <co id="CO7-3"/>\r
- "where": [ #\ <co id="CO7-4"/>\r
- {"+acpl": "holdable"}, #\ <co id="CO7-5"/>\r
- {"+acpl": "opac_visible"} #\ <co id="CO7-6"/>\r
- ]}\r
-\r
-Received Data: {\r
- "barcode":"BARCODE1",\r
- "name":"Stacks"\r
-}\r
-\r
-Received Data: {\r
- "barcode":"BARCODE2",\r
- "name":"Stacks"\r
-}</programlisting>\r
-<calloutlist>\r
-<callout arearefs="CO7-1">\r
-<simpara>\r
-Invoke the <literal>json_query</literal> service.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO7-2">\r
-<simpara>\r
-Select the <literal>barcode</literal> field from the <literal>acp</literal> class and the <literal>name</literal>\r
-field from the <literal>acpl</literal> class.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO7-3">\r
-<simpara>\r
-Join the <literal>acp</literal> class to the <literal>acpl</literal> class based on the linked field\r
-defined in the IDL.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO7-4">\r
-<simpara>\r
-Add a <literal>where</literal> clause to filter the results. We have more than one\r
-condition beginning with the same key, so we wrap the conditions inside\r
-an array.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO7-5">\r
-<simpara>\r
-The first condition tests whether the boolean value of the <literal>holdable</literal>\r
-field on the <literal>acpl</literal> class is true.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO7-6">\r
-<simpara>\r
-The second condition tests whether the boolean value of the\r
-<literal>opac_visible</literal> field on the <literal>acpl</literal> class is true.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-<simpara>For thorough coverage of the breadth of support offered by JSON\r
-query syntax, see <ulink url="http://open-ils.org/dokuwiki/doku.php?id=documentation:technical:jsontutorial">JSON Queries: A Tutorial</ulink>.</simpara>\r
-</section>\r
-<section id="_fleshing_linked_objects">\r
-<title>Fleshing linked objects</title>\r
-<simpara>A simplistic approach to retrieving a set of objects that are linked to\r
-an object that you are retrieving - for example, a set of call numbers\r
-linked to the barcodes that a given user has borrowed - would be to:\r
- 1. Retrieve the list of circulation objects (<literal>circ</literal> class)\r
-for a given user (<literal>usr</literal> class).\r
- 2. For each circulation object, look up the target copy (<literal>target_copy</literal>\r
-field, linked to the <literal>acp</literal> class).\r
- 3. For each copy, look up the call number for that copy (<literal>call_number</literal>\r
-field, linked to the <literal>acn</literal> class).</simpara>\r
-<simpara>However, this would result in potentially hundreds of round-trip\r
-queries from the client to the server. Even with low-latency connections,\r
-the network overhead would be considerable. So, built into the <literal>open-ils.cstore</literal> and\r
-<literal>open-ils.pcrud</literal> access methods is the ability to <emphasis>flesh</emphasis> linked fields -\r
-that is, rather than return an identifier to a given linked field,\r
-the method can return the entire object as part of the initial response.</simpara>\r
-<simpara>Most of the interfaces that return class instances from the IDL offer the\r
-ability to flesh returned fields. For example, the\r
-<literal>open-ils.cstore.direct.\*.retrieve</literal> methods allow you to specify a\r
-JSON structure defining the fields you wish to flesh in the returned object.</simpara>\r
-<formalpara><title>Fleshing fields in objects returned by <literal>open-ils.cstore</literal></title><para>\r
-<programlisting language="sh" linenumbering="unnumbered">srfsh# request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \\r
- {\r
- "flesh": 1, #\ <co id="CO8-1"/>\r
- "flesh_fields": { #\ <co id="CO8-2"/>\r
- "acp": ["location"]\r
- }\r
- }</programlisting>\r
-</para></formalpara>\r
-<calloutlist>\r
-<callout arearefs="CO8-1">\r
-<simpara>\r
-The <literal>flesh</literal> argument is the depth at which objects should be fleshed.\r
-For example, to flesh out a field that links to another object that includes\r
-a field that links to another object, you would specify a depth of 2.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="CO8-2">\r
-<simpara>\r
-The <literal>flesh_fields</literal> argument contains a list of objects with the fields\r
-to flesh for each object.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-<simpara>Let’s flesh things a little deeper. In addition to the copy location,\r
-let’s also flesh the call number attached to the copy, and then flesh\r
-the bibliographic record attached to the call number.</simpara>\r
-<formalpara><title>Fleshing fields in fields of objects returned by <literal>open-ils.cstore</literal></title><para>\r
-<programlisting language="java" linenumbering="unnumbered">request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \\r
- {\r
- "flesh": 2,\r
- "flesh_fields": {\r
- "acp": ["location", "call_number"],\r
- "acn": ["record"]\r
- }\r
- }</programlisting>\r
-</para></formalpara>\r
-</section>\r
-</section>\r
-<section id="_adding_an_idl_entry_for_resolverresolver">\r
-<title>Adding an IDL entry for ResolverResolver</title>\r
-<simpara>Most OpenSRF methods in Evergreen define their object interface in the\r
-IDL. Without an entry in the IDL, the prospective caller of a given\r
-method is forced to either call the method and inspect the returned\r
-contents, or read the source to work out the structure of the JSON\r
-payload. At this stage of the tutorial, we have not defined an entry\r
-in the IDL to represent the object returned by the\r
-<literal>open-ils.resolver.resolve_holdings</literal> method. It is time to complete\r
-that task.</simpara>\r
-<simpara>The <literal>open-ils.resolver</literal> service is unlike many of the other classes\r
-defined in the IDL because its data is not stored in the Evergreen\r
-database. Instead, the data is requested from an external Web service\r
-and only temporarily cached in <literal>memcached</literal>. Fortunately, the IDL\r
-enables us to represent this kind of class by setting the\r
-<literal>oils_persist:virtual</literal> class attribute to <literal>true</literal>.</simpara>\r
-<simpara>So, let’s add an entry to the IDL for the <literal>open-ils.resolver.resolve_holdings</literal>\r
-service:</simpara>\r
-<programlisting language="xml" linenumbering="unnumbered"></programlisting>\r
-<simpara>And let’s make <literal>ResolverResolver.pm</literal> return an array composed of our new\r
-<literal>rhr</literal> classes rather than raw JSON objects:</simpara>\r
-<programlisting language="perl" linenumbering="unnumbered"></programlisting>\r
-<simpara>Once we add the new entry to the IDL and copy the revised <literal>ResolverResolver.pm</literal>\r
-Perl module to <literal>/openils/lib/perl5/OpenILS/Application/</literal>, we need to:</simpara>\r
-<orderedlist numeration="arabic">\r
-<listitem>\r
-<simpara>\r
-Copy the updated IDL to both the <literal>/openils/conf/</literal> and\r
-<literal>/openils/var/web/reports/</literal> directories. The Dojo approach to\r
-parsing the IDL uses the IDL stored in the reports directory.\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Restart the Perl services to make the new IDL visible to the services\r
-and refresh the <literal>open-ils.resolver</literal> implementation\r
-</simpara>\r
-</listitem>\r
-<listitem>\r
-<simpara>\r
-Rerun <literal>/openils/bin/autogen.sh</literal> to regenerate the JavaScript versions\r
-of the IDL required by the HTTP translator and gateway.\r
-</simpara>\r
-</listitem>\r
-</orderedlist>\r
-<simpara>We also need to adjust our JavaScript client to use the nifty new\r
-objects that <literal>open-ils.resolver.resolve_holdings</literal> now returns.\r
-The best approach is to use the support in Evergreen’s Dojo extensions\r
-to generate the JavaScript classes directly from the IDL XML file.</simpara>\r
-<formalpara><title>Accessing classes defined in the IDL via Fieldmapper</title><para>\r
-<programlisting language="html" linenumbering="unnumbered"></programlisting>\r
-</para></formalpara>\r
-<calloutlist>\r
-<callout arearefs="">\r
-<simpara>\r
-Load the Dojo core.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-<literal>fieldmapper.AutoIDL</literal> reads <literal>/openils/var/reports/fm_IDL.xml</literal> to\r
-generate a list of class properties.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-<literal>fieldmapper.dojoData</literal> seems to provide a store for Evergreen data\r
-accessed via Dojo.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-<literal>fieldmapper.Fieldmapper</literal> converts the list of class properties into\r
-actual classes.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-<literal>fieldmapper.standardRequest</literal> invokes an OpenSRF method and returns\r
-an array of objects.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The first argument to <literal>fieldmapper.standardRequest</literal> is an array\r
-containing the OpenSRF service name and method name.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-The second argument to <literal>fieldmapper.standardRequest</literal> is an array\r
-containing the arguments to pass to the OpenSRF method.\r
-</simpara>\r
-</callout>\r
-<callout arearefs="">\r
-<simpara>\r
-As Fieldmapper has instantiated the returned objects based on their\r
-class hints, we can invoke getter/setter methods on the objects.\r
-</simpara>\r
-</callout>\r
-</calloutlist>\r
-</section>\r
-</section>\r
-<section id="_license">\r
-<title>License</title>\r
-<simpara>This work is licensed under a <ulink url="http://creativecommons.org/licenses/by-sa/2.5/ca/">Creative Commons Attribution-Share Alike 2.5 Canada License</ulink>.</simpara>\r
-</section>\r
-</chapter>\r
projects / transitory.git / commitdiff