======Evergreen workshop======

At code4lib 2008 we will be giving a pre-conference session on Evergreen. This is what we're planning on doing; hopefully it will be useful material for future workshops.

=====Base line=====

To avoid any heartache associated with conflicting packages, etc., we have asked participants to bring a laptop with a bootable image or VMWare image (running Debian Etch 4.0 or Ubuntu Gutsy 7.10) dedicated to Evergreen.

To avoid relying on the network for downloading packages, we have also asked participants to install the prerequisites ahead of time using the [[http://open-ils.org/dokuwiki/doku.php?id=server_installation:debian_gentoo_ubuntu_prerequisites_makefile|Makefile.install prereq installer]].

We'll bring CDs with copies of the OpenSRF and Evergreen tarballs in case the network gods are angry.

As we go through each of the following phases, we provide commentary that explains a little bit more about what's going on, how a given piece fits into the overall system, and what's happening in trunk to make things easier / better / faster / stronger.

We've made a copy of the installation presentation available in [[http://open-ils.org/~denials/workshop.odp|OpenOffice Impress]] and [[http://open-ils.org/~denials/workshop.odp|PDF]] format.

=====To do=====

^ Who ^ What ^
| Dan | <del>Get Laurentian MARC data ready for import (create some basic script to munge it out)</del> - see http://open-ils.org/downloads |
| Dan | Burn CDs with tarballs and MARC data and script |

=====Download on your Linux server=====

  * http://open-ils.org/downloads/OpenSRF-0.9.tar.gz
  * http://open-ils.org/downloads/Evergreen-ILS-1.2.1.4.tar.gz
  * http://open-ils.org/~denials/import_demo.tar.gz
  * [[http://releases.mozilla.org/pub/mozilla.org/xulrunner/releases/1.8.1.3/contrib/linux-i686/xulrunner-1.8.1.3.en-US.linux-i686-20080128.tar.gz|xulrunner linux tarball]] (for Debian desktop people who have an ancient xulrunner)

=====Download on your Windows machine (if you have one)=====
  * http://open-ils.org/downloads/evergreen-setup-rel_1_2_1_4.exe

=====Install and configure Evergreen=====
  - Install OpenSRF
  - Install Evergreen
  - Configure opensrf_core.xml
    - Talk about the role of the router Jabber user versus the Evergreen application Jabber user.
  - Configure opensrf.xml
    - Talk about tuning (min connections, etc).
    - Talk about the services (with reference to upcoming changes in trunk).
    - Talk about database replicas (reports versus core).
  - Configure Apache
    - IP address changes
    - Talk about what mod_gateway and mod_xmlent do for us
  - Configure srfsh
    - Test connection
    - Introspect some services; call some services? Fun wow!
  - Try out the cgi-bin configuration scripts at http://localhost/cgi-bin/config.cgi:
    - Add a branch (talk about org_unit hierarchy)
    - Flip through circ, copy status, user groups, permissions
    - Mention Django admin alternative and likely future of admin

=====Import bib records and holdings=====

Dan has made 500 bib records in MARC21XML format from Laurentian available for download from the [[http://open-ils.org/downloads|Evergreen downloads page]] at http://open-ils.org/~denials/import_demo.tar.gz (including a README, some custom scripts, and the current trunk versions of marc2bre.pl, direct_ingest.pl, and parallel_pg_loader.pl).

  - Discuss: Evergreen concepts of libraries, copy locations, and the bib records/call numbers/copies hierarchy
  - Extract the files from ''import_demo.tar.gz'' and change directories:<code bash>
tar xzf import_demo.tar.gz
cd import_demo
</code>
  - Follow the steps from the [[http://open-ils.org/dokuwiki/doku.php?id=evergreen-admin:importing:bibrecords|Gutenberg example]] for importing bibs by running the import_bibs.sh script:<code bash>
# Ensure that the database name, user name, and password at the top of the script
# match your settings before running this script:
sh import_bibs.sh
</code>
    * Good chance to talk about the IDL - "what the heck is an msfe?!!" - and database
  - Edit pg_loader-output.sql to uncomment the "--COMMIT;" line to "COMMIT;" to enable your additions to the database to take place.
  - Load pg_loader-output.sql into the database:<code bash>
# Syntax: psql -U <username> -f pg_loader-output.sql <database>
psql -U evergreen -f pg_loader-output.sql evergreen</code>
  - Run the quick metarecord map to enable placing holds:<code bash>
psql -U evergreen -f quick_metarecord_map.sql evergreen</code>
  - Run ''parse_holdings.pl'' to generate a file called ''insert_holdings.sql''. ''parse_holdings.pl'' is just a basic script Dan wrote to extract the holdings into plain-jane SQL for the staging table import (PostgreSQL COPY format could be used but we might as well keep it simple for those not used to PostgreSQL).<code bash>
perl parse_holdings.pl
</code> Take a look at the output of ''parse_holdings.sh'' -- a file named ''insert_holdings.sql''. It's just a bunch of INSERT statements with the relevant copy attributes - and should be easy to create something similar from your own ILS holdings information.
  - Create the staging table:<code bash>
psql -U evergreen -f import_staging_table.sql evergreen</code>
  - Insert the holdings into the staging table:<code bash>
psql -U evergreen -f insert_holdings.sql evergreen</code>
  - Generate the locations, call numbers, and copies in the database from the entries in the staging table:<code bash>
psql -U evergreen -f generate_copies.sql evergreen</code>


=====Staff Client=====

Murph might be able to step in here and walk through a few interesting parts of the staff client.

  - Create a patron with an ''@localhost'' email account.
  - Do some circs
    * Circulation configuration - point out ''/openils/var/circ/*''
  - Cataloging
    - Groovy contextual help (soon to be available //en français//)
    - Item type templates - point out ''/openils/var/templates/marc/*''
  - Reporting interface if we feel spunky
  - Offline interface: 
     - Where is it?
     - How do you upload transactions once you're connected again?
     - What happens with conflicts, etc?
  - Discuss a bit of Mozilla XUL:
    - Look at the XML and JavaScript - it's not so scary
    - Benefits of server side XUL

=====OPAC time=====

Now that we have real live holdings in our system, we can do fun things with the catalog.

Let's use the existing [[http://open-ils.org/dokuwiki/doku.php?id=advocacy:evergreen_walk-through_script|advocacy script]] and pick some interesting things to point out - shelf browsing, etc.

Talk a little bit about how this is put together: HTML and JavaScript and calls back to OpenSRF services.

=====Customizing Evergreen: OPAC theme=====

We'll borrow from the [[http://open-ils.org/dokuwiki/doku.php?id=evergreen-admin:customizations:opac|OPAC customization]] documentation - thanks Karen!




=====Customizing Evergreen: new service=====
Patrons often forget passwords. Heck, I often forget passwords. The Evergreen catalog currently doesn't give you the ability to reset your password. We'll add that feature in front of a live audience.

  - Add the OpenSRF service [[advocacy:perl_reset_email|Perl Code]]
  - Add the "Reset my password" button to the catalog [[advocacy:js_reset_email|Javascript]]
  - For bonus points, define the service in ''Open-ILS/web/common/js/config.js'' and call the variable instead.

**The Perl and Javascript code are "quick and dirty" snippets.  They are meant to be examples of functional code, by some definition, but not good code.**