From c604a0713379bbdbb735aa43acc72f6f1e00b24a Mon Sep 17 00:00:00 2001 From: Robert Soulliere Date: Wed, 10 Nov 2010 09:06:20 -0500 Subject: [PATCH] Add index terms. and remove files not being used. --- 1.6/admin/AdminMisc.xml | 12 +- 1.6/admin/Upgrading-Evergreen_1.6.xml | 10 +- 1.6/admin/actiontriggers.xml | 11 +- 1.6/admin/admin-booking.xml | 3 + 1.6/admin/admin-lsa.xml | 19 +- 1.6/admin/admin-receipt.xml | 1 + 1.6/admin/admin-survey.xml | 1 + 1.6/admin/localization.xml | 2 + 1.6/admin/migratingdata.xml | 15 +- 1.6/admin/requirements-configuration.xml | 7 +- 1.6/admin/serveradministration.xml | 58 +- 1.6/admin/serversideinstallation.xml | 51 +- 1.6/admin/staffclientinstallation.xml | 31 +- 1.6/admin/troubleshooting.xml | 3 +- 1.6/appendices/about_this_documentation.xml | 10 +- 1.6/appendices/bookindex.xml | 10 +- 1.6/appendices/glossary.xml | 81 +- 1.6/appendices/installchecklist.xml | 40 +- 1.6/appendices/more_info.xml | 10 +- 1.6/development/OpenSRF_intro.xml | 13 + 1.6/development/booking.xml | 196 --- 1.6/development/customize_opac.xml | 5 + 1.6/development/customizingstaffclient.xml | 2 + 1.6/development/datamodelsandaccess.xml | 14 +- 1.6/development/directoriesandFiles.xml | 8 + 1.6/development/introduction_to_sql.xml | 2 + 1.6/development/json.xml | 2 + 1.6/development/supercat.xml | 9 +- 1.6/development/workshop.xml | 1532 ------------------- 29 files changed, 281 insertions(+), 1877 deletions(-) delete mode 100644 1.6/development/booking.xml delete mode 100644 1.6/development/workshop.xml diff --git a/1.6/admin/AdminMisc.xml b/1.6/admin/AdminMisc.xml index 50f6dff883..55d4b9ec08 100644 --- a/1.6/admin/AdminMisc.xml +++ b/1.6/admin/AdminMisc.xml @@ -4,6 +4,7 @@ Server Operations and Maintenance + receipt template editor This chapter deals with basic server operations such as starting and stopping Evergreen as well wall security, backing up and troubleshooting Evergreen. @@ -57,6 +58,8 @@
Backing Up + databasesbacking up + Backing up your system files and data is a critical task for server and database administrators. Having a strategy for backing up and recovery could be the difference between a minor annoyance for users and a complete catastrophe. @@ -83,6 +86,7 @@ Backing up Evergreen Files + directoriesbacking up When you deploy Evergreen, you will probably customize many aspects of your system including the system configuration files, Apache configuration files, OPAC and Staff Client. In order to protect your investment of time, you should carefully consider the best approach to backing up @@ -116,6 +120,7 @@
Security + security As with an ILS and resource accessible from the world wide web careful consideration needs to be given to the security of your Evergreen servers and database. While it is impossible to cover all aspects of security, it is important to take several precautions when setting up production Evergreen site. @@ -148,10 +153,12 @@
Managing Log Files + logsmanaging Evergreen comes with a sophisticated logging system, but it is important to manage the OpenSRF and Evergreen logs. This section will provide a couple of log management techniques and tools. - Using the Log Rotate<indexterm><primary>logrotate</primary></indexterm> Utility to Manage Log Size + Using the <systemitem class="service">logrotate</systemitem> Utility to Manage Log Size + logsLog Rotate Fortunately, this is not a new problem for Unix administrators, and there are a number of ways of keeping your logs under control. On Debian and Ubuntu, for example, the logrotate utility controls when old log files are compressed and a new log file is started. @@ -175,6 +182,7 @@ size 50M Changing Logging Level for <application>Evergreen</application> + logslogging levels Change the Log Levels in your config files. Changing the level of logging will help narrow down errors. @@ -200,6 +208,7 @@ size 50M
Installing PostgreSQL from Source + databasesPostgreSQL Some Linux distributions, such as Debian Etch (4.0), do not offer PostgreSQL version 8.2 as an installable package. Before you continue, examine the software dependencies listed in to ensure that your Linux distribution supports the required version of PostgreSQL. @@ -268,6 +277,7 @@ pg_ctl -D /usr/local/pgsql/data -l /home/postgres/logfile start
Configuring PostgreSQL + databasesPostgreSQL The values of several PostreSQL configuration parameters may be changed for enhanced performance. The following table lists the default values and some suggested updates for several useful parameters: diff --git a/1.6/admin/Upgrading-Evergreen_1.6.xml b/1.6/admin/Upgrading-Evergreen_1.6.xml index bd39174066..b6f6295b85 100644 --- a/1.6/admin/Upgrading-Evergreen_1.6.xml +++ b/1.6/admin/Upgrading-Evergreen_1.6.xml @@ -10,7 +10,7 @@ service interruptions. All of the steps in this chapter are to be completed from the command line. - In the following instructions, you are asked to perform certain steps as either the root or opensrf user. + In the following instructions, you are asked to perform certain steps as either the root or opensrf user. Debian: To become the root user, issue the su command and enter the password of the root user. @@ -43,7 +43,7 @@ - Upgrading OpenSRF to 1.4OpenSRF1.2 + Upgrading OpenSRF to 1.4OpenSRF As the opensrf user, download and extract the source files for OpenSRF @@ -174,14 +174,14 @@ tar xzf Evergreen-ILS-1.6.1.2.tar.gz these values for your distribution of Debian or Ubuntu: - for Debian Etch (4.0) + for Debian Etch (4.0)LinuxDebian for Debian Lenny (5.0) for Ubuntu Hardy Heron - (8.04) + (8.04)LinuxUbuntu for Ubuntu Intrepid Ibex @@ -365,7 +365,7 @@ psql -f /usr/share/postgresql/8.4/contrib/pgxml.sql evergreen - As the postgres user on the PostgreSQL server, create a PostgreSQL user named evergreen for the database cluster: + As the postgres user on the PostgreSQL server, create a PostgreSQL user named evergreen for the database cluster: createuser -P -s evergreen Enter the password for the new PostgreSQL superuser (evergreen) diff --git a/1.6/admin/actiontriggers.xml b/1.6/admin/actiontriggers.xml index 0d532a51b7..29a88f309f 100644 --- a/1.6/admin/actiontriggers.xml +++ b/1.6/admin/actiontriggers.xml @@ -2,7 +2,8 @@ - Action Triggers + Action Triggers + action triggers 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 hold notifications. @@ -21,6 +22,7 @@
Event Definitions + action triggersevent definitions Event Definitions is the main tab and contains the key fields when working with action triggers. These fields include:
Action Trigger Event Definitions @@ -86,7 +88,8 @@
- Creating New Action Triggers + Creating Action Triggers + action triggerscreating From the top menu, select @@ -195,6 +198,7 @@ The following items are 90 days overdue and have been marked LOST.
Hooks + action triggershooks Hooks define the Fieldmapper class in the core_type column off of which the rest of the field definitions hang. Hooks @@ -231,6 +235,7 @@ The following items are 90 days overdue and have been marked LOST.
Reactors + action triggersreactors Reactors link the trigger definition to the action to be carried out.
Action Trigger Reactors @@ -261,6 +266,7 @@ The following items are 90 days overdue and have been marked LOST.
Validators + action triggersvalidators Validators set the validation test to be preformed to determine whether the action trigger is executed.
Action Trigger Validators @@ -291,6 +297,7 @@ The following items are 90 days overdue and have been marked LOST.
Processing Action Triggers + action triggersprocessing To run the action triggers, an Evergreen administrator will need to run the trigger processing script /openils/bin/action_trigger_runner.pl . This should be set up as a cron job to run periodically. diff --git a/1.6/admin/admin-booking.xml b/1.6/admin/admin-booking.xml index 1ddc57d57d..1a5ae446f8 100644 --- a/1.6/admin/admin-booking.xml +++ b/1.6/admin/admin-booking.xml @@ -19,6 +19,7 @@
Make a Cataloged Item Bookable in Advance + booking reservationmaking a cataloged item bookable If their permission settings allow, staff members can make items bookable. Staff members can do this in advance of a booking request, or they can do it on the fly. If you know in advance of the request that an item will need to be booked, you can make @@ -97,6 +98,7 @@
Create a Bookable Status for Non-Bibliographic Items + booking reservationnon-bibliographic items Staff with the required permissions can create a bookable status for non-bibliographic items. For example, staff can book conference rooms or laptops. You will be able to create types of resources, specify the names of individual resources within each type, and set @@ -232,6 +234,7 @@
Setting Booking Permissions + booking reservationsetting booking permissions Administrators can set permissions so that staff members can view reservations, make reservations, and make bibliographic or non-bibliographic items bookable. diff --git a/1.6/admin/admin-lsa.xml b/1.6/admin/admin-lsa.xml index ca9b4cd254..1e86c259ba 100644 --- a/1.6/admin/admin-lsa.xml +++ b/1.6/admin/admin-lsa.xml @@ -171,6 +171,8 @@
Global Font and Sound Settings + staff clientfonts + Global Font and Sound Settings apply to the current workstation only. Use to turn staff client sounds on/off or to adjust the font size in the staff client @@ -185,6 +187,7 @@ + staff clientsounds To turn off the system sounds, like the noise that happens when a patron with a block is retrieved check the disable sound box and click Save to Disk.   @@ -218,6 +221,7 @@
Printer Settings Editor + staff clientprinter settings Use the Printer Settings Editor to configure printer output for each workstation. @@ -264,6 +268,7 @@
Closed Dates Editor + closed dates editor These dates are in addition to your regular weekly closed days (see ).    Both regular closed days and those entered in the @@ -272,6 +277,7 @@ Due dates + closed dates editordue dates Due dates that would fall on closed days are automatically pushed forward to the next open day. Likewise, if an item is checked out at 8pm, for example, and would normally be due on a day when the library closes before 8pm, Evergreen @@ -281,6 +287,7 @@ Overdue fines + closed dates editorfines Overdue fines are not charged on days when the library is closed. @@ -353,6 +360,7 @@
Copy Locations Editor + copy locations editor @@ -432,6 +440,7 @@
Library Settings Editor + library settings editor With the Library Settings Editor Local System Admnistrators (LSAs) can optionally customize Evergreen's behaviour for a particular library or library system. @@ -901,6 +910,7 @@
Non-Catalogued Type Editor + non-catalogued type editor This is where you configure your non-catalogued types that appear in the dropdown menu @@ -960,6 +970,7 @@
Group Penalty Thresholds + group penalty thresholds Group Penalty Thresholds block circulation transactions for users who exceed maximum check out limits, number of overdue items, or fines. Settings for your library are @@ -1092,7 +1103,7 @@ Creating local penalty thresholds - + group penalty thresholdscreating local penalty thresholds Local System Administrators can override the system defaults by creating local penalty thresholds for selected patron groups. @@ -1221,6 +1232,7 @@
Statistical Categories Editor + statistical categories editor This is where you configure your statistical categories (stat cats).  Stat cats are a way to save and report on additional information that doesn’t fit elsewhere in Evergreen's @@ -1252,7 +1264,8 @@ - Copy stat cats + Copy Stat Cats + copy stat cats The image above shows some examples of copy stat cats. You would see these when editing items in the Copy Editor, also known as the Edit Item Attributes screen. You might use copy stat cats to track books you @@ -1275,6 +1288,7 @@ Patron stat cats + patron stat cats Below are some examples of patron stat cats.  Patron stat cats can be used to keep track of information like the high school a patron attends, or the home library for a consortium patron, e.g. Interlink. You would see these in the fifth screen of patron @@ -1306,6 +1320,7 @@
Cash Reports + cash reports diff --git a/1.6/admin/admin-receipt.xml b/1.6/admin/admin-receipt.xml index 50f8b460c3..4c4b843d1e 100644 --- a/1.6/admin/admin-receipt.xml +++ b/1.6/admin/admin-receipt.xml @@ -4,6 +4,7 @@ Receipt Template Editor + receipt template editor This tip sheet will show you how to customize your receipts.  This example will walk you diff --git a/1.6/admin/admin-survey.xml b/1.6/admin/admin-survey.xml index d7309af488..b84e95c1d5 100644 --- a/1.6/admin/admin-survey.xml +++ b/1.6/admin/admin-survey.xml @@ -3,6 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> Surveys + surveys This section illustrates how to create a survey, shows where the survey responses are saved in the patron record, and explains how to report on surveys. diff --git a/1.6/admin/localization.xml b/1.6/admin/localization.xml index ee396e7682..947b8536dc 100644 --- a/1.6/admin/localization.xml +++ b/1.6/admin/localization.xml @@ -11,6 +11,7 @@ all interfaces. Only a few steps are required to enable or disable one or more languages. Enabling a Localization + languagesenabling a localization 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 following example illustrates how to enable Canadian French (fr-CA) support in the database. These same steps can be used with any of the languages bundled with Evergreen, or you can create and add your own localization. @@ -56,6 +57,7 @@ VALUES ('fr-CA', 'fre', 'French (Canada)', 'Canadian French'); Disabling a Localization + languagesdisabling a localization 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 entries from the table config.i18n_locale using the psql utility: diff --git a/1.6/admin/migratingdata.xml b/1.6/admin/migratingdata.xml index 8494904d43..7d3c936864 100644 --- a/1.6/admin/migratingdata.xml +++ b/1.6/admin/migratingdata.xml @@ -11,6 +11,7 @@
Migrating Bibliographic Records + migratingimporting bibliographic records 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 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 @@ -21,6 +22,7 @@ http://svn.open-ils.org/trac/ILS/browser/branches/rel_1_6_1/Open-ILS/src/extras/import). Converting MARC records to Evergreen BRE JSON format + BRE JSON 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 record entry (hence bre) in Evergreen. marc2bre.pl can perform the following functions: @@ -99,6 +101,7 @@ Converting Records for Import into PostgreSQL + migratingimport into PostgreSQL Once you have your records in Evergreen's BRE JSON format, you then need to use direct_ingest.pl to convert the records into the generic ingest JSON format for Open-ILS. This step uses the open-ils.ingest application to extract the data that will be indexed in the database. @@ -109,6 +112,7 @@ Adding Metarecords to the Database + migratingadding metarecords One you have loaded the records into PostgreSQL, you can create metarecord entries in the metabib.metarecord table by running the following SQL: psql evergreen @@ -118,13 +122,15 @@
- Adding Copies to Bibliographic Records + Adding Copies to Bibliographic Records + migratingadding copies 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 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 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 well. Importing volumes and copies from <systemitem>MARC21XML</systemitem> holdings + migratingimporting volumes There is currently no simple method for importing holdings based on the contents of the MARC holdings field (852, as specified by http://www.loc.gov/marc/holdings/). However, a more or less automated method could be built that performs the following steps: @@ -157,6 +163,7 @@
Migrating Patron Data + migratingimporting patrons This section will explain the task of migrating your patron data from comma delimited filescomma delimited files into Evergreen. It does not deal with the process of exporting from the non-Evergreen @@ -316,6 +323,7 @@ COMMIT; Batch Updating Patron Data + migratingbatch updating patrons For academic libraries, doing batch updates to add new patrons to the Evergreen database is a critical task. The above procedures and 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, 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 @@ -326,7 +334,8 @@ COMMIT;
- Making electronic resources visible in the catalogue + Making Electronic Resources Visible in the Catalogue + migratingimporting bibliographic recordselectronic resources 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 bibliographic record to a value that matches the corresponding ID of the config.bib_source where the transcendant value is TRUE. Here's a practical example: @@ -360,6 +369,8 @@ COMMIT;
Restoring your Evergreen Database to an Empty State + databasesrestoring Evergreen to an empty state + importing bibliographic records 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 following: diff --git a/1.6/admin/requirements-configuration.xml b/1.6/admin/requirements-configuration.xml index efaa113b4d..4420124eef 100644 --- a/1.6/admin/requirements-configuration.xml +++ b/1.6/admin/requirements-configuration.xml @@ -29,7 +29,8 @@
- Server Hardware Configurations and Clusteringhardwareclustering + Server Hardware Configurations and Clustering + hardwareclustering The hardware requirements for running a functional Evergreen server are minimal. It is also possible to scale up your evergreen configuration to be spread your Evergreen resources and services over several or even many servers in a clustered approach for the purpose @@ -76,9 +77,7 @@ 512Mb of RAM - - Barcode Scanners - + Barcode Scanners Evergreen will work with virtually any barcode scannerbarcode scanner – if it worked with your legacy system it should work on Evergreen. diff --git a/1.6/admin/serveradministration.xml b/1.6/admin/serveradministration.xml index 982e16a373..91c0b26f3f 100644 --- a/1.6/admin/serveradministration.xml +++ b/1.6/admin/serveradministration.xml @@ -13,6 +13,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Organizational Unit Types and Organizational Units Organizational Unit Types + organizational unit types Organizational Unit Types are the terms used to refer to levels in the hierarchy of your library system(s). Examples could include>All-Encompassing Consortium, Consortium Within a Consortium, Library System, Branch, Bookmobile, Sub-Branch, Twig, etc. @@ -25,15 +26,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati may be difficult once you have loaded records or users. The fields in the organizational unit type record include: - Type Name - The name of the organization unit type. - Opac Label - This is the label displayed in the OPAC to describe the search + Type Name - The name of the organization unit type. + Opac Label - This is the label displayed in the OPAC to describe the search range and the copy count columns for results. They are range relative labels. - Parent Type - The parent organizational unit type of this type. - Can Have Volumes - Flag that allows an organizational unit of this type to contain + Parent Type - The parent organizational unit type of this type. + Can Have Volumes - Flag that allows an organizational unit of this type to contain Volumes/Call Numbers and thus Copies. - Can Have Users - Flag that allows an Organizational unit of this type to be home to + Can Have Users - Flag that allows an Organizational unit of this type to be home to Users. An organizational unit type can be added, edited, or removed using the staff client. @@ -45,7 +46,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Adding Organization Types<indexterm><primary>organization types</primary><secondary>adding</secondary></indexterm> + Adding Organization Types<indexterm><primary>organizational unit types</primary><secondary>adding</secondary></indexterm> Select an organization type from the organization type tree on the left and click New Child. Make sure your new type is selected and edit the Type Name, @@ -66,7 +67,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Deleting Organization Types<indexterm><primary>organization types</primary><secondary>deleting</secondary></indexterm> + Deleting Organization Types + organizational unit typesdeleting Select the organization type from the Organization Type tree. Click Delete. @@ -87,7 +89,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Editing Organization Types<indexterm><primary>organization types</primary><secondary>editing</secondary></indexterm> + Editing Organization Types<indexterm><primary>organizational unit types</primary><secondary>editing</secondary></indexterm> Select the organization type you wish to edit from the organization type tree. Make the changes in the right pane. @@ -103,7 +105,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Organizational Units<indexterm><primary>organization units</primary></indexterm> + Organizational Units + organizational units Organizational Units are the specific instances of the organization unit types that make up your library's hierarchy. These can include consortia, systems, branches, @@ -118,7 +121,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Adding Organizational Units<indexterm><primary>organization units</primary><secondary>adding</secondary></indexterm> + Adding Organizational Units + organization unitsadding Select an Organizational Unit from the organizational unit tree on the left and click New Child. Make sure your new unit is selected and edit the Organizational Unit @@ -147,7 +151,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Deleting Organizational Units <indexterm><primary>organization units</primary><secondary>deleting</secondary></indexterm> + Deleting Organizational Units + organization unitsdeleting Select the organizational unit you wish to delete from the organizational unit tree in the left pane. ClickDelete. Click OK on the warning alert box. @@ -1511,6 +1516,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati
Copy Status + copy status To navigate to the copy status editor from the staff client menu, select Admin Server Administration Copy Statuses @@ -1668,12 +1674,14 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati
Billing Types + billing types The billing types editor is used for creating, editing and deleting billing types. To navigate to the billing types editor from the staff client menu, select Admin Server Administration Billing Types Adding Billing Types + billing typesadding Click New Billing Type. Enter the name of the billing type. Select the Org Unit to use this billing type. @@ -1684,6 +1692,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Deleting Billing Types + billing typesdeleting Check the check box of the billing type(s) you wish to delete. Click Delete Selected. The selected billing types will be deleted without a @@ -1692,6 +1701,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Editing Billing Types + billing typesediting Double click on a billing types to open the editing window. Make desired changes to the name, Org Unit and Default Price. @@ -1702,6 +1712,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati
Circulation Modifiers + circulation modifiers The circulation modifier editor is used to create, edit and delete modifier categories to control circulation policies on specific groups of items. To navigate to the circulation modifiers editor from the staff client menu, select @@ -1711,6 +1722,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Adding Circulation Modifiers + circulation modifiersadding Click New Circ Modifier. Enter a Code, Name and Description. @@ -1722,6 +1734,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Deleting Circulation Modifiers + circulation modifiersdeleting Check the check box(es) next to the circulation modifiers(s) you wish to delete. Click Delete Selected near the top of the page. @@ -1731,6 +1744,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Editing Circulation Modifiers + circulation modifiersediting Double click on the row of the circulation modifier you wish to edit. Make desired changes. @@ -1740,6 +1754,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati
Cataloging Templates + catalogingtemplates 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 Adding Cataloging Templates @@ -1810,6 +1825,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati
Adjusting Search Relevancy Rankings + search relevancy This section describes indexed field weighting and matchpoint weighting, which @@ -1822,7 +1838,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Indexed-field Weighting<indexterm><primary>relevancy</primary><secondary>indexed-field weighting</secondary></indexterm> + Indexed-field Weighting<indexterm><primary>search relevancy</primary><secondary>indexed-field weighting</secondary></indexterm> Indexed-field weighting is configured in the Evergreen database in the weight column of the config.metabib_field table, which follows the other four columns in this table: field_class, name, xpath, and format. @@ -1837,7 +1853,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati jaguar in another indexed field. - Match point Weighting<indexterm><primary>relevancy</primary><secondary>match point weighting</secondary></indexterm> + Match point Weighting + search relevancymatch point weighting Match point weighting provides another way to fine-tune Evergreen relevance ranking, and is configured through floating-point multipliers in the multiplier column of the search.relevance_adjustment table. @@ -2021,6 +2038,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati Combining Index Weighting and Match point Weighting + search relevancycombining index weighting and match point weighting + Index weighting and matchpoint weighting may be combined. The relevance boost of the combined weighting is equal to the product of the two multiplied values. If the relevance setting in the config.metabib_field were increased to 2, and the multiplier @@ -2033,7 +2052,8 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="serveradministrati - Adjusting Relevancy for Keyword Searches<indexterm><primary>relevancy</primary><secondary>keyword searches</secondary></indexterm> + Adjusting Relevancy for Keyword Searches + search relevancykeyword search adjusting Searching the out of the box keyword does not boost the ranking for terms appearing in, the title or subject fields since there is just one 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 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 @@ -2097,6 +2117,7 @@ WHERE id = 17; 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.
Hold Notifications + notificationshold 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 is captured by a library staff member and the item is in the on holds shelf status. @@ -2175,7 +2196,8 @@ WHERE id = 17; Overdue and Predue Notifications 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. - Activating Overdue Existing Overdue Action Triggers + Activating the Existing Overdue Action Triggers + notificationsoverdueactivating action triggers The easiest way to set up overdue notifications is to use the Action Trigger mechanism introduced in Evergreen 1.6. @@ -2212,6 +2234,8 @@ WHERE id = 17; Creating Overdue and Predue Notifications by Cloning Existing Action Triggers + notificationsoverduecreating using action triggers + notificationspreduecreating using action triggers 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 unique Name, customize as needed. and save. There are no pre-existing predue notices so they will need to be created by cloning an existing overdue notice. @@ -2219,7 +2243,9 @@ WHERE id = 17; due date, use the value -1 days. - Creating Overdue and Predue Notices using the Evergreen Configuration File + Creating Overdue and Predue Notices using the Evergreen Configuration File + notificationsoverduecreating using the configuration file + notificationspreduecreating using the configuration file It is also possible to create overdue and predue notices using the Evergreen configuration file /openils/conf/opensrf.xml diff --git a/1.6/admin/serversideinstallation.xml b/1.6/admin/serversideinstallation.xml index 1ba1848cae..ad2efb9aab 100644 --- a/1.6/admin/serversideinstallation.xml +++ b/1.6/admin/serversideinstallation.xml @@ -32,6 +32,7 @@ listed here:
Evergreen Software Dependencies + Evergreen software dependencies @@ -79,8 +80,11 @@ take a final snapshot backup of your system(s). This can be the first in the series of regularly scheduled system backups that you should probably also begin.
+ OpenSRFinstallation Installing OpenSRF 1.4.x On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem> + LinuxDebian + LinuxUbuntu This section describes the installation of the latest version of the Open Service Request Framework (OpenSRF), a major component of the Evergreen server-side software, on Ubuntu or Debian @@ -133,6 +137,7 @@ Download and Unpack Latest OpenSRF Version + OpenSRFdownload As the opensrf user, download and extract the latest version of OpenSRF. The latest version can be found here: @@ -204,6 +209,7 @@ Configure OpenSRF + OpenSRFconfigure As the opensrf user, return to the OpenSRF build directory and use the configure utility to prepare for the next @@ -254,6 +260,7 @@ /etc/hosts. As the root user, edit the file /etc/hosts and add the following entries for our example domains: + Jabber 127.0.1.2 public.localhost public 127.0.1.3 private.localhost private @@ -273,6 +280,7 @@ Stop the <systemitem class="service">ejabberd</systemitem> Service + ejabberd As the root user, stop the ejabberd service: @@ -498,6 +506,7 @@ ejabberdctl register opensrf public.localhost In this section you will set up a special configuration file for each user who will need to run the srfsh (pronounced surf shell) utility. + srfsh The software installation will automatically create srfsh. This is a command line diagnostic tool for testing and interacting with OpenSRF. It will be used in a future @@ -622,6 +631,8 @@ srfsh#
Installing Evergreen 1.6.1.x On <systemitem class="osname">Ubuntu</systemitem> or <systemitem class="osname">Debian</systemitem> + LinuxDebian + LinuxUbuntu This section outlines the installation process for the latest stable version of Evergreen. In this section you will download, unpack, install, configure and test the Evergreen @@ -736,8 +747,9 @@ srfsh#
- + (OPTIONAL) Install the PostgreSQL Server + databasesPostgreSQL Since the PostgreSQL server is usually a standalone server in multi-server production systems, the prerequisite installer Makefile in the previous step does not automatically install PostgreSQL. You must install the PostgreSQL server @@ -790,6 +802,7 @@ srfsh# For more information on installing Perl Modules vist the official CPAN site. + PerlCPAN Update the System Dynamic Library Path @@ -807,7 +820,7 @@ srfsh# - (OPTIONAL) Restart the PostgreSQL Server + Restart the PostgreSQL Server If PostgreSQL is running on the same system as the rest of Evergreen, as the root user you must restart PostgreSQL to re-read the new library paths just configured. If PostgreSQL is @@ -873,6 +886,7 @@ srfsh# Create and Configure PostgreSQL Database + databasesPostgreSQL In this step you will create the Evergreen database. In the commands below, remember to adjust the path of the contrib repository to match your PostgreSQL server layout. For example, if you built PostgreSQL from source the path would be @@ -949,6 +963,7 @@ srfsh# Configure the Apache web server + web serverApache In this step you will configure the Apache web server to support Evergreen software. First, you must enable some built-in Apache modules and install @@ -1080,32 +1095,6 @@ srfsh# - - (OPTIONAL) Apache Performance Modifications - Some further configuration changes to Apache may be - necessary for busy systems. These changes increase the - number of Apache server processes that are started to - support additional browser connections. - As the root - user, edit the Apache configuration file - /etc/apache2/apache2.conf and add the - lines KeepAliveTimeout 1 and - MaxKeepAliveRequests 100, or modify any - existing lines. Then locate the section related to - prefork configuration and modify it - to suit the load on your system: - - - StartServers 20 - MinSpareServers 5 - MaxSpareServers 15 - MaxClients 150 - MaxRequestsPerChild 10000 - -]]> - - Enable the Evergreen web site Finally, you must enable the Evergreen web site. As the @@ -1458,7 +1447,7 @@ Updating fieldmapper
- (OPTIONAL) Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments + Installing In Virtualized <systemitem class="osname">Linux</systemitem> Environments This section describes the installation of Evergreen software in so-called "virtualized" software environments. Evergreen software runs as a native application on any of several well-known x86 (32-bit) and x86-64 (64-bit) Linux @@ -1499,7 +1488,8 @@ Updating fieldmapper http://virtualbox.org and follow the on screen instructions to install the software. - Installing <application>"VMware"</application> Virtualization Software + Installing VMware Virtualization Software + virtualization softwareVMware This section reviews installation of the "VMware" application on WindowsXP Professional (SP2). Find and Download the free virtual machine software of from the VMware official website: http://downloads.vmware.com and follow the on @@ -1581,6 +1571,7 @@ Updating fieldmapper VirtualBox Example + virtualization softwareVirtualBox Start VirtualBox for the first time and select FileVirtualBox Media diff --git a/1.6/admin/staffclientinstallation.xml b/1.6/admin/staffclientinstallation.xml index 05c46becb0..259d6bd9bf 100644 --- a/1.6/admin/staffclientinstallation.xml +++ b/1.6/admin/staffclientinstallation.xml @@ -8,11 +8,13 @@
Installing the Staff Client + staff clientinstalling Installing a Pre-Built Staff Client You can install the pre-built Staff Client available for Windows, MAC or Linux. Installing on Windows + staff clientinstallingWindows A standard Microsoft Windows installer that contains the current version of the Staff Client is available from the downloads section of the Evergreen website at http://www.evergreen-ils.org/downloads.php. Download the Staff Client installer, then run it. A screen that looks similar to this should appear: @@ -44,6 +46,7 @@ Installing on Mac OS + staff clientinstallingMac OS A Mac package that contains the current version of the Staff Client is available for use with XULRunner. Evergreen Indiana Pkg file [Evergreen v1.2.3.0] @@ -85,6 +88,8 @@ Running directly using XULRunner + staff clientXULRunner + XULRunner You must install an apropriate version of XULRunner to match the Evergreen version. See the following table for the recommended version of XULRunner: Evergreen / XULRunner Dependencies @@ -120,6 +125,7 @@ Removing previously installed XULRunner versions + XULRunnerremoving previous versions If you already have a newer version installed, per the release notes, you will need to remove the entire directory /Library/Frameworks/XUL.framework before downgrading. In addition, you may also need to remove the previous file /Library/Receipts/xulrunner-ver-mak.pkg . @@ -249,6 +255,7 @@ ______* etc. Building the Staff Client on the Server + staff clientbuilding on the server A Linux Staff Client is automatically built on the server as part of the normal make install process for Evergreen server-side software, using a procedure similar to this: @@ -385,7 +392,8 @@ ______* etc. - Using Wine to Install On Linux + Using Wine to Install on Linux + staff clientusing wine to install on Linux The Linux application Wine is another alternative if you wish to install the packaged Windows versions rather than building 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 the Staff Client. More information about Wine can be found at @@ -432,6 +440,7 @@ ______* etc. Assigning Workstation Names + staff clientassigning workstation names 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 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 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. @@ -471,6 +480,7 @@ ______* etc. Building the Staff Client + staff clientbuilding You can also manually build the Staff Client by using the make utility in the Staff Client source directory (e.g., the directory /home/opensrf/Evergreen-ILS-1.6.0.x/Open-ILS/xul/staff_client for the current Evergreen version). There are a number of 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 @@ -541,6 +551,7 @@ ______* etc. Advanced Build Options + staff clientbuildingadvanced build options 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 make utility and require that you build the Staff Client from its source directory. See the following table for a list of possible make target keywords: @@ -612,7 +623,7 @@ ______* etc. Developer Build - You can create a so-called "developer build" of the Staff Client by substituting "devbuild" for "build" when running make. + You can create a so-called developer build of the Staff Client by substituting for when running make. The build will contain an extra configuration file that enables some developer options. As the opensrf user, run make from the Staff Client source directory: @@ -623,7 +634,8 @@ ______* etc. Compressed Javascript - You can execute the Google "Closure Compiler" utility to automatically review and compress Javascript code after the build process completes, + You can execute the Google Closure Compiler utility to automatically review and compress + Javascript code after the build process completes, by substituting for "build" when running make. For more information see Google Closure Compiler. As the opensrf user, run the following commands from the Staff Client source directory: @@ -632,7 +644,7 @@ ______* etc. cd /home/opensrf/[Evergreen Install Directory]/Open-ILS/xul/staff_client make compress-javascript - You can also combine Javascript review and compression, and also perform a "developer build". + You can also combine Javascript review and compression, and also perform a developer build. As the opensrf user, run the following commands from the Staff Client source directory: In the following make below, the order of options is important! @@ -761,10 +773,10 @@ ______* etc. Staff Client Automatic Updates + staff clientautomatic updates 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 Staff Client with certain special options. - - WARNINGS + Automatic update server certificate requirements are more strict than normal server requirements. Firefox and XULRunner will 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 accept them WILL NOT WORK. @@ -775,7 +787,7 @@ ______* etc. You can pre-install the signing key into the file install.rdf directly, or install it into a copy as install.mccoy.rdf. If the latter exists it will be copied into the build instead of the original file install.rdf. - + Autoupdate Host The name of the automatic update host can be provided in either of two ways: @@ -809,6 +821,7 @@ ______* etc. Building Updates + staff clientautomatic updatesbuilding Similar to building clients, the targets , , , and can be used individually with make to build the update files for the Staff Client. To build all the targets at once, simply use the target . @@ -842,6 +855,7 @@ ______* etc. Building updates with clients + staff clientautomatic updatesbuilding with clients To save time and effort you can build updates and manual download clients at the same time by adding to each target name. For instance, you can specify . You can also specify to build all the targets at once. This does not work for . @@ -871,6 +885,7 @@ ______* etc. Activating the Update Server + staff clientautomatic updatesactivating the update server This section reviews scripts associated with the update server, and requires some final adjustments to file permissions. The Apache example configuration creates an "updates" directory that, by default, points to the directory /openils/var/updates/pub. This directory contains one HTML file and several specially-named script files. @@ -917,6 +932,7 @@ ______* etc.
Running the Staff Client + staff clientrunninglinux Run the Staff Client on a Linux system by using the application XULRunner (installed automatically and by default with Firefox version 3.0 and later on Ubuntu and Debian distributions). For example, if the source files for the Evergreen installation are in the directory /home/opensrf/[Evergreen Install Directory]/, start @@ -927,6 +943,7 @@ ______* etc. Running the Staff Client over an SSH Tunnel + staff clientrunning through an SSH tunnel The Staff Client can use an SSH tunnel as a SOCKS 5 proxy. Configuring a Proxy for the Staff Client diff --git a/1.6/admin/troubleshooting.xml b/1.6/admin/troubleshooting.xml index 75737794b3..84dcd09750 100644 --- a/1.6/admin/troubleshooting.xml +++ b/1.6/admin/troubleshooting.xml @@ -289,10 +289,11 @@ $ Follow the steps in the troubleshooting guide in . - Try to login from the staff client + Try to login from the staff clientstaff clienttesting Testing the Catalog + OPACtesting By default, the OPAC will live at the URL http://my.domain.com/opac/. 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 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 diff --git a/1.6/appendices/about_this_documentation.xml b/1.6/appendices/about_this_documentation.xml index 1f9b1b8810..eb3d7bacd6 100644 --- a/1.6/appendices/about_this_documentation.xml +++ b/1.6/appendices/about_this_documentation.xml @@ -101,10 +101,6 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="about_this_documen Rod Schiffman Alpha-G Consulting - - Chris Sharp - Georgia Public Library Service - Steve Sheppard Open @@ -175,7 +171,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="about_this_documen would not be possible.
- How to Participate + How to ParticipateDocumentation Interest Group (DIG) 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 experts, more easily spotting the places where documentation is lacking or where it is unclear. We welcome your contribution with planning, writing, editing, testing, translating to DocBook, and other tasks. Whatever your background or experience we are keen to @@ -184,7 +180,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="about_this_documen Join the Evergreen documentation listserv: list.georgialibraries.org/mailman/listinfo/open-ils-documentation . This is the primary way we communicate with each other. - Please send an email introducing yourself to the list. + Please send an email introducing yourself to the list.mailing lists Add yourself to the participant list if you have an Evergreen DokuWiki account, or send a request to docs@evergreen-ils.org. Check out the documentation outline to see which areas need work, @@ -203,7 +199,7 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="about_this_documen XML conversion – Convert existing documentation to DocBook format. Editorial review – Ensuring the documentation is clear and follows Evergreen DIG style guide conventions. - Style and Design – Edit the DocBook style sheets or post style tips and suggestions on the DIG list. + Style and Design – Edit the DocBook style sheets or post style tips and suggestions on the DIG list.DocBook
diff --git a/1.6/appendices/bookindex.xml b/1.6/appendices/bookindex.xml index 261c6ec735..82d9a74ada 100755 --- a/1.6/appendices/bookindex.xml +++ b/1.6/appendices/bookindex.xml @@ -1,5 +1,5 @@ - - -Index - - + + +Index + + diff --git a/1.6/appendices/glossary.xml b/1.6/appendices/glossary.xml index e612a96558..cd7bfe1b7d 100644 --- a/1.6/appendices/glossary.xml +++ b/1.6/appendices/glossary.xml @@ -7,7 +7,7 @@ A - Apache + ApacheApache 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 apache.org. @@ -16,7 +16,7 @@ B - Bookbags + Bookbagsbookbags 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, 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 @@ -33,7 +33,7 @@ - CPAN + CPANPerlCPAN An open-source archive of software modules written in Perl. More information is available at www.cpan.org. @@ -42,13 +42,13 @@ D - Debian + DebianLinuxDebian One of the most popular open-source operating system using the Linux kernel that provides over 25000 useful precompiled software packages. Also known as Debian GNU/Linux. More information is available at www.debian.org. - Domain name + Domain namedomain name 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.: www.esilibrary.com). Domain names can be reserved via third-party registration services, and can be associated with a unique IP address or suite of IP addresses. @@ -58,7 +58,7 @@ E - ejabberd + ejabberdejabberd An open-source Jabber/XMPP instant messaging server that runs under popular operating systems (e.g., Mac OSX, GNU/Linux, and Microsoft Windows). One popular use is to provide XMPP messaging services for a Jabber domain across an extendable cluster of cheap, easily-replaced machine nodes. More information is available at http://www.ejabberd.im. @@ -81,13 +81,14 @@ I - IP Address + IP AddressIP Address (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"). - Item/copy Buckets + Item/copy Bucketscopy bucketsitem buckets + item bucketscopy buckets Virtual containers to use in batch processing of item or copy records. They can be used to perform various cataloging/holdings maintenance tasks in batch. @@ -97,7 +98,7 @@ J - Jabber + JabberjabberXMPP Now known as XMPP (eXtensible Messaging and Presence Protocol), it was originally named "Jabber". @@ -115,13 +116,13 @@ M - MARC + MARCMARC The MARC formats are standards for the representation and communication of bibliographic and related information in machine-readable form. - MARCXML + MARCXMLMARCXML Framework for working with MARC data in a XML environment. @@ -134,7 +135,7 @@ - memcached + memcachedmemcached A general-purpose distributed memory caching system, usually with a client~server architecture spread over multiple computing systems. It reduces the number of times a data source (e.g., a database) must be directly accessed by temporarily caching data in memory, therefore dramatically speeding up database-driven @@ -145,7 +146,7 @@ N - Network address + Network addressnetwork addressip address Also known as an IP address (Internet Protocol address). @@ -162,14 +163,14 @@ O - OPAC + OPACOPAC The "Online Public Access Catalog"; an online database of a library's holdings; used to find resources in their collections; possibly searchable by keyword, title, author, subject or call number. - OpenSRF + OpenSRFOpenSRF The "Open Scalable Request Framework" (pronounced 'open surf') is a stateful, decentralized service architecture that allows developers to create applications for Evergreen with a minimum of knowledge of its structure. @@ -179,13 +180,13 @@ P - PostgreSQL + PostgreSQLdatabasesPostgreSQL A popular open-source object-relational database management system that underpins Evergreen software. - Putty + PuttySSHPutty A popular open-source telnet/ssh client for the Windows and Unix platforms. More information is available at http://www.chiark.greenend.org.uk/~sgtatham/putty/. @@ -208,34 +209,34 @@ S - + SIPSIP 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 devices. - + srfsh srfsh A command language interpreter (shell) that executes commands read from the standard input. It is used to test the Open Service Request Framework (OpenSRF). - SRU + SRUSRU SRU is a standard XML-focused search protocol for Internet search queries, utilizing CQL (Contextual Query Language), a standard syntax for representing queries. - SSH + SSHSSH An encrypted network protocol using public-key cryptography that allows secure communications between systems on an insecure network. Typically used to access shell accounts but also supports tunneling, forwarding TCP ports and X11 connections, and transferring files. - SSH proxy + SSH proxySSHproxy 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. @@ -244,7 +245,7 @@ - SSH tunnel + SSH tunnelSSHtunneling An encrypted data channel existing over an SSH network connection. Used to securely transfer unencrypted data streams over insecure networks. @@ -252,7 +253,7 @@ - SSL Certificate + SSL CertificateSSL A special electronic document used to guarantee authenticity of a digital message. Also known as a "public key", or "identity" or "digital" certificate. It 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, @@ -263,7 +264,7 @@ T - tunneling + tunnelingtunnelingSSH tunneling A method of encapsulating data provided in one network protocol (the "delivery" protocol), within data in a different network protocol (the "tunneling" 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 @@ -275,7 +276,7 @@ U - Ubuntu + UbuntuLinuxUbuntu A popular open-source operating system using the Linux kernel that was originally based on the Debian GNU/Linux operating system. More information is available at www.ubuntu.com. @@ -286,7 +287,7 @@ V - Virtualization + Virtualizationvirtualization A method of executing software in a special environment that is partitioned or separated from the real underlying hardware and software resources. In typical usage, it allows a host operating system to encapsulate or emulate another operating system environment in such a way that the emulated environment @@ -295,7 +296,7 @@ - VirtualBox + VirtualBoxvirtualization softwareVirtualBox A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It can be installed on Linux, Mac OS X, Windows or @@ -305,7 +306,7 @@ - Virtual PC + Virtual PCvirtualization softwareVirtual PC A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It is installed on a Windows "host" operating system and allows other "guest" (typically including Linux and Windows) operating systems to @@ -314,14 +315,14 @@ - Volume Buckets + Volume Bucketsvolume buckets Virtual containers to use in batch processing of multiple volumes. They can be used to perform various cataloging/holdings maintenance tasks in batch. - VMware + VMwarevirtualization softwareVMware A popular commercial package of virtualization software that emulates the x86 microprocessor architecture. It can be installed on Linux, Mac OS X, Windows or Solaris "host" operating systems and allows other "guest" (typically including Linux and Windows) operating systems to be loaded and executed. @@ -331,7 +332,7 @@ W - Wine + WineLinuxWine A popular open-source application that allows Linux and Unix systems to run Windows executables. More information is available at http://www.winehq.org/. @@ -341,14 +342,14 @@ X - XML + XMLXML 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 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). - XMPP + XMPPXMPPjabber An open-standard communications protocol, based on XML, used in message-oriented middleware. It supports the concept of a consistent domain of message types that flow between software applications, possibly on different operating systems and architectures. More information is available at @@ -357,7 +358,7 @@ - xpath + xpathxpath 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 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 @@ -365,7 +366,7 @@ - XUL + XULxUL The XML User Interface Language, a specialized interface language that allows building cross-platform applications that drive Mozilla -based browsers such as Firefox. More information is available at @@ -373,7 +374,7 @@ - xulrunner + xulrunnerXULRunner A specialized run-time application environment that provides support for installing, upgrading and uninstalling XUL applications. It operates with Mozilla-based applications such as the Firefox browser. More information is available at @@ -385,12 +386,12 @@ Y - YAZ + YAZyaz A programmers’ toolkit supporting the development of Z39.50/SRW/SRU clients and servers. - + yaz yaz-client Z39.50/SRU client for connecting to YAZ servers. @@ -400,7 +401,7 @@ Z - Z39.50 + Z39.50Z39.50 A client–server protocol for searching and retrieving information from remote computer databases. diff --git a/1.6/appendices/installchecklist.xml b/1.6/appendices/installchecklist.xml index 10f768d1d2..567c868697 100644 --- a/1.6/appendices/installchecklist.xml +++ b/1.6/appendices/installchecklist.xml @@ -9,76 +9,76 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="install_checklist" - Install OpenSRF + Install OpenSRFOpenSRF Install Evergreen server software - Install Evergreen staff client + Install Evergreen staff clientstaff client Establish a back up strategy for Evergreen data and files - Configure PostgreSQL for better performance + Configure PostgreSQL for better performancePostgreSQL - Configure Evergreen error logging + Configure Evergreen error logginglogs - Set up organizational unit types + Set up organizational unit typesorganizational unit types - Set up organizational units + Set up organizational unitsorganizational units - Customize localization and languages (optional) + Customize localization and languages (optional)localization and languages - Add circ modifiers + Add circ modifierscirculation modifiers - Configure copy statuses + Configure copy statusescopy status - Add cataloguing templates + Add cataloguing templatescataloguing templates - Add user groups and assign permissions + Add user groups and assign permissionspermissions Adjust various Local Administration Settings - Adjust circulation policies and penalty threshholds for groups + Adjust circulation policies and penalty threshholds for groupspenalty threshholds Add staff users - Customize OPAC as needed + Customize OPAC as neededOPACcustomizing - Import data + Import datamigratingimporting data - Start the reporter service and set up reports + Start the reporter service and set up reportsreportsstarting - Set up email notifications for holds and overdue items + Set up email notifications for holds and overdue itemsnotifications - Set up action triggers + Set up action triggersaction triggers - Set up z39.50 server (optional) + Set up Z39.50 server (optional)Z39.50 - Adjust search relevancy settings if required (optional) + Adjust search relevancy settings if required (optional)search relevancy - Install SIP server (optional) - for communications with automated devices such as self check stations, autmated sorters and other devices using SIP + Install SIP server (optional) - for communications with automated devices such as self check stations, autmated sorters and other devices using SIPSIP diff --git a/1.6/appendices/more_info.xml b/1.6/appendices/more_info.xml index 96094ee0e3..d8c36228bb 100644 --- a/1.6/appendices/more_info.xml +++ b/1.6/appendices/more_info.xml @@ -6,15 +6,15 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="more_info"> 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 you might have. - Evergreen Wiki - Loads of information and the main portal to the Evergreen community. + Evergreen Wiki - Loads of information and the main portal to the Evergreen community.wiki Evergreen mailing lists - These are excellent for initiating questions. There are several lists including: General list - General inquiries regarding Evergreen. If unsure about - which list to use, this is a good stating point. + which list to use, this is a good stating point.mailing lists Developer list - Technical questions should be asked here including questions regarding installation. As well, patches can be submitted using this list and developer communication also takes place here. DIG list - This list is used for questions and - feedback regarding this documentation, the Documentation Interest Group and other documentation related ideas and issues. + feedback regarding this documentation, the Documentation Interest Group and other documentation related ideas and issues.Documentation Interest Group (DIG) Evergreen Blog - Great for getting general news and updates about Evergreen. It is also an interesting historical read @@ -22,10 +22,10 @@ xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="more_info"> Evergreen IRC channel - Allows live chat. Many developers hang out here and will try to field technical questions. This 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 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 - IRC page. + IRC page.IRC chat Evergreen related community blogs - Evergreen related blog entries from the community. Resource Sharing Cooperative of Evergreen Libraries (RSCEL) - Provides some technical documents and a means for the - Evergreen community to collaborate with other libraries. + Evergreen community to collaborate with other libraries.Resource Sharing Cooperative of Evergreen Libraries (RSCEL) List of current Evergreen libraries - Locate other libraries who are using Evergreen. diff --git a/1.6/development/OpenSRF_intro.xml b/1.6/development/OpenSRF_intro.xml index 150b46e339..466d1f75b0 100644 --- a/1.6/development/OpenSRF_intro.xml +++ b/1.6/development/OpenSRF_intro.xml @@ -14,6 +14,7 @@
Introducing OpenSRF + OpenSRF OpenSRF is a message routing network that offers scalability and failover support for individual services and entire servers with minimal development and deployment overhead. You can use OpenSRF to build loosely-coupled applications @@ -68,6 +69,7 @@ Protocol (XMPP, sometimes referred to as Jabber) - provides the base messaging infrastructure between OpenSRF clients and services + XMPP @@ -79,12 +81,14 @@ memcached - provides the caching service + memcached syslog - the standard UNIX logging service + syslog Unfortunately, the @@ -97,6 +101,7 @@ The recommended option for would-be developers of another language binding is to use the Python implementation as the cleanest basis for a port to another language. + Python
@@ -190,11 +195,13 @@ __PACKAGE__->register_method( this for a new service if the new service needs to be accessible via the public router. + configuration filesopensrf_core.xml Begin by defining the service itself in opensrf.xml. To register the opensrf.simple-text service, add the following section to the <apps> element (corresponding to the XPath /opensrf/default/apps/): + configuration filesopensrf.xml <apps> <opensrf.simple-text> @@ -355,6 +362,7 @@ __PACKAGE__->register_method( Calling an OpenSRF method + srfsh OpenSRF clients in any supported language can invoke OpenSRF services in any supported language. So let’s see a few examples of how we can call our fancy new opensrf.simple-text.reverse() method: @@ -649,6 +657,7 @@ __PACKAGE__->register_method( relationships to other objects, the permissions required to create, read, update, or delete objects of that type, and the database table or view on which they are based. + Fieldmapper The Evergreen fieldmapper offers a great deal of convenience for working with complex system objects beyond the basic mapping of classes to database schemas. Although the result is passed over the wire as a JSON object @@ -1001,6 +1010,7 @@ my $logger = OpenSRF::Utils::Logger; Caching results: one secret of scalability + search resultscaching If you have ever used an application that depends on a remote Web service outside of your control — say, if you need to retrieve results from a microblogging service — you know the pain of latency and dependability (or the @@ -1163,6 +1173,7 @@ sub test_cache {
OpenSRF Communication Flows + OpenSRFCommunication Flows Now that you have seen that it truly is easy to create an OpenSRF service, we can take a look at what is going on under the covers to make all of this work for you. @@ -1194,6 +1205,7 @@ sub test_cache { OpenSRF communication flows over XMPP + XMPP In a minimal OpenSRF deployment, two XMPP users named "router" connect to the XMPP server, with one connected to the private XMPP domain and one connected to the public XMPP domain. Similarly, two XMPP users named "opensrf" connect to @@ -1233,6 +1245,7 @@ sub test_cache { OpenSRF communication flows over HTTP + HTTPtranslator In some contexts, access to a full XMPP client is not a practical option. For example, while XMPP clients have been implemented in JavaScript, you might be concerned about browser compatibility and processing overhead - or you might diff --git a/1.6/development/booking.xml b/1.6/development/booking.xml deleted file mode 100644 index 2e61316a16..0000000000 --- a/1.6/development/booking.xml +++ /dev/null @@ -1,196 +0,0 @@ - - - - Using the Booking Module - - 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- - bibliographic items; create pull lists for reserved items; capture resources; and pick up and - return reservations. - - - -
- Creating a Booking Reservation - Only staff members can create reservations. To initiate a reservation, staff can - - search the catalog, - enter a patron record, - or use the booking module. - - - - Search the catalog to create a reservation - - In the staff client, select Search Search the Catalog - - Search for the item to be booked. - Click Submit Search. - A list of results will appear. Select the title of the item to be reserved. - After clicking the title, the record summary appears. Beneath the record summary, - the copy summary will appear. In the Actions column, select Copy Details. - - The Copy Details will appear in a new row. In the barcode column, click the book now - link. - A screen showing the title and barcodes of available copies will appear. - Enter the user’s barcode in the Reserve to patron barcode box. If the patron barcode - does not exist, a pop up box will appear to alert you to the error. After entering the - patron’s barcode, the user’s existing reservations will appear at the bottom of the - screen. - To the right, a section titled, I need this resource... will allow you to set the dates and - times for which the item should be reserved. If the date/time boxes appear in red, - then the date and time set is incorrect. For example, if the time for which the - reservation is set has already passed, the boxes will appear in red. The times must be - set correctly for the reservation to be accomplished. If the item has already been - reserved at the time for which you are trying to reserve the item, then you will receive - an error message. - Finally, select the barcode of the item that you want to reserve. If multiple copies of - the item exist, choose the barcode of the copy that you want to reserve, and click - Reserve Selected. If you do not select a barcode, and you click Reserve Selected, you - will receive an error message. If you do not have a preference, you do not have to - select a barcode, and you may click Reserve Any. One of the barcodes will be pulled - from the list. - An item must have a status of available or reshelving in order to - be targeted for a reservation. If the item is in another status, the reservation will fail. - After you have made the reservation, a message will confirm that the action succeeded. Click OK. - The screen will refresh, and the reservation will appear below the user’s name. - - - - Enter a patron’s record to create a reservation - - Enter the barcode or patron information, and click Search to retrieve the patron’s record. - The match(es) should appear in the right pane. Click the desired patron’s name. In the - left panel, a summary of the patron’s information will appear. Click the Retrieve - Patron button in the right corner to access more options in the patron’s record. - Eight buttons will appear in the top right corner. Select Other Booking - to create, cancel, pick up, and return reservations. - The Copy Details will appear in a new row. In the barcode column, click the book now - link. - A screen showing the title and barcodes of available copies will appear. - Enter the user’s barcode in the Reserve to patron barcode box. If the patron barcode - does not exist, a pop up box will appear to alert you to the error. After entering the - patron’s barcode, the user’s existing reservations will appear at the bottom of the - screen. - To the right, a section titled, I need this resource... will allow you to set the dates and - times for which the item should be reserved. If the date/time boxes appear in red, - then the date and time set is incorrect. For example, if the time for which the - reservation is set has already passed, the boxes will appear in red. The times must be - set correctly for the reservation to be accomplished. If the item has already been - reserved at the time for which you are trying to reserve the item, then you will receive - an error message. - Finally, select the barcode of the item that you want to reserve. If multiple copies of - the item exist, choose the barcode of the copy that you want to reserve, and click - Reserve Selected. If you do not select a barcode, and you click Reserve Selected, you - will receive an error message. If you do not have a preference, you do not have to - select a barcode, and you may click Reserve Any. One of the barcodes will be pulled - from the list. - An item must have a status of available or reshelving in order to - be targeted for a reservation. If the item is in another status, the reservation will fail. - After you have made the reservation, a message will confirm that the action succeeded. Click OK. - The screen will refresh, and the reservation will appear below the user’s name. - - - - Use the booking module to create a reservation - - Select BookingCreate or Edit Reservations - Enter the barcode of the item and click Next. - A screen showing the name of the available resource will appear. - Enter the user’s barcode in the Reserve to patron barcode box. If the patron barcode - does not exist, a pop up box will appear to alert you to the error. After entering the - patron’s barcode, the user’s existing reservations will appear. - To the right, a section titled, I need this resource... will allow you to set the dates and - times for which the item should be reserved. If the date/time boxes appear in red, - then the date and time set is incorrect. For example, if the time for which the - reservation is set has already passed, the boxes will appear in red. The times must be - set correctly for the reservation to be accomplished. If the resource has already been - reserved at the time for which you want to reserve the item, then the item will - disappear. - Finally, select the resource that you want to reserve. If multiple items or rooms exist, - choose the resource that you want to reserve, and click Reserve Selected. If you do - not select a resource, and you click Reserve Selected, you will receive an error - message. If you do not have a preference, you may click Reserve Any, and one of the - resources will be pulled from the list. - After you have made the reservation, a message will confirm that the action - succeeded. Click OK. - The screen will refresh, and the reservation will appear below the user’s name. - - -
-
- Cancelling a Reservation - 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 - reservation immediately after it has been made. - - Enter the patron’s record to cancel a reservation - - Search for and retrieve a patron’s record. - Select OtherBookingCreate or Cancel Reservations. - The existing reservations will appear at the bottom of the screen. - To cancel a reservation, highlight the reservation that you want to cancel. Click Cancel Selected. - A pop-up window will confirm that you cancelled the reservation. Click OK. - The screen will refresh, and the cancelled reservation will disappear. - To the right, a section titled, I need this resource... will allow you to set the dates and - times for which the item should be reserved. If the date/time boxes appear in red, - then the date and time set is incorrect. For example, if the time for which the - reservation is set has already passed, the boxes will appear in red. The times must be - set correctly for the reservation to be accomplished. If the item has already been - reserved at the time for which you are trying to reserve the item, then you will receive - an error message. - - - - Cancel a reservation immediately after it has been made - - Create the reservation. - Follow steps four through six in the section, Enter the patron’s record to cancel a reservation, to cancel the reservation. - The existing reservations will appear at the bottom of the screen. - - -
-
- Creating a Pull List - Staff members can create a pull list to retrieve items from the stacks. - - To create a pull list, select BookingPull List. - To find a pull list for your library, select a library from the dropdown box adjacent to See pull list for library. - 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 Generate - list for this many days hence. For example, if you would like to pull items that are needed today, you can enter 1 in the box, and you will retrieve items that need to be pulled today. - Click Fetch to retrieve the pull list. - The pull list will appear. Click Print to print the pull list. - -
-
- Capturing Items for Reservations - Staff members can capture items for reservations. - - In the staff client, select BookingCapture Resources. - Enter the barcode of the items to be captured. Click Capture. - A Capture Succeeded message will appear to the right. Information about the item will appear below the message. You can print this - information as a receipt and add it to the item if desired. - -
-
- Picking Up Reservations - Staff members can help users pick up their reservations. - - In the staff client, select BookingPick Up Reservations - Enter the user’s barcode. Click Go. - The title available for pickup will appear. Highlight the title of the item to pick up, and click Pick Up. - The screen will refresh to show that the patron has picked up the reservation. - -
-
- Returning Reservations - Staff members can help users return their reservations. - - In the staff client, select BookingReturn Reservations. - You can return the item by patron or item barcode. Choose Resource or Patron, enter the - barcode, and click Go. - A pop up box will tell you that the item was returned. Click OK. - The screen will refresh to show the reservations that remain out and the resources that have been returned. - -
- - diff --git a/1.6/development/customize_opac.xml b/1.6/development/customize_opac.xml index 2498f1255c..40dc8b97cd 100644 --- a/1.6/development/customize_opac.xml +++ b/1.6/development/customize_opac.xml @@ -13,6 +13,7 @@
Change the Color Scheme + OPACcustomizingchanging the color scheme To change the color scheme of the default Evergreen skin, edit /openils/var/web/opac/theme/default/css/colors.css. From this one file you can change the 4 base color scheme as well as colors of specific elements. @@ -44,6 +45,7 @@ name='Default' csstype='color'/>
customizing Opac Text and Labels + OPACcustomizingtext and labels To change text and links used throughout the OPAC, edit the following files: /openils/var/web/opac/locale/[your locale]/lang.dtd @@ -81,6 +83,7 @@ name='Default' csstype='color'/>
Added Content + OPACadded content By default Evergreen includes customizable Added Content features to enhance the OPAC experience for your user. These features include Amazon book covers and Google books searching. These features can be turned off or customized. @@ -105,6 +108,7 @@ name='Default' csstype='color'/> Google Books Link + OPACadded contentGoogle Books The results page will display a Browse in Google Books Search link for items in the results page which have corresponding entries in Google Books. 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 @@ -127,6 +131,7 @@ name='Default' csstype='color'/>
Customizing the Details Page + OPACcustomizingdetails page 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 of Evergreen when displaying the details of items. Some quick features can be turned on and off by changing variable values in the file /openils/var/web/opac/skin/default/js/rdedail.js. diff --git a/1.6/development/customizingstaffclient.xml b/1.6/development/customizingstaffclient.xml index 46e205ee33..dbe1fa4afc 100644 --- a/1.6/development/customizingstaffclient.xml +++ b/1.6/development/customizingstaffclient.xml @@ -2,6 +2,7 @@ Customizing the Staff Client + staff clientcustomizing This chapter will give you some guidance on customizing the staff client. The files related to the staff client are located in the directory /openils/var/web/xul/[staff client version]/server/
@@ -13,6 +14,7 @@
Changing Labels and Messages + staff clientcustomizinglabels and messages You can customize labels in the staff client by editing the corresponding DTD files. The staff client uses the same lang.dtd used by the OPAC. This file is located in /openils/var/web/opac/locale/[your locale]. Other labels are controlled by the staff client specific lang.dtd file in /openils/var/web/xul/client version]/server/locale/[your locale]/.
diff --git a/1.6/development/datamodelsandaccess.xml b/1.6/development/datamodelsandaccess.xml index a887ab3eac..93ec2462a5 100644 --- a/1.6/development/datamodelsandaccess.xml +++ b/1.6/development/datamodelsandaccess.xml @@ -65,6 +65,7 @@
Evergreen Interface Definition Language (IDL) + Evergreen Interface Definition Language (IDL) Defines properties and required permissions for Evergreen classes. To reduce network overhead, a given object is identified via a class-hint and serialized as a JSON array of properties (no named properties). @@ -75,7 +76,8 @@ - … 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 + … 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 @@ -110,6 +112,7 @@ The class element defines the attributes and permissions for classes, and relationships between classes. + Evergreen Interface Definition Language (IDL)class element @@ -163,6 +166,7 @@ Received Data: [ The fields element defines the list of fields for the class. + Evergreen Interface Definition Language (IDL)fields element @@ -182,6 +186,7 @@ Received Data: [ Each field element defines one property of the class. + Evergreen Interface Definition Language (IDL)field element @@ -218,12 +223,14 @@ Received Data: [ + Evergreen Interface Definition Language (IDL)permacrud element The permacrud element defines the permissions (if any) required to create, retrieve, update, and delete data for this class. open-ils.permacrud must be defined as a controller for the class for the permissions to be applied. + @@ -245,6 +252,7 @@ Received Data: [ + Evergreen Interface Definition Language (IDL)action element An action element may contain a <context_field> element that defines the linked class (identified by the link attribute) and @@ -253,6 +261,7 @@ Received Data: [ + Evergreen Interface Definition Language (IDL)context_field element If the <context_field> element contains a jump attribute, then it defines a link to a link to a class with a field identifying @@ -375,6 +384,7 @@ Received Data: [
<literal>open-ils.cstore</literal> data access interfaces + cstore For each class documented in the IDL, the open-ils.cstore service automatically generates a set of data access methods, based on the oils_persist:tablename class attribute. @@ -421,6 +431,7 @@ Received Data: [
open-ils.pcrud data access interfaces + pcrud For each class documented in the IDL, the open-ils.pcrud service automatically generates a set of data access methods, based on the oils_persist:tablename class attribute. @@ -541,6 +552,7 @@ Received Data: [ srfsh# close open-ils.cstore JSON Queries + JSON Beyond simply retrieving objects by their ID using the \*.retrieve methods, you can issue queries against the \*.delete and \*.search methods using JSON to filter results with simple or complex search diff --git a/1.6/development/directoriesandFiles.xml b/1.6/development/directoriesandFiles.xml index aac5d1d3c1..a72246dd9c 100644 --- a/1.6/development/directoriesandFiles.xml +++ b/1.6/development/directoriesandFiles.xml @@ -68,20 +68,24 @@
/openils/conf/opensrf_core.xml + configuration filesopensrf_core.xml 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. /openils/conf/opensrf.xml + configuration filesopensrf.xml Use this file to set directory locations, the default locale, default notice settings and settings for all Evergreen services. It is critical for any administrator to understand the settings in this file. An Evergreen restart is required for changes to take effect. /openils/conf/fm_IDL.xml + configuration filesfm_IDL.xml Used for linking the OpenSRF/Evergreen services to the Evergreen database tables. An Evergreen restart is required for changes to take effect. Running autogen.sh is also required. /etc/apache2/eg_vhost.conf + configuration filesApache Controls the Evergreen virtual site. Allows to configure the skin for the OPAC or configure various directories within the Apache web server. An Apache restart is required for changes to this file to take effect. @@ -102,15 +106,18 @@ /openils/bin/autogen.sh + autogen 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 Evergreen database entries. /openils/bin/clark-kent.pl + reportsstarting Perl script for starting the reporter. /openils/bin/action_trigger_runner.pl + action triggersrunner Perl script used to trigger the actions set up in the action trigger tool in the staff client. @@ -123,6 +130,7 @@ /openils/bin/srfsh + srfsh Used to start the OpenSRF shell. diff --git a/1.6/development/introduction_to_sql.xml b/1.6/development/introduction_to_sql.xml index 00540384da..ac45698e9d 100644 --- a/1.6/development/introduction_to_sql.xml +++ b/1.6/development/introduction_to_sql.xml @@ -9,6 +9,7 @@
Introduction to SQL Databases + sql Introduction Over time, the SQL database has become the standard method of storing, @@ -28,6 +29,7 @@ Tables + sqltables The table is the cornerstone of a SQL database. Conceptually, a database table is similar to a single sheet in a spreadsheet: every table has one or more columns, with each row in the table containing values for each column. Each diff --git a/1.6/development/json.xml b/1.6/development/json.xml index b445fd97a6..3036c1e92f 100644 --- a/1.6/development/json.xml +++ b/1.6/development/json.xml @@ -3,6 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> JSON Queries + JSON 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 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 @@ -75,6 +76,7 @@ FROM Default SELECT Clauses + JSONSELECT clauses 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 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 SELECT clause. diff --git a/1.6/development/supercat.xml b/1.6/development/supercat.xml index c8d08dc925..28d0d9ff97 100644 --- a/1.6/development/supercat.xml +++ b/1.6/development/supercat.xml @@ -6,6 +6,7 @@
> Using SuperCat + SuperCat 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 supported: @@ -15,6 +16,7 @@ Return a list of ISBNs for related records + SuperCatISBNs Similar to the OCLC xISBN service, Evergreen can return a list of related records based on its oISBN algorithm: http://<hostname>/opac/extras/osibn/<ISBN> For example, http://dev.gapines.org/opac/extras/oisbn/0439136350 returns: @@ -37,6 +39,7 @@ Return records + SuperCatrecords SuperCat can return records and metarecords in many different formats (see http://<hostname>/opac/extras/supercat/retrieve/<format>/<record-type>/<bib-ID> For example, http://dev.gapines.org/opac/extras/supercat/retrieve/mods/record/555 returns: @@ -82,6 +85,7 @@ Return a feed of recently edited or created records + SuperCatrecent records SuperCat can return feeds of recently edited or created authority and bibliographic records: http://<hostname>/opac/extras/feed/freshmeat/<feed-type>/[authority|biblio]/[import|edit]/<limit>/<date> 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. @@ -119,6 +123,7 @@ Supported formats + SuperCatformats SuperCat maintains a list of supported formats for records and metarecords: http://<hostname>/opac/extras/supercat/formats/<record-type> For example, http://dev.gapines.org/opac/extras/supercat/formats/record returns: @@ -265,6 +270,7 @@
Adding new SuperCat Formats + SuperCatformatsadding Adding SuperCat formats requires experience editing XSL files and familiarity with XML and Perl. SuperCat web services are based on the OpenSRF service, >open-ils.supercat. Developers are able to add new formats by adding the xsl stylesheet for the format. By default, the location of the stylesheets is /openils/var/xsl/. You must also add the feed to the perl @@ -273,7 +279,8 @@ Use an existing xsl stylesheet and Perl module entry as a template for your new format.
- Customizing SuperCat Formats + Customizing SuperCat Formats + SuperCatformatscustomizing Editing SuperCat formats requires experience editing XSL files and familiarity with XML.. 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. 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 diff --git a/1.6/development/workshop.xml b/1.6/development/workshop.xml deleted file mode 100644 index 0b11121382..0000000000 --- a/1.6/development/workshop.xml +++ /dev/null @@ -1,1532 +0,0 @@ - - - - - Evergreen development - February 2010 - - Dan - Scott - dscott@laurentian.ca - - DS -1.0February 2010DS - -
-Part 1: OpenSRF applications -OpenSRF, pronounced "Open Surf", is the Open Service Request -Framework. It was designed as an architecture on which one could -easily build scalable applications. -
-Introduction to OpenSRF -The framework is built on JSON-over-XMPP. XML can be used, but JSON -is much less verbose. XMPP is a standard messaging protocol that -has been used as the backbone of low-latency, high-volume -applications including instant messaging and Google Wave. -OpenSRF offers scalability via its clustering architecture; a service -that is a bottleneck can be moved onto its own server; or multiple -instances of the service can be run on many servers. Services can -themselves be clients of other services. -OpenSRF services listen at an XMPP address such as -"opensrf@private.localhost/open-ils.fielder_drone_at_localhost_7652". -The initial request from an OpenSRF client is directed to the -OpenSRF router, which determines whether the requested service is -accessible to the client (based on the public versus private domains), -and then connects the client to the service for any subsequent -communication that is required. -To significantly improve the speed at which request services can -respond to common requests, OpenSRF has integrated support for the -caching via the memcached daemon. For example, the contents of the -configuration files are cached by the opensrf.settings service when -that service starts, so that rather than having to parse the XML file -every time a service checks a configuration setting, the value can be -retrieved with much less overhead directly from the cache. -if you change a setting in one of those configuration files, you -must restart the opensrf.settings service to update its data. You must -then restart any of the services that make use of that setting to make -the change take effect. -Supports Perl, C, and Python as services and clients, and Java as a -client. JavaScript can access services via HTTP translator and -gateway. JSON library converts messages to/from native structures for -ease of development. -
-
-Configuring OpenSRF -Walk through the configuration files, explaining why we put the values -into the files that we do: - - - -opensrf_core.xml - - - - -Distinguish between public and private services for security of Web-based applications. - - - - -Deprecated HTTP gateway versus OpenSRF-over-HTTP - - - - - - -opensrf.xml - - - -In a clustered OpenSRF instance, these files are normally hosted on -a network share so that each member of the cluster can read them. -
-
-Starting OpenSRF services -I won’t go through this during a live session. Perhaps I can cut this -out entirely… -Issue the following commands as the opensrf user. If you are running OpenSRF -on a single-server machine, you can use the -l flag to force the hostname -to be treated as localhost. - - - -Start the OpenSRF router: - -osrf_ctl.sh -a start_router -The router must only run on a single machine in a given brick. - - - -Start all OpenSRF Perl services defined for this host: - -osrf_ctl.sh -a start_perl -You can start an individual Perl service using: -opensrf-perl.pl -s <service-name> -a start -p <PID-directory> - - - -Start all OpenSRF C services defined for this host: - -osrf_ctl.sh -a start_c - - -
-
-Stopping OpenSRF services -Issue the following commands as the opensrf user. If you are running OpenSRF -on a single-server machine, you can use the -l flag to force the hostname -to be treated as localhost. - - - -Stop the OpenSRF router: - -osrf_ctl.sh -a stop_router - - - -Stop all OpenSRF Perl services defined for this host: - -osrf_ctl.sh -a stop_perl -You can stop an individual Perl service using: -opensrf-perl.pl -s <service-name> -a stop -p <PID-directory> - - - -Stop all OpenSRF C services defined for this host: - -osrf_ctl.sh -a stop_c - - -PID files for OpenSRF services are stored and looked up -in /openils/var/run by default with osrf_ctl.sh, and in -/tmp/ with opensrf-perl.pl. For a clustered server instance -of Evergreen, you must store the PIDs on a directory that is local -to each server, or else one of your cluster servers may try -killing processes on itself that actually have PIDs on other servers. -
-
-
-Examining sample code -Show internal documentation for methods. Do some stupid srfsh tricks -(introspect for one) and show docgen.xsl in action. -
-SRFSH stupid tricks -srfsh# introspect open-ils.auth -... returns documentation for all methods registered for open-ils.auth - -srfsh# introspect open-ils.auth "open-ils.auth.authenticate" -... returns documentation for all methods with names beginning with - "open-ils.auth.authenticate" registered for open-ils.auth - -srfsh# open open-ils.cstore -... begins a stateful connection with open-ils.cstore -srfsh# request open-ils.cstore open-ils.cstore.transaction.begin -... begins a transaction -srfsh# request open-ils.cstore open-ils.cstore.direct.config.language_map.delete \ - {"code": {"like":"a%"}} -... deletes all of the entries from config.language_map that have a -... code beginning with "e" -srfsh# request open-ils.cstore open-ils.cstore.transaction.rollback -... rolls back the transaction -srfsh# close open-ils.cstore -... closes the stateful connection with open-ils.cstore -
-
-Perl -
-Services -See OpenSRF/src/perl/lib/OpenSRF/UnixServer.pm to understand how the -optional methods for initializing and cleaning up OpenSRF services -are invoked: - - - -initialize() - - - - -child_init() - - - - -child_exit() - - - -Services are implemented as Perl functions. Each service needs to be registered with: -__PACKAGE__->register_method( - method => 'method name', # - api_name => 'API name', # - api_level => 1, # - argc => # of args, # - signature => { # - desc => “Description”, - params => [ - { - name => 'parameter name', - desc => 'parameter description', - type => '(array|hash|number|string)' - } - ], - return => { - desc => 'Description of return value', - type => '(array|hash|number|string)' - } - } -); - - - -The method name is the name of the Perl method that is called when a -client invokes the corresponding OpenSRF method. - - - - -The API name is the OpenSRF method name. By convention, each API -uses the OpenSRF service name for its root, and then appends one or more -levels of names to the OpenSRF service name, depending on the complexity -of the service and the number of methods exposed by a given service. - - - - -The API level is always 1. - - - - -The number of arguments that can be passed to the OpenSRF method is -primarily for guidance purposes. - - - - -The signature is consumed by the various utilities (srfsh, docgen.xsl) -that generate documentation about the OpenSRF service. - - - -Note that arguments are converted between native data structures and JSON -for us for free. -
-
-Client cheat sheet -This is the simplest possible OpenSRF client written in Perl: - - - - -The OpenSRF::System module gives our program access to the core OpenSRF -client functionality. - - - - -The bootstrap_client() method reads the opensrf_core.xml file and sets -up communication with the OpenSRF router. - - - - -The OpenSRF::Appsession->create() instance method asks the router if it -can connect to the named service. If the router determines that the service -is accessible (either the opensrf credentials are on the private domain, which -gives it access to all public and private services; or the service is on a -public domain, which is accessible to both public and private opensrf -credentials), it returns an OpenSRF session with a connection to the named service. - - - - -The OpenSRF::Appsession->request() method invokes a method of the -associated service to return a request object. - - - - -The method name that you want to invoke is the first argument to request(). - - - - -The arguments to the method follow the method name. - - - - -Invoking the gather() method on the returned request object returns a -single result. - -If the service is expected to return multiple results, you should loop -over it with recv() instead. But then, that wouldn’t be the simplest -possible client anymore would it? - - - -The OpenSRF::Appsession->disconnect() instance method disconnects from -the service, enabling that child to go on and handle other requests. - - - -
-
-
-JavaScript -Historically, JavaScript has had access to OpenSRF methods via the -OpenSRF HTTP gateway Apache module. You can still see this in heavy use -in the OPAC and staff client as of Evergreen 1.6, but the approach has been -deprecated as it has significant performance problems with large responses. -The successor for the OpenSRF gateway is the OpenSRF-over-HTTP translator -Apache module, which supports streaming responses for improved performance -and better support for the broad range of OpenSRF attributes. -
-Invoking methods via the HTTP Translator -The following example demonstrates the basic approach to invoking -OpenSRF methods via JavaScript. It uses just three OpenSRF JavaScript -libraries to simplify calls to the OpenSRF-over-HTTP translator, -which became available to developers as part of the OpenSRF 1.0 / -Evergreen 1.4 releases. - - - - -opensrf.js defines most of the objects and methods required for a bare -JavaScript call to the OpenSRF HTTP translator. - - - - -opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF. - - - - -JSON_v1.js converts the requests and responses between JavaScript and the -JSON format that the OpenSRF translator expects. - - - - -Create a client session that connects to the open-ils.resolver service. - - - - -Create a request object that identifies the target method and passes the -required method arguments. - - - - -Define the function that will be called when the request is sent and -results are returned from the OpenSRF HTTP translator. - - - - -Loop over the returned results using the recv() method. - - - - -The content of each result is accessible via the content() method of -each returned result. - - - - -open-ils.resolver.resolve_holdings returns a hash of values, so -invoking one of the hash keys (coverage) gives us access to that value. - - - - -Actually send the request to the method; the function defined by -req.oncomplete is invoked as the results are returned. - - - -
-
-
-
-Exercise -Build a new OpenSRF service. -
-Perl -The challenge: implement a service that caches responses from some -other Web service (potentially cutting down on client-side latency -for something like OpenLibrary / Google Books / xISBN services, and -avoiding timeouts if the target service is not dependable). Our -example will be to build an SFX lookup service. This has the -additional advantage of enabling XmlHttpRequest from JavaScript by -hosting the services on the same domain. -Let’s start with the simplest possible implementation – a CGI script. - -Hopefully you can follow what this CGI script is doing. It works, -but it has all the disadvantages of CGI: the environment needs to -be built up on every request, and it doesn’t remember anything -from the previous times it was called, etc. -
-Turning the CGI script into an OpenSRF service -So now we want to turn this into an OpenSRF service. - - - -Start by ripping out the CGI stuff, as we won’t need that any more. - - - - -To turn this into an OpenSRF service, we create a new -Perl module (OpenILS::Application::ResolverResolver). We no -longer have to convert results between Perl and JSON values, as -OpenSRF will handle that for us. We now have to register the -method with OpenSRF. - - - - - -Copy the file into the /openils/lib/perl5/OpenILS/Application/ directory -so that OpenSRF can find it in the @INC search path. - - - - -Add the service to opensrf.xml so it gets started with the -other Perl services on our host of choice: - -... -<open-ils.resolver> - <keepalive>3</keepalive> - <stateless>1</stateless> - <language>perl</language> - <implementation>OpenILS::Application::ResolverResolver</implementation> - <max_requests>17</max_requests> - <unix_config> - <unix_sock>open-ils.resolver_unix.sock</unix_sock> - <unix_pid>open-ils.resolver_unix.pid</unix_pid> - <max_requests>1000</max_requests> - <unix_log>open-ils.resolver_unix.log</unix_log> - <min_children>5</min_children> - <max_children>15</max_children> - <min_spare_children>3</min_spare_children> - <max_spare_children>5</max_spare_children> - </unix_config> - <app_settings> - <cache_timeout>86400</cache_timeout> - <default_url_base>http://sfx.scholarsportal.info/laurentian</default_url_base> - </app_settings> -</open-ils.resolver> -... -<!-- In the <hosts> section --> -<localhost> - ... - <appname>open-ils.resolver</appname> -</localhost> - - - -Add the service to opensrf_core.xml as a publicly exposed -service via the HTTP gateway and translator: - -... -<!-- In the public router section --> -<services> - ... - <service>open-ils.resolver</service> -</services> -... -<!-- In the public gateway section --> -<services> -<gateway> - ... - <services> - <service>open-ils.resolver</service> - </services> -</gateway> - - - -Restart the OpenSRF Perl services to refresh the OpenSRF -settings and start the service.. - - - - -Restart Apache to enable the gateway and translator to pick up -the new service. - - - -
-
-Add caching -To really make this service useful, we can take advantage of OpenSRF’s -built-in support for caching via memcached. Keeping the values -returned by the resolver for 1 week is apparently good. -We will also take advantage of the opensrf.settings service that -holds the values defined in the opensrf.xml configuration file to -supply some of our default arguments. -Caching OpenSRF Resolver Service - - -
-
-Pulling application settings from <literal>opensrf.xml</literal> -In case you missed it in the previous diff, we also started -pulling some application-specific settings from opensrf.xml -during the initialize() phase for the service. -In the following diff, we enable the service to pull the default URL from -opensrf.xml rather than hard-coding it into the OpenSRF service… because -that’s just the right thing to do. -=== modified file 'ResolverResolver.pm' ---- ResolverResolver.pm 2009-10-22 21:00:15 +0000 -+++ ResolverResolver.pm 2009-10-24 03:00:30 +0000 -@@ -77,6 +77,7 @@ - my $prefix = "open-ils.resolver_"; # Prefix for caching values - my $cache; - my $cache_timeout; -+my $default_url_base; # Default resolver location - - our ($ua, $parser); - -@@ -86,6 +87,8 @@ - my $sclient = OpenSRF::Utils::SettingsClient->new(); - $cache_timeout = $sclient->config_value( - "apps", "open-ils.resolver", "app_settings", "cache_timeout" ) || 300; -+ $default_url_base = $sclient->config_value( -+ "apps", "open-ils.resolver", "app_settings", "default_url_base"); - } - - sub child_init { -@@ -102,14 +105,11 @@ - my $conn = shift; - my $id_type = shift; # keep it simple for now, either 'issn' or 'isbn' - my $id_value = shift; # the normalized ISSN or ISBN -+ my $url_base = shift || $default_url_base; - - # We'll use this in our cache key - my $method = "open-ils.resolver.resolve_holdings"; - -- # For now we'll pass the argument with a hard-coded default -- # Should pull these specifics from the database as part of initialize() -- my $url_base = shift || 'http://sfx.scholarsportal.info/laurentian'; -- - # Big ugly SFX OpenURL request - my $url_args = '?url_ver=Z39.88-2004&url_ctx_fmt=infofi/fmt:kev:mtx:ctx&' - . 'ctx_enc=UTF-8&ctx_ver=Z39.88-2004&rfr_id=info:sid/conifer&' -The opensrf.settings service caches the settings defined in opensrf.xml, -so if you change a setting in the configuration files and want that change -to take effect immediately, you have to: - - - -Restart the opensrf.settings service to refresh the cached settings. - - - - -Restart the affected service to make the new settings take effect. - - - -Next step: add org_unit settings for resolver type and URL on a per-org_unit basis. -OrgUnit settings can be retrieved via -OpenILS::Application::AppUtils->ou_ancestor_setting_value($org_id, $setting_name)). -This is where we step beyond OpenSRF and start getting into the -Evergreen database schema (config.org_unit_setting table). -
-
-
-Further reading -OpenSRF terminology: http://open-ils.org/dokuwiki/doku.php?id=osrf-devel:terms -
-
-
-Part 2: Evergreen applications -
-Authentication -Although many services offer methods that can be invoked without -authentication, some methods require authentication in Evergreen. -Evergreen’s authentication framework returns an authentication token -when a user has successfully logged in to represent that user -session. You can then pass the authentication token to various -methods to ensure, for example, that the requesting user has permission -to access the circulation information attached to a particular account, -or has been granted the necessary permissions at a particular library -to perform the action that they are requesting. -Authentication in Evergreen is performed with the assistance of the -open-ils.auth service, which has been written in C for performance -reasons because it is invoked so frequently. A successful authentication -request requires two steps: - - - -Retrieve an authentication seed value by invoking the -open-ils.auth.authenticate.init method, passing the user name as -the only argument. As long as the user name contains no spaces, the -method returns a seed value calculated by the MD5 checksum of -a string composed of the concatenation of the time() system call, -process ID, and user name. - - - - -Retrieve an authentication token by invoking the -open-ils.auth.authenticate.complete method, passing -a JSON hash composed of a minimum of the following arguments -(where seed represents the value returned by the -open-ils.auth.authenticate.init method): - -{ - "username": username, // or "barcode": barcode, - "password": md5sum(seed + md5sum(password)), -} - - -open-ils.auth.authenticate.complete also accepts the following -additional arguments: - - - -type: one of "staff" (default), "opac", or "temp" - - - - -org: the numeric ID of the org_unit where the login is active - - - - -workstation: the registered workstation name - - - -
-Authentication in Perl -The following example is taken directly from OpenILS::WWW::Proxy: -sub oils_login { - my( $username, $password, $type ) = @_; - - $type |= "staff"; - my $nametype = 'username'; - $nametype = 'barcode' if ($username =~ /^\d+$/o); - - my $seed = OpenSRF::AppSession - ->create("open-ils.auth") - ->request( 'open-ils.auth.authenticate.init', $username ) - ->gather(1); - - return undef unless $seed; - - my $response = OpenSRF::AppSession - ->create("open-ils.auth") - ->request( 'open-ils.auth.authenticate.complete', { - $nametype => $username, - password => md5_hex($seed . md5_hex($password)), - type => $type - }) - ->gather(1); - - return undef unless $response; - - return $response->{payload}->{authtoken}; -} -
-
-Authentication in JavaScript -The following example provides a minimal implementation of the authentication -method in JavaScript. For a more complete implementation, you would -differentiate between user names and barcodes, potentially accept the -org_unit and workstation name for more granular permissions, and provide -exception handling. - - - - -opensrf.js defines most of the objects and methods required for a bare -JavaScript call to the OpenSRF HTTP translator. - - - - -opensrf_xhr.js provides cross-browser XMLHttpRequest support for OpenSRF. - - - - -JSON_v1.js converts the requests and responses between JavaScript and the -JSON format that the OpenSRF translator expects. - - - - -md5.js provides the implementation of the md5sum algorithm in the -hex_md5 function - - - - -Create a client session that connects to the open-ils.auth service. - - - - -Create a request object that invokes the open-ils.auth.authenticate.init -method, providing the user name as the salt. - - - - -Set the timeout property on the request object to make it a -synchronous call. - - - - -Send the request. The method returns a seed value which is assigned to -the seed variable. - - - - -Create the hash of parameters that will be sent in the request to the -open-ils.auth.authenticate.complete method, including the password and -authentication type. - - - - -Assume that the credentials being sent are based on the user name rather -than the barcode. The Perl implementation tests the value of the user name -variable to determine whether it contains a digit; if it does contain a -digit, then it is considered a barcode rather than a user name. Ensure that -your implementations are consistent! - - - - -Create a request object that invokes the -open-ils.auth.authenticate.complete method, passing the entire hash of -parameters. Once again, set the timeout parameter to make the request -synchronous. - - - - -Assign the authtoken attribute of the returned payload to the -authtoken variable. - - - -
-
-
-
-Evergreen data models and access -
-Database schema -The database schema is tied pretty tightly to PostgreSQL. Although PostgreSQL -adheres closely to ANSI SQL standards, the use of schemas, SQL functions -implemented in both plpgsql and plperl, and PostgreSQL’s native full-text -search would make it… challenging… to port to other database platforms. -A few common PostgreSQL interfaces for poking around the schema and -manipulating data are: - - - -psql (the command line client) - - - - -pgadminIII (a GUI client). - - - -Or you can read through the source files in Open-ILS/src/sql/Pg. -Let’s take a quick tour through the schemas, pointing out some highlights -and some key interdependencies: - - - -actor.org_unit → asset.copy_location - - - - -actor.usr → actor.card - - - - -biblio.record_entry → asset.call_number → asset.copy - - - - -config.metabib_field → metabib.*_field_entry - - - -
-
-Database access methods -You could use direct access to the database via Perl DBI, JDBC, etc, -but Evergreen offers several database CRUD services for -creating / retrieving / updating / deleting data. These avoid tying -you too tightly to the current database schema and they funnel database -access through the same mechanism, rather than tying up connections -with other interfaces. -
-
-Evergreen Interface Definition Language (IDL) -Defines properties and required permissions for Evergreen classes. -To reduce network overhead, a given object is identified via a -class-hint and serialized as a JSON array of properties (no named properties). -As of 1.6, fields will be serialized in the order in which they appear -in the IDL definition file, and the is_new / is_changed / is_deleted -properties are automatically added. This has greatly reduced the size of -the fm_IDL.xml file and makes DRY people happier :) - - - -… 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 - - - -
-IDL basic example (config.language_map) -<class id="clm" controller="open-ils.cstore open-ils.pcrud" - oils_obj:fieldmapper="config::language_map" - oils_persist:tablename="config.language_map" - reporter:label="Language Map" oils_persist:field_safe="true"> # - <fields oils_persist:primary="code" oils_persist:sequence=""> # - <field reporter:label="Language Code" name="code" - reporter:selector="value" reporter:datatype="text"/> # - <field reporter:label="Language" name="value" - reporter:datatype="text" oils_persist:i18n="true"/> # - </fields> - <links/> - <permacrud xmlns="http://open-ils.org/spec/opensrf/IDL/permacrud/v1"> # - <actions> - <create global_required="true" permission="CREATE_MARC_CODE"> # - <retrieve global_required="true" - permission="CREATE_MARC_CODE UPDATE_MARC_CODE DELETE_MARC_CODE"> - <update global_required="true" permission="UPDATE_MARC_CODE"> - <delete global_required="true" permission="DELETE_MARC_CODE"> - </actions> - </permacrud> -</class> - - - -The class element defines the attributes and permissions for classes, -and relationships between classes. - - - - -The id attribute on the class element defines the class hint that is -used everywhere in Evergreen. - - - - -The controller attribute defines the OpenSRF -services that provide access to the data for the class objects. - - - - - - -The oils_obj::fieldmapper attribute defines the name of the class that -is generated by OpenILS::Utils::Fieldmapper. - - - - -The oils_persist:tablename attribute defines the name of the table -that contains the data for the class objects. - - - - -The reporter interface uses reporter:label attribute values in -the source list to provide meaningful class and attribute names. The -open-ils.fielder service generates a set of methods that provide direct -access to the classes for which oils_persist:field_safe is true. For -example, - -srfsh# request open-ils.fielder open-ils.fielder.clm.atomic \ - {"query":{"code":{"=":"eng"}}} - -Received Data: [ - { - "value":"English", - "code":"eng" - } -] - - - -The fields element defines the list of fields for the class. - - - - -The oils_persist:primary attribute defines the column that acts as -the primary key for the table. - - - - -The oils_persist:sequence attribute holds the name of the database -sequence. - - - - - - -Each field element defines one property of the class. - - - - -The name attribute defines the getter/setter method name for the field. - - - - -The reporter:label attribute defines the attribute name as used in -the reporter interface. - - - - -The reporter:selector attribute defines the field used in the reporter -filter interface to provide a selectable list. This gives the user a more -meaningful access point than the raw numeric ID or abstract code. - - - - -The reporter:datatype attribute defines the type of data held by -this property for the purposes of the reporter. - - - - - - -The oils_persist:i18n attribute, when true, means that -translated values for the field’s contents may be accessible in -different locales. - - - - -The permacrud element defines the permissions (if any) required -to create, retrieve, update, and delete data for this -class. open-ils.permacrud must be defined as a controller for the class -for the permissions to be applied. - - - - -Each action requires one or more permission values that the -user must possess to perform the action. - - - - -If the global_required attribute is true, then the user must -have been granted that permission globally (depth = 0) to perform -the action. - - - - -The context_field attribute denotes the <field> that identifies -the org_unit at which the user must have the pertinent permission. - - - - -An action element may contain a <context_field> element that -defines the linked class (identified by the link attribute) and -the field in the linked class that identifies the org_unit where -the permission must be held. - - - - -If the <context_field> element contains a jump attribute, -then it defines a link to a link to a class with a field identifying -the org_unit where the permission must be held. - - - - - - - -
-
-Reporter data types and their possible values - - - -bool: Boolean true or false - - - - -id: ID of the row in the database - - - - -int: integer value - - - - -interval: PostgreSQL time interval - - - - - -link: link to another class, as defined in the <links> -element of the class definition - - - - -money: currency amount - - - - -org_unit: list of org_units - - - - -text: text value - - - - -timestamp: PostgreSQL timestamp - - - -
-
-IDL example with linked fields (actor.workstation) -Just as tables often include columns with foreign keys that point -to values stored in the column of a different table, IDL classes -can contain fields that link to fields in other classes. The <links> -element defines which fields link to fields in other classes, and -the nature of the relationship: -<class id="aws" controller="open-ils.cstore" - oils_obj:fieldmapper="actor::workstation" - oils_persist:tablename="actor.workstation" - reporter:label="Workstation"> - <fields oils_persist:primary="id" - oils_persist:sequence="actor.workstation_id_seq"> - <field reporter:label="Workstation ID" name="id" - reporter:datatype="id"/> - <field reporter:label="Workstation Name" name="name" - reporter:datatype="text"/> - <field reporter:label="Owning Library" name="owning_lib" - reporter:datatype="org_unit"/> - <field reporter:label="Circulations" name="circulations" - oils_persist:virtual="true" reporter:datatype="link"/> # - </fields> - <links> # - <link field="owning_lib" reltype="has_a" key="id" - map="" class="aou"/> # - <link field="circulations" reltype="has_many" key="workstation" - map="" class="circ"/> - <link field="circulation_checkins" reltype="has_many" - key="checkin_workstation" map="" class="circ"/> - </links> -</class> - - - -This field includes an oils_persist:virtual attribute with the value of -true, meaning that the linked class circ is a virtual class. - - - - -The <links> element contains 0 or more <link> elements. - - - - -Each <link> element defines the field (field) that links to a different -class (class), the relationship (rel_type) between this field and the target -field (key). If the field in this class links to a virtual class, the (map) -attribute defines the field in the target class that returns a list of matching -objects for each object in this class. - - - -
-
-
-<literal>open-ils.cstore</literal> data access interfaces -For each class documented in the IDL, the open-ils.cstore service -automatically generates a set of data access methods, based on the -oils_persist:tablename class attribute. -For example, for the class hint clm, cstore generates the following -methods with the config.language_map qualifer: - - - -open-ils.cstore.direct.config.language_map.id_list {"code" { "like": "e%" } } - -Retrieves a list composed only of the IDs that match the query. - - - -open-ils.cstore.direct.config.language_map.retrieve "eng" - -Retrieves the object that matches a specific ID. - - - -open-ils.cstore.direct.config.language_map.search {"code" : "eng"} - -Retrieves a list of objects that match the query. - - - -open-ils.cstore.direct.config.language_map.create <_object_> - -Creates a new object from the passed in object. - - - -open-ils.cstore.direct.config.language_map.update <_object_> - -Updates the object that has been passed in. - - - -open-ils.cstore.direct.config.language_map.delete "eng" - -Deletes the object that matches the query. - - -
-
-open-ils.pcrud data access interfaces -For each class documented in the IDL, the open-ils.pcrud service -automatically generates a set of data access methods, based on the -oils_persist:tablename class attribute. -For example, for the class hint clm, open-ils.pcrud generates the following -methods that parallel the open-ils.cstore interface: - - - -open-ils.pcrud.id_list.clm <_authtoken_>, { "code": { "like": "e%" } } - - - - -open-ils.pcrud.retrieve.clm <_authtoken_>, "eng" - - - - -open-ils.pcrud.search.clm <_authtoken_>, { "code": "eng" } - - - - -open-ils.pcrud.create.clm <_authtoken_>, <_object_> - - - - -open-ils.pcrud.update.clm <_authtoken_>, <_object_> - - - - -open-ils.pcrud.delete.clm <_authtoken_>, "eng" - - - -
-
-Transaction and savepoint control -Both open-ils.cstore and open-ils.pcrud enable you to control database transactions -to ensure that a set of operations either all succeed, or all fail, -atomically: - - - -open-ils.cstore.transaction.begin - - - - -open-ils.cstore.transaction.commit - - - - -open-ils.cstore.transaction.rollback - - - - -open-ils.pcrud.transaction.begin - - - - -open-ils.pcrud.transaction.commit - - - - -open-ils.pcrud.transaction.rollback - - - -At a more granular level, open-ils.cstore and open-ils.pcrud enable you to set database -savepoints to ensure that a set of operations either all succeed, or all -fail, atomically, within a given transaction: - - - -open-ils.cstore.savepoint.begin - - - - -open-ils.cstore.savepoint.commit - - - - -open-ils.cstore.savepoint.rollback - - - - -open-ils.pcrud.savepoint.begin - - - - -open-ils.pcrud.savepoint.commit - - - - -open-ils.pcrud.savepoint.rollback - - - -Transactions and savepoints must be performed within a stateful -connection to the open-ils.cstore and open-ils.pcrud services. -In srfsh, you can open a stateful connection using the open -command, and then close the stateful connection using the close -command - for example: -srfsh# open open-ils.cstore -... perform various transaction-related work -srfsh# close open-ils.cstore -
-JSON Queries -Beyond simply retrieving objects by their ID using the \*.retrieve -methods, you can issue queries against the \*.delete and \*.search -methods using JSON to filter results with simple or complex search -conditions. -For example, to generate a list of barcodes that are held in a -copy location that allows holds and is visible in the OPAC: -srfsh# request open-ils.cstore open-ils.cstore.json_query #\ - {"select": {"acp":["barcode"], "acpl":["name"]}, #\ - "from": {"acp":"acpl"}, #\ - "where": [ #\ - {"+acpl": "holdable"}, #\ - {"+acpl": "opac_visible"} #\ - ]} - -Received Data: { - "barcode":"BARCODE1", - "name":"Stacks" -} - -Received Data: { - "barcode":"BARCODE2", - "name":"Stacks" -} - - - -Invoke the json_query service. - - - - -Select the barcode field from the acp class and the name -field from the acpl class. - - - - -Join the acp class to the acpl class based on the linked field -defined in the IDL. - - - - -Add a where clause to filter the results. We have more than one -condition beginning with the same key, so we wrap the conditions inside -an array. - - - - -The first condition tests whether the boolean value of the holdable -field on the acpl class is true. - - - - -The second condition tests whether the boolean value of the -opac_visible field on the acpl class is true. - - - -For thorough coverage of the breadth of support offered by JSON -query syntax, see JSON Queries: A Tutorial. -
-
-Fleshing linked objects -A simplistic approach to retrieving a set of objects that are linked to -an object that you are retrieving - for example, a set of call numbers -linked to the barcodes that a given user has borrowed - would be to: - 1. Retrieve the list of circulation objects (circ class) -for a given user (usr class). - 2. For each circulation object, look up the target copy (target_copy -field, linked to the acp class). - 3. For each copy, look up the call number for that copy (call_number -field, linked to the acn class). -However, this would result in potentially hundreds of round-trip -queries from the client to the server. Even with low-latency connections, -the network overhead would be considerable. So, built into the open-ils.cstore and -open-ils.pcrud access methods is the ability to flesh linked fields - -that is, rather than return an identifier to a given linked field, -the method can return the entire object as part of the initial response. -Most of the interfaces that return class instances from the IDL offer the -ability to flesh returned fields. For example, the -open-ils.cstore.direct.\*.retrieve methods allow you to specify a -JSON structure defining the fields you wish to flesh in the returned object. -Fleshing fields in objects returned by <literal>open-ils.cstore</literal> -srfsh# request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \ - { - "flesh": 1, #\ - "flesh_fields": { #\ - "acp": ["location"] - } - } - - - - -The flesh argument is the depth at which objects should be fleshed. -For example, to flesh out a field that links to another object that includes -a field that links to another object, you would specify a depth of 2. - - - - -The flesh_fields argument contains a list of objects with the fields -to flesh for each object. - - - -Let’s flesh things a little deeper. In addition to the copy location, -let’s also flesh the call number attached to the copy, and then flesh -the bibliographic record attached to the call number. -Fleshing fields in fields of objects returned by <literal>open-ils.cstore</literal> -request open-ils.cstore open-ils.cstore.direct.asset.copy.retrieve 1, \ - { - "flesh": 2, - "flesh_fields": { - "acp": ["location", "call_number"], - "acn": ["record"] - } - } - -
-
-
-Adding an IDL entry for ResolverResolver -Most OpenSRF methods in Evergreen define their object interface in the -IDL. Without an entry in the IDL, the prospective caller of a given -method is forced to either call the method and inspect the returned -contents, or read the source to work out the structure of the JSON -payload. At this stage of the tutorial, we have not defined an entry -in the IDL to represent the object returned by the -open-ils.resolver.resolve_holdings method. It is time to complete -that task. -The open-ils.resolver service is unlike many of the other classes -defined in the IDL because its data is not stored in the Evergreen -database. Instead, the data is requested from an external Web service -and only temporarily cached in memcached. Fortunately, the IDL -enables us to represent this kind of class by setting the -oils_persist:virtual class attribute to true. -So, let’s add an entry to the IDL for the open-ils.resolver.resolve_holdings -service: - -And let’s make ResolverResolver.pm return an array composed of our new -rhr classes rather than raw JSON objects: - -Once we add the new entry to the IDL and copy the revised ResolverResolver.pm -Perl module to /openils/lib/perl5/OpenILS/Application/, we need to: - - - -Copy the updated IDL to both the /openils/conf/ and -/openils/var/web/reports/ directories. The Dojo approach to -parsing the IDL uses the IDL stored in the reports directory. - - - - -Restart the Perl services to make the new IDL visible to the services -and refresh the open-ils.resolver implementation - - - - -Rerun /openils/bin/autogen.sh to regenerate the JavaScript versions -of the IDL required by the HTTP translator and gateway. - - - -We also need to adjust our JavaScript client to use the nifty new -objects that open-ils.resolver.resolve_holdings now returns. -The best approach is to use the support in Evergreen’s Dojo extensions -to generate the JavaScript classes directly from the IDL XML file. -Accessing classes defined in the IDL via Fieldmapper - - - - - -Load the Dojo core. - - - - -fieldmapper.AutoIDL reads /openils/var/reports/fm_IDL.xml to -generate a list of class properties. - - - - -fieldmapper.dojoData seems to provide a store for Evergreen data -accessed via Dojo. - - - - -fieldmapper.Fieldmapper converts the list of class properties into -actual classes. - - - - -fieldmapper.standardRequest invokes an OpenSRF method and returns -an array of objects. - - - - -The first argument to fieldmapper.standardRequest is an array -containing the OpenSRF service name and method name. - - - - -The second argument to fieldmapper.standardRequest is an array -containing the arguments to pass to the OpenSRF method. - - - - -As Fieldmapper has instantiated the returned objects based on their -class hints, we can invoke getter/setter methods on the objects. - - - -
-
-
-License -This work is licensed under a Creative Commons Attribution-Share Alike 2.5 Canada License. -
- -- 2.43.2