as well as knowledge of how to export data from your current system or access to data export files from your current system.</para>\r
</abstract>\r
</info> \r
+ <section xml:id="migratingbibrecords">\r
+ <title>Migrating Bibliographic Records</title>\r
+ <para>\r
+ One of the most important and challenging tasks is migrating your bibliographic records to a new system. The procedure may be different depending on the system from which you \r
+ are migrating and the content of the marc records exported from the existing system. The proecedures in this section deal with the process once the data from the existing system \r
+ is exporterd into marc records. It does not cover exporting data from your existing non-Evergreen system.</para>\r
+ <para>Several tools for importing bibliographic records into Evergreen can be found in the Evergreen installation folder \r
+ (<filename class="directory">/home/opensrf/Evergreen-ILS-1.6.1.2/Open-ILS/src/extras/import/</filename> ) and are also available from the Evergreen repository \r
+ (<link xl:href="http://svn.open-ils.org/trac/ILS/browser/branches/rel_1_6_1/Open-ILS/src/extras/import" xl:title="import scripts - Evergreen repository">\r
+ http://svn.open-ils.org/trac/ILS/browser/branches/rel_1_6_1/Open-ILS/src/extras/import</link>).</para> \r
+ <simplesect>\r
+ <title>Converting MARC records to Evergreen BRE JSON format</title>\r
+ <para>If you are starting with MARC records from your existing system or another source, use the marc2bre.pl script to create the JSON representation of a bibliographic \r
+ record entry (hence bre) in Evergreen. <filename>marc2bre.pl</filename> can perform the following functions:</para>\r
+ <itemizedlist> \r
+ <listitem><para>Converts <systemitem>MARC-8</systemitem> encoded records to <systemitem>UTF-8</systemitem> encoding</para></listitem>\r
+ <listitem><para>Converts <systemitem>MARC21</systemitem> to <systemitem>MARCXML21</systemitem></para></listitem>\r
+ <listitem><para>Select the unique record number field (common choices are '035' or '001'; check your records as you might be surprised how a supposedly unique field \r
+ actually has duplicates, though marc2bre.pl will select a unique identifier for subsequent duplicates)</para></listitem>\r
+ <listitem><para>Extracts certain pertinent fields indexing and display purposes (along with the complete MARCXML21 record)</para></listitem>\r
+ <listitem><para>Sets the ID number of the first record from this batch to be imported into the biblio.record_entry table (hint - run the following \r
+ <systemitem>SQL</systemitem> to determine what this number should be to avoid conflicts:</para>\r
+<screen>\r
+<userinput>psql -U postgres evergreen</userinput>\r
+<userinput> # SELECT MAX(id)+1 FROM biblio.record_entry;</userinput>\r
+</screen>\r
+ </listitem>\r
+ <listitem>\r
+ <para>If you are processing multiple sets of MARC records with <command>marc2bre.pl</command>before loading the records into the database, you will need to keep track \r
+ of the starting ID number for each subsequent batch of records that you are importing. For example, if you are processing three files of MARC records with 10000 \r
+ records each into a clean database, you would use <option>–startid 1</option>, <option>–startid 10001</option>, and <option>–startid 20001</option> \r
+ parameters for each respective file.</para>\r
+ </listitem>\r
+ <listitem>\r
+ <para>Ignore <quote>trash</quote> fields that you do not want to retain in Evergreen</para>\r
+ </listitem>\r
+ <listitem>\r
+ <para>If you use <filename>marc2bre.pl</filename> to convert your MARC records from the <systemitem>MARC-8</systemitem> encoding to the UTF-8 encoding, it relies\r
+ on the <systemitem>MARC::Charset Perl</systemitem> module to complete the conversion. When importing a large set of items, you can speed up the process by using a \r
+ utility like <systemitem>marc4j</systemitem> or <systemitem>marcdumper</systemitem> to convert the records \r
+ to <systemitem>MARC21XML</systemitem> and <systemitem>UTF-8</systemitem> before running them through <command>marc2bre.pl</command> with the \r
+ <option>–marctype=XML</option> flag to tell <command>marc2bre.pl</command> that the records are already in <systemitem>MARC21XML</systemitem> format with \r
+ the <systemitem>UTF-8 </systemitem>encoding. If you take this approach, due to a current limitation of <systemitem>MARC::File::XML</systemitem> you have to do a \r
+ horrible thing and ensure that there are no namespace prefixes in front of the element names. <filename>marc2bre.pl</filename> cannot parse the following \r
+ example:</para>\r
+\r
+<programlisting language="xml">\r
+<![CDATA[\r
+\r
+<?xml version="1.0" encoding="UTF-8" ?>\r
+<marc:collection xmlns:marc="http://www.loc.gov/MARC21/slim" \r
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \r
+ xsi:schemaLocation="http://www.loc.gov/MARC/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd">\r
+ <marc:record>\r
+ <marc:leader>00677nam a2200193 a 4500</marc:leader>\r
+ <marc:controlfield tag="001">H01-0000844</marc:controlfield>\r
+ <marc:controlfield tag="007">t </marc:controlfield>\r
+ <marc:controlfield tag="008">060420s1950 xx 000 u fre d</marc:controlfield>\r
+ <marc:datafield tag="040" ind1=" " ind2=" ">\r
+ <marc:subfield code="a">CaOHCU</marc:subfield>\r
+ <marc:subfield code="b">fre</marc:subfield>\r
+ </marc:datafield>\r
+...\r
+]]>;\r
+</programlisting>\r
+ \r
+ <para>But marc2bre.pl can parse the same example with the namespace prefixes removed:</para>\r
+<programlisting language="xml">\r
+<![CDATA[\r
+<?xml version="1.0" encoding="UTF-8" ?>\r
+<collection xmlns:marc="http://www.loc.gov/MARC21/slim" \r
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \r
+ xsi:schemaLocation="http://www.loc.gov/MARC/slim http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd">\r
+ <record>\r
+ <leader>00677nam a2200193 a 4500</leader>\r
+ <controlfield tag="001">H01-0000844</controlfield>\r
+ <controlfield tag="007">t </controlfield>\r
+ <controlfield tag="008">060420s1950 xx 000 u fre d</controlfield>\r
+ <datafield tag="040" ind1=" " ind2=" ">\r
+ <subfield code="a">CaOHCU</subfield>\r
+ <subfield code="b">fre</subfield>\r
+ </datafield>\r
+...\r
+]]>;\r
+</programlisting>\r
+ </listitem>\r
+ </itemizedlist>\r
+ </simplesect>\r
+ <simplesect>\r
+ <title>Converting Records for Import into PostgreSQL</title>\r
+ <para>Once you have your records in Evergreen's <systemitem>BRE JSON</systemitem> format, you then need to use <command>direct_ingest.pl</command> to convert the records \r
+ into the generic ingest <systemitem>JSON</systemitem> format for Open-ILS. \r
+ This step uses the <systemitem>open-ils.ingest</systemitem> application to extract the data that will be indexed in the database. </para>\r
+ <para>Once you have your records in Open-ILS <systemitem>JSON</systemitem> ingest format, you then need to use <command>pg_loader.pl</command> to convert these records into a \r
+ set of <systemitem>SQL</systemitem> statements that you can use to \r
+ load the records into PostgreSQL. The <option>–order</option> and <option>–autoprimary</option> command line options (bre, mrd, mfr, etc) map to class IDs defined in \r
+ <filename>/openils/conf/fm_IDL.xml</filename>.</para>\r
+ </simplesect> \r
+ <simplesect>\r
+ <title>Adding Metarecords to the Database</title>\r
+ <para>One you have loaded the records into PostgreSQL, you can create metarecord entries in the <link linkend="metabib.table.metarecord">metabib.metarecord</link> table by running the following <systemitem>SQL</systemitem>:</para>\r
+<screen>\r
+<userinput>psql evergreen</userinput>\r
+<userinput># \i /home/opensrf/Evergreen-ILS-1.6*/src/extras/import/quick_metarecord_map.sql</userinput>\r
+</screen>\r
+ <para>Metarecords are required to place holds on items, among other actions.</para>\r
+ </simplesect> \r
+ </section>\r
+ <section xml:id="migratingbibrecordcopies">\r
+ <title>Adding Copies to Bibliographic Records</title> \r
+ <para>Once you've loaded the bibliographic records in Evergreen, you can search and view the records in the staff client, but they will not be visible in the catalogue. By \r
+ default, bibliographic records will not be visible in the catalogue until you add a copy representing a physical manifestation of that resource. You can add a copy manually through \r
+ the staff client via the Holdings maintenance screen, but if you're bulk-importing MARC records you probably want to bulk load the associated copies, call numbers, and barcodes as \r
+ well.</para>\r
+ <simplesect>\r
+ <title>Importing volumes and copies from <systemitem>MARC21XML</systemitem> holdings</title>\r
+ <para>There is currently no simple method for importing holdings based on the contents of the MARC holdings field (852, as specified by \r
+ <link xml:href="http://www.loc.gov/marc/holdings/">http://www.loc.gov/marc/holdings/</link>). \r
+ However, a more or less automated method could be built that performs the following steps:</para>\r
+ <procedure>\r
+ <step><para>Create a tab-delimited file that contains your holdings information</para>\r
+ <itemizedlist>\r
+ <listitem>Required fields: bibliographic ID, barcode, and call number</listitem> \r
+ <listitem>Optional fields: shelving location (text) – see the <link linkend="asset.table.copy">asset.copy table</link> for \r
+ possible fields to include</listitem>\r
+ </itemizedlist> \r
+ </step>\r
+ <step><para>Create a staging table that matches the contents of your tab-delimited file.</para>\r
+ </step>\r
+ <step><para>Insert the contents of your tab-delimited file into the table.</para>\r
+ </step>\r
+ <step><para>Generate <systemitem>SQL</systemitem> scripts for item import to match the staging table that you created.</para>\r
+ </step>\r
+ <step><para>Run the <systemitem>SQL</systemitem> scripts to create the holdings in Evergreen.</para>\r
+ </step>\r
+ </procedure>\r
+ <para>If an ILS has the concept of <quote>item categories</quote>, these may be mapped to Evergreen via statistical categories in the \r
+ <link linkend="asset.table.stat_cat">asset.stat_cat table</link> . Note that statistical categories cannot be used as search filters; individual branches can define \r
+ their own statistical categories; and define their own statistical category entries for individual items - best use case for statistical categories is probably for gifts.</para>\r
+ <para>In 2009, Conifer placed their <link xl:href="http://svn.open-ils.org/trac/ILS-Contrib/browser/conifer/branches/rel_1_6_1/tools/migration-scripts" \r
+ xl:title="Conifer migration tools">migration tools</link> \r
+ in the <link xl:href="http://svn.open-ils.org/trac/ILS-Contrib/browser/conifer" xl:title="Conifer ILS-Contrib SVN repository">Conifer ILS-Contrib SVN repository</link>, which might be useful samples augmenting the \r
+ basic staging table import approach.</para>\r
+ <para>In 2010, Equinox contributed a set of <link xl:href="http://git.esilibrary.com/?p=migration-tools.git;a=summary" xl:title="Equinox migration utilities">migration utilities</link></para>\r
+ </simplesect>\r
+ </section>\r
<section xml:id="migratingpatrons">\r
<title>Migrating Patron Data</title>\r
<para>\r
the convenience of patron loads and the cost of processing these loads vs staff adding patrons manually.</para> \r
</simplesect> \r
</section>\r
+ <section xml:id="electronicresourcesvisible"> \r
+ <title>Making electronic resources visible in the catalogue</title>\r
+ <para>For electronic resources that should be visible in the catalogue without any copies, you must set the source column value in the record.biblio_entry row for the respective \r
+ bibliographic record to a value that matches the corresponding ID of the <link linkend="config.table.bib-source">config.bib_source</link> where the transcendant value is \r
+ <emphasis>TRUE</emphasis>. Here's a practical example:</para>\r
+ <procedure>\r
+ <step>\r
+ <para>Connect to your Evergreen database with <command>psql</command> (substitute username / database name as required):</para>\r
+<screen>\r
+<userinput>psql -U postgres evergreen</userinput>\r
+</screen>\r
+ </step>\r
+ <step>\r
+ <para>Add a source for your electronic resources:</para>\r
+<screen>\r
+<userinput># INSERT INTO config.bib_source(quality, source, transcendant) VALUES (50, 'Institutional repository', TRUE);</userinput>\r
+</screen>\r
+ </step>\r
+ <step>\r
+ <para>Find the ID that was generated for your new source:</para>\r
+<screen>\r
+<userinput># SELECT ID FROM config.bib_source WHERE source = 'Institutional repository';</userinput>\r
+</screen>\r
+ </step>\r
+ <step>\r
+ <para>Update the source column for your bibliographic record for the electronic resource (for the sake of the example, let's assume that the ID returned from the new \r
+ source was 4, and that we know that the bib record with ID 75 is an electronic resource from your institutional repository):</para>\r
+<screen>\r
+<userinput># UPDATE biblio.record_entry SET source = 4 where biblio.record_entry.id=75;</userinput>\r
+</screen>\r
+ </step>\r
+ </procedure>\r
+ </section>\r
+ <section xml:id="emptydatabase">\r
+ <title>Restoring your Evergreen Database to an Empty State</title>\r
+ <para>If you've done a test import of records and you want to quickly get Evergreen back to a pristine state, you can create a clean Evergreen database schema by performing the \r
+ following:</para>\r
+ <procedure>\r
+ <step> \r
+<screen>\r
+<userinput>cd ILS/Open-ILS/src/sql/Pg/</userinput>\r
+</screen>\r
+ </step>\r
+ <step> \r
+ <para>Rebuild the database schema:</para>\r
+<screen>\r
+<userinput>./build-db.sh [db-hostname> [db-port] [db-name] [db-user] [db-password] [db-version]</userinput>\r
+</screen>\r
+ <caution><para>This will remove all of your data from the database and restore the default values.</para></caution> \r
+ </step>\r
+ </procedure>\r
+ </section>\r
</chapter>\r
Evergreen. Evergreen can support organizations as simple as a single library with one or more \r
branches or as complex as a consortium composed of many independently governed library \r
systems. Organizational unit types should never have proper names since they are only generic types .</para>\r
+ <tip><para>It is a good idea to set up all of your organizational types and units before loading other data. In many cases, editing or deleting organizational units and types \r
+ may be difficult once you have loaded records or users. </para></tip>\r
<para>The fields in the organizational unit type record include:</para>\r
<itemizedlist>\r
<listitem>Type Name - The name of the organization unit type.</listitem>\r
to be have the organization units of this type as their home unit.</para></step>\r
<step><para>Click <guibutton>Save</guibutton> to save your new organization type.\r
</para></step> \r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
</procedure>\r
<procedure>\r
<title>Deleting Organization Types<indexterm><primary>organization types</primary><secondary>deleting</secondary></indexterm></title>\r
tree.</para></step>\r
<step><para>Click <guibutton>Delete</guibutton>.</para></step>\r
<step><para>Click <guibutton>OK</guibutton> on the warning alert box.</para></step>\r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
<note>\r
<para>You will not be able to delete organization types if organization units are \r
assigned to that type. Before you can delete the organization \r
Type, you must change the organization type of the units associated with the type \r
or delete the units.</para>\r
</note>\r
+\r
</procedure>\r
<procedure>\r
<title>Editing Organization Types<indexterm><primary>organization types</primary><secondary>editing</secondary></indexterm></title>\r
organization type tree.</para></step>\r
<step><para>Make the changes in the right pane.</para></step>\r
<step><para>Click <guibutton>Save</guibutton> to save your changes.</para></step>\r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
</procedure>\r
</simplesect>\r
\r
and copies</secondary></indexterm></para></step>\r
<step><para>Check the <guilabel>OPAC Visible</guilabel> check box if you want this location to be \r
visible in the OPAC for searching.<indexterm><primary>Organization Units</primary><secondary>opac visible</secondary></indexterm></para></step>\r
- <step><para>Click <guibutton>Save</guibutton> to save your new organizational unit.</para></step> \r
+ <step><para>Click <guibutton>Save</guibutton> to save your new organizational unit.</para></step>\r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
</procedure>\r
<procedure>\r
<title>Deleting Organizational Units <indexterm><primary>organization units</primary><secondary>deleting</secondary></indexterm></title>\r
<step><para>Select the <emphasis>organizational unit</emphasis> you wish to delete from the organizational unit tree in the left pane.</para></step>\r
<step><para>Click<guibutton>Delete</guibutton>.</para></step>\r
<step><para>Click <guibutton>OK</guibutton> on the warning alert box.</para></step>\r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
<note>\r
<para>You will not be able to delete organizational units if you have \r
users, workstations or copies assigned to the unit. Before you can delete the \r
organizational unit, you must move its users, workstations, copies and other associated resources to other \r
- organizational units units.</para>\r
+ organizational units.</para>\r
</note>\r
</procedure>\r
<procedure>\r
organizational unit tree in the left pane.</para></step>\r
<step><para>Edit the fields in the right pane.</para></step>\r
<step><para>Click <guibutton>Save</guibutton> to save your changes.</para></step>\r
+ <step><para>From the server command line, run autogen to apply the changes to the database and scripts. Run the following command as the opensrf user:</para>\r
+<screen>\r
+<userinput>/openils/bin/autogen.sh -c /openils/conf/opensrf_core.xml -u</userinput>\r
+</screen> \r
+ </step> \r
+ <step><para>The staff client will need to be restarted for changes to appear.</para>\r
+ </step> \r
</procedure>\r
\r
</simplesect>\r
subdivided with <markup linkend="section">section</markup> or <markup\r
linkend="simplesect">simplesect</markup> elements.</para>\r
</glossdef></glossentry>\r
+ <glossentry xml:id="systemitem">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/systemitem.html">systemitem</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Indicates various system related resources and items. See the Docbook entry for classification possibilities. Use this in place of emphasis where applicable.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="command">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/command.html">command</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>The name of an executable program or other software command. Use this instead of <markup linkend="emphasis">emphasis</markup> where applicable.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="option">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/option.html">option</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Specify an option for a software command. Use this instead of <markup linkend="emphasis">emphasis</markup> where applicable.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="filename">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/filename.html">filename</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Specify a name of a file or directory. See docbook entrey for class options.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="screen">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/screen.html">screen</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Text that a user sees or might see on a computer screen</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="userinput">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/userinput.html">userinput</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Data entered by the user. Used with <markup linkend="screen">screen</markup> to differentiate input from output.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="computeroutput">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/computeroutput.html">computeroutput</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>Computer generated output. Used with <markup linkend="screen">screen</markup> to differentiate output from input.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="code">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/code.html">code</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>An inline code fragment.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="errortext">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/errortext.html">errortext</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>An error message.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="function">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/function.html">function</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>The name of a function or subroutine, as in a programming language.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="prompt">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/prompt.html">prompt</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>A character or string indicating the start of an input field in a computer display. Used with <markup linkend="screen">screen</markup> to indicate a prompt for user input.</para>\r
+ </glossdef></glossentry>\r
+ <glossentry xml:id="varname">\r
+ <glossterm>\r
+ <link xlink:href="http://www.docbook.org/tdg5/en/html/varname.html">varname</link>\r
+ </glossterm>\r
+ <glossdef>\r
+ <para>The name of a variable. Use this instead of <markup linkend="emphasis">emphasis</markup> where applicable.</para>\r
+ </glossdef></glossentry>\r
</glossary>\r
</section>\r
<section>\r
green, red, and yellow\r
respectively.</para></formalpara></glossdef>\r
</glossentry>\r
- \r
</glossary>\r
</section>\r
</chapter>\r
projects / working / Evergreen.git / commitdiff