1.6/admin/migratingdata.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3             xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="migratingdata" >\r
   4         <info>          \r
   5         <title>Migrating Data</title>\r
   6                 <abstract>\r
   7                         <para>Migrating data into Evergreen can be one of the most daunting tasks for an administrator. This chapter will explain some procedures to help to migrate \r
   8                         bibliographic records, copies and patrons into the Evergreen system. This chapter requires advanced ILS Administration experience, knowledge of Evergreen data structures, \r
   9                         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
  10                 </abstract>\r
  11         </info>    \r
  12         <section xml:id="migratingpatrons">\r
  13                 <title>Migrating Patron Data</title>\r
  14                 <para>\r
  15                 This section will explain the task of migrating your patron datas from Comma Delimited Files into Evergreen. It does not deal with the process of exporting from the non-Evergreen \r
  16                 system since this process may vary depending on where you are extracting your patron records. Patron could come from an ILS or it could come from a student database in the case of \r
  17                 academic records.               \r
  18                 </para>\r
  19                 <para>\r
  20                 This section will explain the task of migrating your patron datas from Comma Delimited Files into Evergreen. It does not deal with the process of exporting from the non-Evergreen \r
  21                 system since this process may vary depending on where you are extracting your patron records. Patron could come from an ILS or it could come from a student database in the case of \r
  22                 academic records.The Comma Delimited File usod for importing the records should use Unicode (UTF8) character encoding.                  \r
  23                 </para>\r
  24                 <para>When importing records into Evergreen you will need to populate 3 tables in your Evergreen databas:</para>\r
  25                 <itemizedlist>\r
  26                         <listitem><link linkend="actor.table.usr">actor.usr</link> - This is the main table for user data</listitem>\r
  27                         <listitem><link linkend="actor.table.card">actor.card</link> - Stores the barcode for users. Users can have more than 1 card but only 1 can be active at a given time.</listitem>\r
  28                         <listitem><link linkend="actor.table.usr_address">actor.usr_address</link> - Used for storing address information. A user can have more than one address.</listitem>\r
  29                 </itemizedlist>\r
  30                 <para>Before following the procedures below to import patron data into Evergreen, it is a good idea to examine the fields in these tables in order to decide on a strategy \r
  31                 for data to include \r
  32                 in your import. It is important to understand the data types and constraints of the fields.</para>\r
  33                 <procedure>\r
  34                         <step>\r
  35                                 <para>Export the patron data from your existing ILS or from another source into a Comma Delimited File.</para>\r
  36                         </step>\r
  37                         <step>\r
  38                                 <para>Create a staging table. A staging table will allow you to tweak the data before importing. Here is an example sql statement:</para>\r
  39 <programlisting language="sql">\r
  40 CREATE TABLE students (\r
  41         student_id int, barcode text, last_name text, first_name text, program_number text, program_name text, email text, address_type text, street1 text, street2 text, city text, province text, \r
  42         country text, postal_code text, phone text, profile int, ident_type int, home_ou int, claims_returned_count int DEFAULT 0, usrname text, net_access_level int DEFAULT 2, password text\r
  43 ); \r
  44 </programlisting>\r
  45                                 <para>Note the <varname>DEFAULT</varname> variables. These allow you to set default for your library or to pulate required fields if you data allows NULL values where \r
  46                                 fields are required in Evergreen.</para>\r
  47                         </step>\r
  48                         <step>\r
  49                                 <para>Formatting of some fields to fit Evergreen filed foprmatting may be required. Here is an example of sql to adjust phone numbers in the staging \r
  50                                 table top fit the evergreen field:</para>\r
  51 <programlisting language="sql">\r
  52 UPDATE students phone = replace(replace(replace(rpad(substring(phone from 1 for 9), 10, '-') || substring(phone from 10), '(', ''), ')', ''), ' ', '-');\r
  53 </programlisting>\r
  54                                 <para>Data <quote>masaging</quote> may be required to fit formats used in Evergreen.</para>\r
  55                         </step>\r
  56                         <step>\r
  57                                 <para>Insert records from the staging table into the <link linkend="actor.table.usr">actor.usr</link> Evergreen table:</para>\r
  58 <programlisting language="sql">\r
  59  INSERT INTO actor.usr (\r
  60         profile, usrname, email, passwd, ident_type, ident_value, first_given_name, family_name, day_phone, home_ou, claims_returned_count, net_access_level) SELECT profile, students.usrname, \r
  61         email, student_id, ident_type, student_id, first_name, last_name, phone, home_ou, claims_returned_count, net_access_level FROM students;\r
  62 </programlisting>                       \r
  63                         </step>\r
  64                         <step>\r
  65                                 <para>insert records into <link linkend="actor.table.card">actor.card</link> from <link linkend="actor.table.usr">actor.usr</link>.</para>\r
  66 <programlisting language="sql">\r
  67 INSERT INTO actor.card (usr, barcode) \r
  68         SELECT actor.usr.id, students.barcode \r
  69         FROM students \r
  70                 INNER JOIN actor.usr \r
  71                         ON students.usrname = actor.usr.usrname;\r
  72 </programlisting>               \r
  73                                 <para>This assumes a one to one card patron relationship. If your patron data import has multible cards assined to one patron more complex import scripts may be required                                       which look for inactive or active flags.</para> \r
  74                         </step>\r
  75                         <step>\r
  76                                 <para>Update actor.usr.card field with actor.card.id to associate active card with the user:</para>\r
  77 <programlisting language="sql">\r
  78 UPDATE actor.usr \r
  79         SET card = actor.card.id \r
  80         FROM actor.card \r
  81         WHERE actor.card.usr = actor.usr.id;\r
  82 </programlisting>                       \r
  83                         </step>\r
  84                         <step>\r
  85                                 <para>Insert records into actor.usr_address to add address inforamation for users:</para>\r
  86 <programlisting language="sql">\r
  87 INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code) \r
  88         SELECT actor.usr.id, students.street1, students.street2, students.city, students.province, students.country, students.postal_code \r
  89         FROM students \r
  90         INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;\r
  91 </programlisting>                       \r
  92                         </step>\r
  93                         <step>\r
  94                                 <para>update actor.usr.address with address id from address table.</para>\r
  95 <programlisting language="sql">\r
  96 UPDATE actor.usr \r
  97         SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id \r
  98         FROM actor.usr_address \r
  99         WHERE actor.usr.id = actor.usr_address.usr;\r
 100 </programlisting>       \r
 101                         <para>This assumes 1 address per student. More complex scenarios may require more sophisticated SQL.</para>             \r
 102                         </step>\r
 103                 </procedure>\r
 104                 <simplesect>\r
 105                         <title>Creating an sql Script for Importing Patrons</title>\r
 106                         <para>The procedure for importing patron can be automated with the help of an sql script. Follow these steps to create an import script:</para>\r
 107                 \r
 108                         <procedure>\r
 109                                 <step>\r
 110                                         <para>Create an new file and name it <filename>import.sql</filename></para>\r
 111 \r
 112                                 </step>\r
 113 \r
 114                                 <step>\r
 115                                         <para>Edit the file to look similar to this:</para>\r
 116 <programlisting>\r
 117 BEGIN;\r
 118 \r
 119 -- Create stagig table.\r
 120 CREATE TABLE students (\r
 121         student_id int, barcode text, last_name text, first_name text, program_number text, program_name text, email text, address_type text, street1 text, street2 text, city text, province text, \r
 122         country text, postal_code text, phone text, profile int, ident_type int, home_ou int, claims_returned_count int DEFAULT 0, usrname text, net_access_level int DEFAULT 2, password text\r
 123 ); \r
 124 \r
 125 \r
 126 --Insert records from the staging table into the actor.usr table.\r
 127 INSERT INTO actor.usr (\r
 128         profile, usrname, email, passwd, ident_type, ident_value, first_given_name, family_name, day_phone, home_ou, claims_returned_count, net_access_level) SELECT profile, students.usrname, \r
 129         email, student_id, ident_type, student_id, first_name, last_name, phone, home_ou, claims_returned_count, net_access_level FROM students;\r
 130 \r
 131 --Insert records from the staging table into the actor.usr table.\r
 132 INSERT INTO actor.card (usr, barcode) \r
 133         SELECT actor.usr.id, students.barcode \r
 134         FROM students \r
 135                 INNER JOIN actor.usr \r
 136                         ON students.usrname = actor.usr.usrname;\r
 137 \r
 138 --Update actor.usr.card field with actor.card.id to associate active card with the user:\r
 139 UPDATE actor.usr \r
 140         SET card = actor.card.id \r
 141         FROM actor.card \r
 142         WHERE actor.card.usr = actor.usr.id;\r
 143 \r
 144 --INSERT records INTO actor.usr_address from staging table.\r
 145 INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code) \r
 146         SELECT actor.usr.id, students.street1, students.street2, students.city, students.province, students.country, students.postal_code \r
 147         FROM students \r
 148         INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;\r
 149 \r
 150 \r
 151 --Update actor.usr mailing address with id from actor.usr_address table.:\r
 152 UPDATE actor.usr \r
 153         SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id \r
 154         FROM actor.usr_address \r
 155         WHERE actor.usr.id = actor.usr_address.usr;\r
 156 \r
 157 COMMIT;\r
 158 </programlisting>\r
 159                                         <para>Placing the sql statements between <code>BEGIN;</code> and <code>COMMIT;</code> creates a transaction block so that if any statements fail, the \r
 160                                         entire process is cancelled and the database is rolled back to its original state. Lines beginning with <emphasis>--</emphasis> are comments to let you you what \r
 161                                         each sql statement is doing and are not processed.</para> \r
 162                                 </step>\r
 163                         </procedure>\r
 164                 </simplesect>\r
 165                 <simplesect>\r
 166                         <title>Batch Updating Patron Data</title>\r
 167                         <para>For academic libraries, doing batch updates to add new patrons to the Evergreen database is a critical task. The above procedures and \r
 168                         import script can be easily adapted to create an update script for importing new patrons from external databases. If the data import file contains only new patrons, then, \r
 169                         the above procedures will work well to insert those patrons. However, if the data load contains all patrons, a second staging table and a procedure to remove existing                          patrons from that second staging table may be required before importing the new patrons. Moreover, additional steps to update address information and perhaps delete \r
 170                         inactive patrons may also be desired depending on the requirements of the intstitution.</para>\r
 171                         <para>After developing the scripts to import and update patrons have been created, another important task of library staff is to develop an strategy and schedule \r
 172                         which suits the needs of the library. This could be determined by registration dates of your institution in the case of academic libraries. It is important to balance \r
 173                         the convenience of patron loads and the cost of processing these loads vs staff adding patrons as needed.</para>   \r
 174                </simplesect> \r
 175         </section>\r
 176 </chapter>\r