Docs reorg: Adding a manual for command line administrators
[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.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
58 anchor:_marc_export[]
59
60 marc_export: Exporting Bibliographic Records into MARC files
61 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
62
63 indexterm:[marc_export]
64
65 The following procedure explains how to export Evergreen bibliographic
66 records into MARC files using the *marc_export* support script. All steps
67 should be performed by the `opensrf` user from your Evergreen server.
68
69 [NOTE]
70 Processing time for exporting records depends on several factors such as
71 the number of records you are exporting. It is recommended that you divide
72 the export ID files (records.txt) into a manageable number of records if
73 you are exporting a large number of records.
74
75  . Create a text file list of the Bibliographic record IDs you would like
76 to export from Evergreen. One way to do this is using SQL:
77 +
78 [source,sql]
79 ----
80 SELECT DISTINCT bre.id FROM biblio.record_entry AS bre
81     JOIN asset.call_number AS acn ON acn.record = bre.id 
82     WHERE bre.deleted='false' and owning_lib=101 \g /home/opensrf/records.txt;
83 ----
84 +
85 This query creates a file called `records.txt` containing a column of
86 distinct IDs of items owned by the organizational unit with the id 101.
87
88  . Navigate to the support-scripts folder
89 +
90 ----
91 cd /home/opensrf/Evergreen-ILS*/Open-ILS/src/support-scripts/
92 ----
93
94  . Run *marc_export*, using the ID file you created in step 1 to define which
95    files to export. The following example exports the records into MARCXML format.
96 +
97 ----
98 cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensrf_core.xml \
99     -x /openils/conf/fm_IDL.xml -f XML --timeout 5 > exported_files.xml
100 ----
101
102 [NOTE]
103 ====================
104 `marc_export` was updated in Evergreen 2.6 and now does not output progress
105 as it executes.
106 ====================
107
108 [NOTE]
109 ====================
110 You can use the `--since` option to export records modified after a
111 certain date and time.
112 ====================
113
114 [NOTE]
115 ====================
116 By default, marc_export will use the reporter storage service, which should
117 work in most cases. But if you have a separate reporter database and you
118 know you want to talk directly to your main production database, then you
119 can set the `--store` option to `cstore` or `storage`. 
120 ====================
121
122 [NOTE]
123 ====================
124 For more information, run marc_export with the -h option:
125
126  ./marc_export -h
127 ====================
128
129
130
131 Importing Authority Records from Command Line
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133
134 indexterm:[marc2are.pl]
135 indexterm:[pg_loader.pl]
136
137 The major advantages of the command line approach are its speed and its
138 convenience for system administrators who can perform bulk loads of
139 authority records in a controlled environment. For alternate instructions,
140 see the cataloging manual.
141
142  . Run *marc2are.pl* against the authority records, specifying the user
143 name, password, MARC type (USMARC or XML). Use `STDOUT` redirection to
144 either pipe the output directly into the next command or into an output
145 file for inspection. For example, to process a file with authority records
146 in MARCXML format named `auth_small.xml` using the default user name and
147 password, and directing the output into a file named `auth.are`:
148 +
149 ----
150 cd Open-ILS/src/extras/import/
151 perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are
152 ----
153 +
154 [NOTE]
155 The MARC type will default to USMARC if the `--marctype` option is not specified.
156
157  . Run *parallel_pg_loader.pl* to generate the SQL necessary for importing the
158 authority records into your system. This script will create files in your
159 current directory with filenames like `pg_loader-output.are.sql` and
160 `pg_loader-output.sql` (which runs the previous SQL file). To continue with the
161 previous example by processing our new `auth.are` file:
162 +
163 ----
164 cd Open-ILS/src/extras/import/
165 perl parallel_pg_loader.pl --auto are --order are auth.are
166 ----
167 +
168 [TIP]
169 To save time for very large batches of records, you could simply pipe the
170 output of *marc2are.pl* directly into *parallel_pg_loader.pl*.
171
172  . Load the authority records from the SQL file that you generated in the
173 last step into your Evergreen database using the psql tool. Assuming the
174 default user name, host name, and database name for an Evergreen instance,
175 that command looks like:
176 +
177 ----
178 psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql
179 ----
180
181 MARC Stream Importer
182 ~~~~~~~~~~~~~~~~~~~~
183
184 The MARC Stream Importer can import authority records or bibliographic records.
185 A single running instance of the script can import either type of record, based
186 on the record leader.
187
188 This support script has its own configuration file, _marc_stream_importer.conf_, 
189 which includes settings related to logs, ports, uses, and access control.
190
191 The importer is even more flexible than the staff client import, including the
192 following options:
193
194  * _--bib-auto-overlay-exact_ and _--auth-auto-overlay-exact_: overlay/merge on
195 exact 901c matches
196  * _--bib-auto-overlay-1match_ and _--auth-auto-overlay-1match_: overlay/merge
197 when exactly one match is found
198  * _--bib-auto-overlay-best-match_ and _--auth-auto-overlay-best-match_:
199 overlay/merge on best match
200  * _--bib-import-no-match_ and _--auth-import-no-match_: import when no match
201 is found
202
203 One advantage to using this tool instead of the staff client Import interface
204 is that the MARC Stream Importer can load a group of files at once.
205