Docs: documenting --items option of marc_export
[working/Evergreen.git] / docs / development / support_scripts.adoc
1 Support Scripts
2 ---------------
3
4 Various scripts are included with Evergreen in the `/openils/bin/` directory
5 (and in the source code in `Open-ILS/src/support-scripts` and
6 `Open-ILS/src/extras`). Some of them are used during
7 the installation process, such as `eg_db_config`, while others are usually
8 run as cron jobs for routine maintenance, such as `fine_generator.pl` and
9 `hold_targeter.pl`. Others are useful for less frequent needs, such as the
10 scripts for importing/exporting MARC records. You may explore these scripts
11 and adapt them for your local needs. You are also welcome to share your
12 improvements or ask any questions on the
13 http://evergreen-ils.org/communicate/[Evergreen IRC channel or email lists].
14
15 Here is a summary of the most commonly used scripts. The script name links
16 to more thorough documentation, if available.
17
18  * <<_processing_action_triggers,action_trigger_runner.pl>>
19    -- Useful for creating events for specified hooks and running pending events
20  * authority_authority_linker.pl
21    -- Links reference headings in authority records to main entry headings
22       in other authority records. Should be run at least once a day (only for
23           changed records).
24  * <<_authority_control_fields,authority_control_fields.pl>>
25    -- Links bibliographic records to the best matching authority record.
26       Should be run at least once a day (only for changed records).
27       You can accomplish this by running _authority_control_fields.pl --days-back=1_
28  * autogen.sh
29    -- Generates web files used by the OPAC, especially files related to
30       organization unit hierarchy, fieldmapper IDL, locales selection,
31       facet definitions, compressed JS files and related cache key
32  * clark-kent.pl
33    -- Used to start and stop the reporter (which runs scheduled reports)
34  * <<_creating_the_evergreen_database,eg_db_config>>
35    -- Creates database and schema, updates config files, sets Evergreen
36       administrator username and password
37  * fine_generator.pl
38  * hold_targeter.pl
39  * <<_importing_authority_records_from_command_line,marc2are.pl>>
40    -- Converts authority records from MARC format to Evergreen objects
41       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
42  * marc2bre.pl
43    -- Converts bibliographic records from MARC format to Evergreen objects
44       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
45  * marc2sre.pl
46    -- Converts serial records from MARC format to Evergreen objects
47       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
48  * <<_marc_export,marc_export>>
49    -- Exports authority, bibliographic, and serial holdings records into
50       any of these formats: USMARC, UNIMARC, XML, BRE, ARE
51  * osrf_control
52    -- Used to start, stop and send signals to OpenSRF services
53  * parallel_pg_loader.pl
54    -- Uses the output of marc2bre.pl (or similar tools) to generate the SQL
55       for importing records into Evergreen in a parallel fashion
56
57 anchor:_authority_control_fields[]
58
59 authority_control_fields: Connecting Bibliographic and Authority records
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61
62 indexterm:[authority control]
63
64 This script matches headings in bibliographic records to the appropriate
65 authority records. When it finds a match, it will add a subfield 0 to the 
66 matching bibliographic field.
67
68 Here is how the matching works:
69
70 [options="header",cols="1,1,3"]
71 |=========================================================
72 |Bibliographic field|Authority field it matches|Subfields that it examines
73
74 |100|100|a,b,c,d,f,g,j,k,l,n,p,q,t,u
75 |110|110|a,b,c,d,f,g,k,l,n,p,t,u
76 |111|111|a,c,d,e,f,g,j,k,l,n,p,q,t,u
77 |130|130|a,d,f,g,h,k,l,m,n,o,p,r,s,t
78 |600|100|a,b,c,d,f,g,h,j,k,l,m,n,o,p,q,r,s,t,v,x,y,z
79 |610|110|a,b,c,d,f,g,h,k,l,m,n,o,p,r,s,t,v,w,x,y,z
80 |611|111|a,c,d,e,f,g,h,j,k,l,n,p,q,s,t,v,x,y,z
81 |630|130|a,d,f,g,h,k,l,m,n,o,p,r,s,t,v,x,y,z
82 |648|148|a,v,x,y,z
83 |650|150|a,b,v,x,y,z
84 |651|151|a,v,x,y,z
85 |655|155|a,v,x,y,z
86 |700|100|a,b,c,d,f,g,j,k,l,n,p,q,t,u
87 |710|110|a,b,c,d,f,g,k,l,n,p,t,u
88 |711|111|a,c,d,e,f,g,j,k,l,n,p,q,t,u
89 |730|130|a,d,f,g,h,j,k,m,n,o,p,r,s,t
90 |751|151|a,v,x,y,z
91 |800|100|a,b,c,d,e,f,g,j,k,l,n,p,q,t,u,4
92 |830|130|a,d,f,g,h,k,l,m,n,o,p,r,s,t
93 |=========================================================
94
95
96 anchor:_marc_export[]
97
98 marc_export: Exporting Bibliographic Records into MARC files
99 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100
101 indexterm:[marc_export]
102 indexterm:[MARC records,exporting,using the command line]
103
104 The following procedure explains how to export Evergreen bibliographic
105 records into MARC files using the *marc_export* support script. All steps
106 should be performed by the `opensrf` user from your Evergreen server.
107
108 [NOTE]
109 Processing time for exporting records depends on several factors such as
110 the number of records you are exporting. It is recommended that you divide
111 the export ID files (records.txt) into a manageable number of records if
112 you are exporting a large number of records.
113
114  . Create a text file list of the Bibliographic record IDs you would like
115 to export from Evergreen. One way to do this is using SQL:
116 +
117 [source,sql]
118 ----
119 SELECT DISTINCT bre.id FROM biblio.record_entry AS bre
120     JOIN asset.call_number AS acn ON acn.record = bre.id 
121     WHERE bre.deleted='false' and owning_lib=101 \g /home/opensrf/records.txt;
122 ----
123 +
124 This query creates a file called `records.txt` containing a column of
125 distinct IDs of items owned by the organizational unit with the id 101.
126
127  . Navigate to the support-scripts folder
128 +
129 ----
130 cd /home/opensrf/Evergreen-ILS*/Open-ILS/src/support-scripts/
131 ----
132
133  . Run *marc_export*, using the ID file you created in step 1 to define which
134    files to export. The following example exports the records into MARCXML format.
135 +
136 ----
137 cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensrf_core.xml \
138     -x /openils/conf/fm_IDL.xml -f XML --timeout 5 > exported_files.xml
139 ----
140
141 [NOTE]
142 ====================
143 `marc_export` does not output progress as it executes.
144 ====================
145
146 Options
147 ^^^^^^^
148
149 The *marc_export* support script includes several options.  You can find a complete list
150 by running `./marc_export -h`.  A few key options are also listed below:
151
152 --descendants and --library
153 +++++++++++++++++++++++++++
154
155 The `marc_export` script has two related options, `--descendants` and
156 `--library`.  Both options take one argument of an organizational unit
157
158 The `--library` option will export records with holdings at the specified
159 organizational unit only.  By default, this only includes physical holdings,
160 not electronic ones (also known as located URIs).
161
162 The `descendants` option works much like the `--library` option
163 except that it is aware of the org. tree and will export records with
164 holdings at the specified organizational unit and all of its descendants.
165 This is handy if you want to export the records for all of the branches
166 of a system.  You can do that by specifying this option and the system's
167 shortname, instead of specifying multiple `--library` options for each branch.
168
169 Both the `--library` and `--descendants` options can be repeated.
170 All of the specified org. units and their descendants will be included
171 in the output.  You can also combine `--library` and `--descendants`
172 options when necessary.
173
174 --items
175 +++++++
176
177 The `--items` option will add an 852 field for every relevant item to the MARC
178 record.  This 852 field includes the following information:
179
180 [options="header",cols="2,3"]
181 |===================================
182 |Subfield          |Contents
183 |$b (occurrence 1) |Call number owning library shortname
184 |$b (occurrence 2) |Item circulating library shortname
185 |$c                |Shelving location
186 |$g                |Circulation modifier
187 |$j                |Call number
188 |$k                |Call number prefix
189 |$m                |Call number suffix
190 |$p                |Barcode
191 |$t                |Copy number
192 |$x                |Miscellaneous item information
193 |$y                |Price
194 |===================================
195
196
197 --since
198 +++++++
199
200 You can use the `--since` option to export records modified after a certain date and time.
201
202 --store
203 +++++++
204
205 By default, marc_export will use the reporter storage service, which should
206 work in most cases. But if you have a separate reporter database and you
207 know you want to talk directly to your main production database, then you
208 can set the `--store` option to `cstore` or `storage`. 
209
210 --uris
211 ++++++
212 The `--uris` option (short form: `-u`) allows you to  export records with
213 located URIs (i.e. electronic resources).  When used by itself, it will export
214 only records that have located URIs.  When used in conjunction with `--items`,
215 it will add records with located URIs but no items/copies to the output. 
216 If combined with a `--library` or `--descendants` option, this option will
217 limit its output to those records with URIs at the designated libraries.  The
218 best way to use this option is in combination with the `--items` and one of the
219 `--library` or `--descendants` options to export *all* of a library's
220 holdings both physical and electronic.
221
222
223 Importing Authority Records from Command Line
224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
226 indexterm:[marc2are.pl]
227 indexterm:[pg_loader.pl]
228 indexterm:[MARC records,importing,using the command line]
229
230 The major advantages of the command line approach are its speed and its
231 convenience for system administrators who can perform bulk loads of
232 authority records in a controlled environment. For alternate instructions,
233 see the cataloging manual.
234
235  . Run *marc2are.pl* against the authority records, specifying the user
236 name, password, MARC type (USMARC or XML). Use `STDOUT` redirection to
237 either pipe the output directly into the next command or into an output
238 file for inspection. For example, to process a file with authority records
239 in MARCXML format named `auth_small.xml` using the default user name and
240 password, and directing the output into a file named `auth.are`:
241 +
242 ----
243 cd Open-ILS/src/extras/import/
244 perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are
245 ----
246 +
247 [NOTE]
248 The MARC type will default to USMARC if the `--marctype` option is not specified.
249
250  . Run *parallel_pg_loader.pl* to generate the SQL necessary for importing the
251 authority records into your system. This script will create files in your
252 current directory with filenames like `pg_loader-output.are.sql` and
253 `pg_loader-output.sql` (which runs the previous SQL file). To continue with the
254 previous example by processing our new `auth.are` file:
255 +
256 ----
257 cd Open-ILS/src/extras/import/
258 perl parallel_pg_loader.pl --auto are --order are auth.are
259 ----
260 +
261 [TIP]
262 To save time for very large batches of records, you could simply pipe the
263 output of *marc2are.pl* directly into *parallel_pg_loader.pl*.
264
265  . Load the authority records from the SQL file that you generated in the
266 last step into your Evergreen database using the psql tool. Assuming the
267 default user name, host name, and database name for an Evergreen instance,
268 that command looks like:
269 +
270 ----
271 psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql
272 ----
273
274 Juvenile-to-adult batch script
275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276
277 The batch `juv_to_adult.srfsh` script is responsible for toggling a patron
278 from juvenile to adult. It should be set up as a cron job.
279
280 This script changes patrons to adult when they reach the age value set in the
281 library setting named "Juvenile Age Threshold" (`global.juvenile_age_threshold`).
282 When no library setting value is present at a given patron's home library, the
283 value passed in to the script will be used as a default.
284
285 MARC Stream Importer
286 ~~~~~~~~~~~~~~~~~~~~
287
288 indexterm:[MARC records,importing,using the command line]
289
290 The MARC Stream Importer can import authority records or bibliographic records.
291 A single running instance of the script can import either type of record, based
292 on the record leader.
293
294 This support script has its own configuration file, _marc_stream_importer.conf_, 
295 which includes settings related to logs, ports, uses, and access control.
296
297 The importer is even more flexible than the staff client import, including the
298 following options:
299
300  * _--bib-auto-overlay-exact_ and _--auth-auto-overlay-exact_: overlay/merge on
301 exact 901c matches
302  * _--bib-auto-overlay-1match_ and _--auth-auto-overlay-1match_: overlay/merge
303 when exactly one match is found
304  * _--bib-auto-overlay-best-match_ and _--auth-auto-overlay-best-match_:
305 overlay/merge on best match
306  * _--bib-import-no-match_ and _--auth-import-no-match_: import when no match
307 is found
308
309 One advantage to using this tool instead of the staff client Import interface
310 is that the MARC Stream Importer can load a group of files at once.
311