LP#1673857: stamp schema update
[working/Evergreen.git] / docs / development / support_scripts.adoc
1 == Support Scripts
2
3 Various scripts are included with Evergreen in the `/openils/bin/` directory
4 (and in the source code in `Open-ILS/src/support-scripts` and
5 `Open-ILS/src/extras`). Some of them are used during
6 the installation process, such as `eg_db_config`, while others are usually
7 run as cron jobs for routine maintenance, such as `fine_generator.pl` and
8 `hold_targeter.pl`. Others are useful for less frequent needs, such as the
9 scripts for importing/exporting MARC records. You may explore these scripts
10 and adapt them for your local needs. You are also welcome to share your
11 improvements or ask any questions on the
12 http://evergreen-ils.org/communicate/[Evergreen IRC channel or email lists].
13
14 Here is a summary of the most commonly used scripts. The script name links
15 to more thorough documentation, if available.
16
17  * <<_processing_action_triggers,action_trigger_runner.pl>>
18    -- Useful for creating events for specified hooks and running pending events
19  * authority_authority_linker.pl
20    -- Links reference headings in authority records to main entry headings
21       in other authority records. Should be run at least once a day (only for
22           changed records).
23  * authority_control_fields.pl
24    -- Links bibliographic records to the best matching authority record.
25       Should be run at least once a day (only for changed records).
26       You can accomplish this by running _authority_control_fields.pl --days-back=1_
27  * autogen.sh
28    -- Generates web files used by the OPAC, especially files related to
29       organization unit hierarchy, fieldmapper IDL, locales selection,
30       facet definitions, compressed JS files and related cache key
31  * clark-kent.pl
32    -- Used to start and stop the reporter (which runs scheduled reports)
33  * <<_creating_the_evergreen_database,eg_db_config>>
34    -- Creates database and schema, updates config files, sets Evergreen
35       administrator username and password
36  * fine_generator.pl
37  * hold_targeter.pl
38  * <<_importing_authority_records_from_command_line,marc2are.pl>>
39    -- Converts authority records from MARC format to Evergreen objects
40       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
41  * marc2bre.pl
42    -- Converts bibliographic records from MARC format to Evergreen objects
43       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
44  * marc2sre.pl
45    -- Converts serial records from MARC format to Evergreen objects
46       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
47  * <<_marc_export,marc_export>>
48    -- Exports authority, bibliographic, and serial holdings records into
49       any of these formats: USMARC, UNIMARC, XML, BRE, ARE
50  * osrf_control
51    -- Used to start, stop and send signals to OpenSRF services
52  * parallel_pg_loader.pl
53    -- Uses the output of marc2bre.pl (or similar tools) to generate the SQL
54       for importing records into Evergreen in a parallel fashion
55
56
57 anchor:_marc_export[]
58
59 === marc_export: Exporting Bibliographic Records into MARC files
60
61 indexterm:[marc_export]
62
63 The following procedure explains how to export Evergreen bibliographic
64 records into MARC files using the *marc_export* support script. All steps
65 should be performed by the `opensrf` user from your Evergreen server.
66
67 [NOTE]
68 Processing time for exporting records depends on several factors such as
69 the number of records you are exporting. It is recommended that you divide
70 the export ID files (records.txt) into a manageable number of records if
71 you are exporting a large number of records.
72
73  . Create a text file list of the Bibliographic record IDs you would like
74 to export from Evergreen. One way to do this is using SQL:
75 +
76 [source,sql]
77 ----
78 SELECT DISTINCT bre.id FROM biblio.record_entry AS bre
79     JOIN asset.call_number AS acn ON acn.record = bre.id 
80     WHERE bre.deleted='false' and owning_lib=101 \g /home/opensrf/records.txt;
81 ----
82 +
83 This query creates a file called `records.txt` containing a column of
84 distinct IDs of items owned by the organizational unit with the id 101.
85
86  . Navigate to the support-scripts folder
87 +
88 ----
89 cd /home/opensrf/Evergreen-ILS*/Open-ILS/src/support-scripts/
90 ----
91
92  . Run *marc_export*, using the ID file you created in step 1 to define which
93    files to export. The following example exports the records into MARCXML format.
94 +
95 ----
96 cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensrf_core.xml \
97     -x /openils/conf/fm_IDL.xml -f XML --timeout 5 > exported_files.xml
98 ----
99
100 [NOTE]
101 ====================
102 `marc_export` was updated in Evergreen 2.6 and now does not output progress
103 as it executes.
104 ====================
105
106 [NOTE]
107 ====================
108 You can use the `--since` option to export records modified after a
109 certain date and time.
110 ====================
111
112 [NOTE]
113 ====================
114 By default, marc_export will use the reporter storage service, which should
115 work in most cases. But if you have a separate reporter database and you
116 know you want to talk directly to your main production database, then you
117 can set the `--store` option to `cstore` or `storage`. 
118 ====================
119
120 [NOTE]
121 ====================
122 For more information, run marc_export with the -h option:
123
124  ./marc_export -h
125 ====================
126
127
128
129 === Importing Authority Records from Command Line
130
131 indexterm:[marc2are.pl]
132 indexterm:[pg_loader.pl]
133
134 The major advantages of the command line approach are its speed and its
135 convenience for system administrators who can perform bulk loads of
136 authority records in a controlled environment. For alternate instructions,
137 see <<_importing_authority_records_from_the_staff_client,Importing
138 Authority Records from the Staff Client>>.
139
140  . Run *marc2are.pl* against the authority records, specifying the user
141 name, password, MARC type (USMARC or XML). Use `STDOUT` redirection to
142 either pipe the output directly into the next command or into an output
143 file for inspection. For example, to process a file with authority records
144 in MARCXML format named `auth_small.xml` using the default user name and
145 password, and directing the output into a file named `auth.are`:
146 +
147 ----
148 cd Open-ILS/src/extras/import/
149 perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are
150 ----
151 +
152 [NOTE]
153 The MARC type will default to USMARC if the `--marctype` option is not specified.
154
155  . Run *parallel_pg_loader.pl* to generate the SQL necessary for importing the
156 authority records into your system. This script will create files in your
157 current directory with filenames like `pg_loader-output.are.sql` and
158 `pg_loader-output.sql` (which runs the previous SQL file). To continue with the
159 previous example by processing our new `auth.are` file:
160 +
161 ----
162 cd Open-ILS/src/extras/import/
163 perl parallel_pg_loader.pl --auto are --order are auth.are
164 ----
165 +
166 [TIP]
167 To save time for very large batches of records, you could simply pipe the
168 output of *marc2are.pl* directly into *parallel_pg_loader.pl*.
169
170  . Load the authority records from the SQL file that you generated in the
171 last step into your Evergreen database using the psql tool. Assuming the
172 default user name, host name, and database name for an Evergreen instance,
173 that command looks like:
174 +
175 ----
176 psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql
177 ----
178
179