docs/admin_initial_setup/migrating_patron_data.adoc

   1 Migrating Patron Data
   2 =====================
   3
   4 Introduction
   5 ------------
   6
   7 This section will explain the task of migrating your patron data from comma
   8 delimited files into Evergreen. It does not deal with the process of exporting
   9 from the non-Evergreen system since this process may vary depending on where you
  10 are extracting your patron records. Patron could come from an ILS or it could
  11 come from a student database in the case of academic records.
  12
  13 When importing records into Evergreen you will need to populate 3 tables in your
  14 Evergreen database:
  15
  16 * actor.usr - The main table for user data
  17 * actor.card - Stores the barcode for users; Users can have more than 1 card but
  18 only 1 can be active at a given time;
  19 * actor.usr_address - Used for storing address information; A user can
  20 have more than one address.
  21
  22 Before following the procedures below to import patron data into Evergreen, it
  23 is a good idea to examine the fields in these tables in order to decide on a
  24 strategy for data to include in your import. It is important to understand the
  25 data types and constraints on each field.
  26
  27 . Export the patron data from your existing ILS or from another source into a
  28 comma delimited file. The comma delimited file used for importing the records
  29 should use Unicode (UTF8) character encoding.
  30
  31 . Create a staging table. A staging table will allow you to tweak the data before
  32 importing. Here is an example sql statement:
  33 +
  34 [source,sql]
  35 ----------------------------------
  36     CREATE TABLE students (
  37          student_id int, barcode text, last_name text, first_name text, email text,
  38                  address_type text, street1 text, street2 text,
  39         city text, province text, country text, postal_code text, phone text, profile
  40         int DEFAULT 2, ident_type int, home_ou int, claims_returned_count int DEFAULT
  41                 0, usrname text, net_access_level int DEFAULT 2, password text
  42     );
  43 -----------------------------------
  44 +
  45 NOTE: The _default_ variables allow you to set default for your library or to populate
  46 required fields in Evergreen if your data includes NULL values.
  47 +
  48 The data field profile in the above SQL script refers to the user group and should be an
  49 integer referencing the id field in permission.grp_tree. Setting this value will affect
  50 the permissions for the user. See the values in permission.grp_tree for possibilities.
  51 +
  52 ident_type is the identification type used for identifying users. This is a integer value
  53 referencing config.identification_type and should match the id values of that table. The
  54 default values are 1 for Drivers License, 2 for SSN or 3 for other.
  55 +
  56 home_ou is the home organizational unit for the user. This value needs to match the
  57 corresponding id in the actor.org_unit table.
  58 +
  59 . Copy records into staging table from a comma delimited file.
  60 +
  61 [source,sql]
  62 ----------------------------------
  63     COPY students (student_id, last_name, first_name, email, address_type, street1, street2,
  64         city, province, country, postal_code, phone)
  65         FROM '/home/opensrf/patrons.csv'
  66                 WITH CSV HEADER;
  67 -----------------------------------
  68 +
  69 The script will vary depending on the format of your patron load file (patrons.csv).
  70 +
  71 . Formatting of some fields to fit Evergreen filed formatting may be required. Here is an example
  72 of sql to adjust phone numbers in the staging table to fit the evergreen field:
  73 +
  74 [source,sql]
  75 ----------------------------------
  76     UPDATE students phone = replace(replace(replace(rpad(substring(phone from 1 for 9), 10, '-') ||
  77     substring(phone from 10), '(', ''), ')', ''), ' ', '-');
  78 ----------------------------------
  79 +
  80 Data ``massaging'' will be required to fit formats used in Evergreen.
  81 +
  82 . Insert records from the staging table into the actor.usr Evergreen table:
  83 +
  84 [source,sql]
  85 ----------------------------------
  86      INSERT INTO actor.usr (
  87         profile, usrname, email, passwd, ident_type, ident_value, first_given_name,
  88         family_name, day_phone, home_ou, claims_returned_count, net_access_level)
  89         SELECT profile, students.usrname, email, password, ident_type, student_id,
  90         first_name, last_name, phone, home_ou, claims_returned_count, net_access_level
  91         FROM students;
  92 ----------------------------------
  93 +
  94 . Insert records into actor.card from actor.usr .
  95 +
  96 [source,sql]
  97 ----------------------------------
  98     INSERT INTO actor.card (usr, barcode)
  99         SELECT actor.usr.id, students.barcode
 100         FROM students
 101                 INNER JOIN actor.usr
 102                         ON students.usrname = actor.usr.usrname;
 103 ----------------------------------
 104 +
 105 This assumes a one to one card patron relationship. If your patron data import has multiple cards
 106 assigned to one patron more complex import scripts may be required which look
 107 for inactive or active flags.
 108 +
 109 . Update actor.usr.card field with actor.card.id to associate active card with the user:
 110 +
 111 [source,sql]
 112 ----------------------------------
 113     UPDATE actor.usr
 114         SET card = actor.card.id
 115         FROM actor.card
 116         WHERE actor.card.usr = actor.usr.id;
 117 ----------------------------------
 118 +
 119 . Insert records into actor.usr_address to add address information for users:
 120 +
 121 [source,sql]
 122 ----------------------------------
 123     INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code)
 124         SELECT actor.usr.id, students.street1, students.street2, students.city, students.province,
 125         students.country, students.postal_code
 126         FROM students
 127         INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;
 128 ----------------------------------
 129 +
 130 . Update actor.usr.address with address id from address table.
 131
 132 [source,sql]
 133 ----------------------------------
 134     UPDATE actor.usr
 135         SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id
 136         FROM actor.usr_address
 137         WHERE actor.usr.id = actor.usr_address.usr;
 138 ----------------------------------
 139
 140 This assumes 1 address per patron. More complex scenarios may require more sophisticated SQL.
 141
 142 Creating an sql Script for Importing Patrons
 143 --------------------------------------------
 144
 145 The procedure for importing patron can be automated with the help of an sql script. Follow these
 146 steps to create an import script:
 147
 148 . Create an new file and name it import.sql
 149 . Edit the file to look similar to this:
 150
 151 [source,sql]
 152 ----------------------------------
 153     BEGIN;
 154
 155     -- Create staging table.
 156     CREATE TABLE students (
 157         student_id int, barcode text, last_name text, first_name text, email text, address_type text,
 158                 street1 text, street2 text, city text, province text, country text, postal_code text, phone
 159                 text, profile int, ident_type int, home_ou int, claims_returned_count int DEFAULT 0, usrname text,
 160         net_access_level int DEFAULT 2, password text
 161     );
 162
 163     --Copy records from your import text file
 164     COPY students (student_id, last_name, first_name, email, address_type, street1, street2, city, province,
 165         country, postal_code, phone, password)
 166         FROM '/home/opensrf/patrons.csv' WITH CSV HEADER;
 167
 168
 169     --Insert records from the staging table into the actor.usr table.
 170     INSERT INTO actor.usr (
 171         profile, usrname, email, passwd, ident_type, ident_value, first_given_name, family_name,
 172         day_phone, home_ou, claims_returned_count, net_access_level)
 173         SELECT profile, students.usrname, email, password, ident_type, student_id, first_name,
 174         last_name, phone, home_ou, claims_returned_count, net_access_level FROM students;
 175
 176     --Insert records from the staging table into the actor.usr table.
 177     INSERT INTO actor.card (usr, barcode)
 178         SELECT actor.usr.id, students.barcode
 179         FROM students
 180                 INNER JOIN actor.usr
 181                         ON students.usrname = actor.usr.usrname;
 182
 183     --Update actor.usr.card field with actor.card.id to associate active card with the user:
 184     UPDATE actor.usr
 185         SET card = actor.card.id
 186         FROM actor.card
 187         WHERE actor.card.usr = actor.usr.id;
 188
 189     --INSERT records INTO actor.usr_address from staging table.
 190     INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code)
 191         SELECT actor.usr.id, students.street1, students.street2, students.city, students.province,
 192         students.country, students.postal_code
 193         FROM students
 194         INNER JOIN actor.usr ON students.usrname = actor.usr.usrname;
 195
 196
 197    --Update actor.usr mailing address with id from actor.usr_address table.:
 198     UPDATE actor.usr
 199         SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id
 200         FROM actor.usr_address
 201         WHERE actor.usr.id = actor.usr_address.usr;
 202
 203     COMMIT;
 204 ----------------------------------
 205
 206 Placing the sql statements between BEGIN; and COMMIT; creates a transaction
 207 block so that if any sql statements fail, the entire process is canceled and the
 208 database is rolled back to its original state. Lines beginning with -- are
 209 comments to let you you what each sql statement is doing and are not processed.
 210
 211 Batch Updating Patron Data
 212 --------------------------
 213
 214 For academic libraries, doing batch updates to add new patrons to the Evergreen
 215 database is a critical task. The above procedures and import script can be
 216 easily adapted to create an update script for importing new patrons from
 217 external databases. If the data import file contains only new patrons, then, the
 218 above procedures will work well to insert those patrons. However, if the data
 219 load contains all patrons, a second staging table and a procedure to remove
 220 existing patrons from that second staging table may be required before importing
 221 the new patrons. Moreover, additional steps to update address information and
 222 perhaps delete inactive patrons may also be desired depending on the
 223 requirements of the institution.
 224
 225 After developing the scripts to import and update patrons have been created,
 226 another important task for library staff is to develop an import strategy and
 227 schedule which suits the needs of the library. This could be determined by
 228 registration dates of your institution in the case of academic libraries. It is
 229 important to balance the convenience of patron loads and the cost of processing
 230 these loads vs staff adding patrons manually.
 231