Docs: fix uneven lengths of code delimiter blocks
[Evergreen.git] / 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     -- Remove any old staging table.
156     DROP TABLE IF EXISTS students;
157
158     -- Create staging table.
159     CREATE TABLE students (
160         student_id text, barcode text, last_name text, first_name text, email text, address_type text, 
161                 street1 text, street2 text, city text, province text, country text, postal_code text, phone 
162                 text, profile int, ident_type int, home_ou int, claims_returned_count int DEFAULT 0, usrname text, 
163         net_access_level int DEFAULT 2, password text, already_exists boolean DEFAULT FALSE
164     ); 
165
166     --Copy records from your import text file
167     COPY students (student_id, last_name, first_name, email, address_type, street1, street2, city, province, 
168         country, postal_code, phone, password) 
169         FROM '/home/opensrf/patrons.csv' WITH CSV HEADER;  
170
171     --Determine which records are new, and which are merely updates of existing patrons
172     --You may with to also add a check on the home_ou column here, so that you don't
173     --accidentally overwrite the data of another library in your consortium.
174     --You may also use a different matchpoint than actor.usr.ident_value.
175     UPDATE students
176         SET already_exists = TRUE
177         FROM actor.usr
178         WHERE students.student_id = actor.usr.ident_value;
179
180     --Update the names of existing patrons, in case they have changed their name
181     UPDATE actor.usr
182         SET first_given_name = students.first_name, family_name=students.last_name
183         FROM students
184         WHERE actor.usr.ident_value=students.student_id
185         AND (first_given_name != students.first_name OR family_name != students.last_name)
186         AND students.already_exists;
187         
188     --Update email addresses of existing patrons
189     --You may wish to update other fields as well, while preserving others
190     --actor.usr.passwd is an example of a field you may not wish to update,
191     --since patrons may have set the password to something other than the
192     --default.
193     UPDATE actor.usr
194         SET email=students.email
195         FROM students
196         WHERE actor.usr.ident_value=students.student_id
197         AND students.email != ''
198         AND actor.usr.email != students.email
199         AND students.already_exists;
200
201     --Insert records from the staging table into the actor.usr table.
202     INSERT INTO actor.usr (
203         profile, usrname, email, passwd, ident_type, ident_value, first_given_name, family_name, 
204         day_phone, home_ou, claims_returned_count, net_access_level) 
205         SELECT profile, students.usrname, email, password, ident_type, student_id, first_name, 
206         last_name, phone, home_ou, claims_returned_count, net_access_level
207         FROM students WHERE NOT already_exists;
208
209     --Insert records from the staging table into the actor.card table.
210     INSERT INTO actor.card (usr, barcode) 
211         SELECT actor.usr.id, students.barcode 
212         FROM students 
213                 INNER JOIN actor.usr 
214                         ON students.usrname = actor.usr.usrname
215         WHERE NOT students.already_exists;
216
217     --Update actor.usr.card field with actor.card.id to associate active card with the user:
218     UPDATE actor.usr 
219         SET card = actor.card.id 
220         FROM actor.card 
221         WHERE actor.card.usr = actor.usr.id;
222
223     --INSERT records INTO actor.usr_address from staging table.
224     INSERT INTO actor.usr_address (usr, street1, street2, city, state, country, post_code) 
225         SELECT actor.usr.id, students.street1, students.street2, students.city, students.province, 
226         students.country, students.postal_code 
227         FROM students 
228         INNER JOIN actor.usr ON students.usrname = actor.usr.usrname
229         WHERE NOT students.already_exists;
230
231
232    --Update actor.usr mailing address with id from actor.usr_address table.:
233     UPDATE actor.usr 
234         SET mailing_address = actor.usr_address.id, billing_address = actor.usr_address.id 
235         FROM actor.usr_address 
236         WHERE actor.usr.id = actor.usr_address.usr;
237
238     COMMIT;
239 ----------------------------------
240
241 Placing the sql statements between BEGIN; and COMMIT; creates a transaction
242 block so that if any sql statements fail, the entire process is canceled and the
243 database is rolled back to its original state. Lines beginning with -- are
244 comments to let you you what each sql statement is doing and are not processed.
245
246 Batch Updating Patron Data
247 --------------------------
248
249 For academic libraries, doing batch updates to add new patrons to the Evergreen
250 database is a critical task. The above procedures and import script can be
251 easily adapted to create an update script for importing new patrons from
252 external databases. If the data import file contains only new patrons, then, the
253 above procedures will work well to insert those patrons. However, if the data
254 load contains all patrons, a second staging table and a procedure to remove
255 existing patrons from that second staging table may be required before importing
256 the new patrons. Moreover, additional steps to update address information and
257 perhaps delete inactive patrons may also be desired depending on the
258 requirements of the institution.
259
260 After developing the scripts to import and update patrons have been created,
261 another important task for library staff is to develop an import strategy and
262 schedule which suits the needs of the library. This could be determined by
263 registration dates of your institution in the case of academic libraries. It is
264 important to balance the convenience of patron loads and the cost of processing
265 these loads vs staff adding patrons manually.
266