Docs reorg: cleanup syntax in the command line admin manual
[working/Evergreen.git] / docs / admin / patron_address_by_zip_code.adoc
1 Patron Address City/State/County Pre-Populate by ZIP Code
2 ---------------------------------------------------------
3
4 indexterm:[zips.txt, Populate Address by ZIP Code, ZIP code]
5
6 This feature saves staff time and increases accuracy when entering patron address information by
7 automatically filling in the City, State and County information based on the
8 ZIP code entered by the staff member.
9
10 *Released:* Evergreen 0.1, available in all versions.
11
12 Please be aware of the following when using this feature.
13
14 * ZIP codes do not always match 1 to 1 with City, State and County.  ZIP codes were designed for postal delivery and represent postal delivery zones that may cover more than one city, state or county.
15 ** It is currently only possible to have one match per ZIP code, but you can add an alert to those entries to prompt staff to double check the entered data.
16 * Only the first 5 digits of the ZIP are used.  ZIP+4 is not currently supported.
17 * The zips.txt data is loaded once at service startup and stored in memory, so changes to the zips.txt data file require that Evergreen be restarted.  Specifically, you need to restart the "open-ils.search" OpenSRF service.
18
19
20 Scoping and Permissions
21 ~~~~~~~~~~~~~~~~~~~~~~~
22
23 There are no staff client permissions associated with this feature since there is no staff client interface.
24
25 This feature affects all users of the system; there is no way to have separate settings per Org Unit.
26
27 Setup Steps
28 ~~~~~~~~~~~
29
30 Step 1 - Setup Data File
31 ^^^^^^^^^^^^^^^^^^^^^^^^
32
33 The default location and name of the data file is /openils/var/data/zips.txt on your Evergreen server.  You can choose a different location if needed.
34
35 The file format of your zips.txt will look like this (delimited by the .):
36
37 ID|*StateAbb*|*City*|*ZIP*|*IsDefault*|StateID|*County*|AreaCode|*AlertMesg*
38
39 The only fields that are used are *StateAbb*, *City*, *ZIP*, *IsDefault*, *County* and *AlertMesg*.
40
41 Most fields can be left blank if the information is not available and that data will not be entered.
42
43 .Data Field Descriptions
44 . ID - ID field to uniquely identify this row.  Not required, can be left blank.
45 . *StateAbb* - State abbreviation like "MN" or "ND".
46 . *City* - Name of city.
47 . *ZIP* - ZIP code, only first 5 digits used.
48 . *IsDefault* - Must be set to 1 for the row to be used.  Easy way to disable/enable a row.
49 . StateID - Unknown and unused.
50 . *County* - County name.
51 . AreaCode - Phone number area code, unused.
52 . *AlertMesg* - Message to display to staff to alert them of any special circumstances.
53
54 TIP: The Address Alerts feature -- described in the Staff Client Sysadmin manual -- can also be used to alert staff about certain addresses.
55
56 Here is an example of what the data file should look like.
57
58 .Example zips.txt
59 ----
60 |MN|Moorhead|56561|1||Clay||
61 |MN|Moorhead|56562|1||Clay||
62 |MN|Moorhead|56563|1||Clay||
63 |MN|Sabin|56580|1||Clay||
64 |MN|Ulen|56585|1||Clay||
65 |MN|Lake Itasca|56460|1||Clearwater County||
66 |MN|Bagley|56621|1||Clearwater||
67 |MN|Clearbrook|56634|1||Clearwater||
68 |MN|Gonvick|56644|1||Clearwater||
69 ----
70
71 Step 2 - Enable Feature
72 ^^^^^^^^^^^^^^^^^^^^^^^
73
74 The next step is to tell the system to use the zips.txt file that you created. This is done by editing /openils/conf/opensrf.xml. Look about halfway into the file and you may very well see a commented section in the file that looks similar to this:
75
76 ----
77           <!-- zip code database file -->
78           <!--<zips_file>/openils/var/data/zips.txt</zips_file>-->
79      </app_settings>
80 </open-ils.search>
81 ----
82
83 Uncomment the area by . ..  Change the file path if you placed your file in a different location.  The file should look like this after you are done.
84
85 ----
86           <!-- zip code database file -->
87           <zips_file>/openils/var/data/zips.txt</zips_file>
88      </app_settings>
89 </open-ils.search>
90 ----
91
92 .Save and Restart
93 Save your changes to the opensrf.xml file, restart Evergreen and restart Apache.
94
95 NOTE: The specific opensrf services you need to restart are "opensrf.setting" and "open-ils.search".
96
97 Step 3 - Test
98 ^^^^^^^^^^^^^
99
100 Open up the staff client and try to register a new patron.  When you get to the address section, enter a ZIP code that you know is in your zips.txt file.  The data from the file that matches your ZIP will auto fill the city, state and county fields.
101
102 ZIP Code Data
103 ~~~~~~~~~~~~~
104
105 There are several methods you can use to populate your zips.txt with data.
106
107 Manual Entry
108 ^^^^^^^^^^^^
109
110 If you only have a few communities that you serve, entering data manually may be the simplest approach.
111
112 Geonames.org Data
113 ^^^^^^^^^^^^^^^^^
114
115 Geonames.org provides free ZIP code to city, state and county information licensed under the Creative Commons Attribution 3.0 License, which means you need to put a link to them on your website.  Their data includes primary city, state and county information only.  It doesn't include info about which other cities are included in a ZIP code.  Visit http://www.geonames.org for more info.
116
117 The following code example shows you how to download and reformat the data into the zips.txt format.  You have the option to filter the data to only include certain states also.
118
119 [source,bash]
120 ----
121 ## How to get a generic Evergreen zips.txt for free
122 wget http://download.geonames.org/export/zip/US.zip
123 unzip US.zip
124 cut -f2,3,5,6 US.txt \
125 | perl -ne 'chomp; @f=split(/\t/); print "|" . join("|", (@f[2,1,0], "1", "", $f[3], "")), "|\n";' \
126 > zips.txt
127
128 ##Optionally filter the data to only include certain states
129 egrep "^\|(ND|MN|WI|SD)\|" zips.txt  > zips-mn.txt
130 ----
131
132 Commercial Data
133 ^^^^^^^^^^^^^^^
134
135 There are many vendors that sell databases that include ZIP code to city, state and county information.  A web search will easily find them.  Many of the commercial vendors will include more information on which ZIP codes cover multiple cities, counties and states, which you could use to populate the alert field.
136
137 Existing Patron Database
138 ^^^^^^^^^^^^^^^^^^^^^^^^
139
140 Another possibility is to use your current patron database to build your zips.txt.  Pull out the current ZIP, city, state, county unique rows and use them to form your zips.txt.
141
142 .Small Sites
143
144 For sites that serve a small geographic area (less than 30 ZIP codes), an sql query like the following will create a zips.txt for you.  It outputs the number of matches as the first field and sorts by ZIP code and number of matches.  You would need to go through the resulting file and deal with duplicates manually.
145
146 [source,bash]
147 ----
148 psql egdb26 -A -t -F $'|' \
149  -c "SELECT count(substring(post_code from 1 for 5)) as zipcount, state, \
150  city, substring(post_code from 1 for 5) as pc, \
151  '1', '', county, '', '' FROM actor.usr_address \
152  group by pc, city, state, county \
153  order by pc, zipcount DESC" > zips.txt
154 ----
155
156 .Larger Sites
157 For larger sites Ben Ostrowsky at ESI created a pair of scripts that handles deduping the results and adding in county information.  Instructions for use are included in the files.
158
159 * http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=elect_ZIPs
160 * http://git.esilibrary.com/?p=migration-tools.git;a=blob;f=enrich_ZIPs
161
162
163 Development
164 ~~~~~~~~~~~
165
166 If you need to make changes to how this feature works, such as to add support for other postal code formats, here is a list of the files that you need to look at.
167
168 . *Zips.pm* - contains code for loading the zips.txt file into memory and replying to search queries.  Open-ILS / src / perlmods / lib / OpenILS / Application / Search / Zips.pm
169 . *register.js* - This is where patron registration logic is located.  The code that queries the ZIP search service and fills the address is located here.  Open-ILS / web / js / ui / default / actor / user / register.js