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` does not output progress as it executes.
 105 ====================
 106
 107 Options
 108 ^^^^^^^
 109
 110 The *marc_export* support script includes several options.  You can find a complete list
 111 by running `./marc_export -h`.  A few key options are also listed below:
 112
 113 --descendants and --library
 114 +++++++++++++++++++++++++++
 115
 116 The `marc_export` script has two related options, `--descendants` and
 117 `--library`.  Both options take one argument of an organizational unit
 118
 119 The `--library` option will export records with holdings at the specified
 120 organizational unit only.  By default, this only includes physical holdings,
 121 not electronic ones (also known as located URIs).
 122
 123 The `descendants` option works much like the `--library` option
 124 except that it is aware of the org. tree and will export records with
 125 holdings at the specified organizational unit and all of its descendants.
 126 This is handy if you want to export the records for all of the branches
 127 of a system.  You can do that by specifying this option and the system's
 128 shortname, instead of specifying multiple `--library` options for each branch.
 129
 130 Both the `--library` and `--descendants` options can be repeated.
 131 All of the specified org. units and their descendants will be included
 132 in the output.  You can also combine `--library` and `--descendants`
 133 options when necessary.
 134
 135 --since
 136 +++++++
 137
 138 You can use the `--since` option to export records modified after a certain date and time.
 139
 140 --store
 141 +++++++
 142
 143 By default, marc_export will use the reporter storage service, which should
 144 work in most cases. But if you have a separate reporter database and you
 145 know you want to talk directly to your main production database, then you
 146 can set the `--store` option to `cstore` or `storage`.
 147
 148 --uris
 149 ++++++
 150 The `--uris` option (short form: `-u`) allows you to  export records with
 151 located URIs (i.e. electronic resources).  When used by itself, it will export
 152 only records that have located URIs.  When used in conjunction with `--items`,
 153 it will add records with located URIs but no items/copies to the output.
 154 If combined with a `--library` or `--descendants` option, this option will
 155 limit its output to those records with URIs at the designated libraries.  The
 156 best way to use this option is in combination with the `--items` and one of the
 157 `--library` or `--descendants` options to export *all* of a library's
 158 holdings both physical and electronic.
 159
 160
 161 Importing Authority Records from Command Line
 162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 163
 164 indexterm:[marc2are.pl]
 165 indexterm:[pg_loader.pl]
 166
 167 The major advantages of the command line approach are its speed and its
 168 convenience for system administrators who can perform bulk loads of
 169 authority records in a controlled environment. For alternate instructions,
 170 see the cataloging manual.
 171
 172  . Run *marc2are.pl* against the authority records, specifying the user
 173 name, password, MARC type (USMARC or XML). Use `STDOUT` redirection to
 174 either pipe the output directly into the next command or into an output
 175 file for inspection. For example, to process a file with authority records
 176 in MARCXML format named `auth_small.xml` using the default user name and
 177 password, and directing the output into a file named `auth.are`:
 178 +
 179 ----
 180 cd Open-ILS/src/extras/import/
 181 perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are
 182 ----
 183 +
 184 [NOTE]
 185 The MARC type will default to USMARC if the `--marctype` option is not specified.
 186
 187  . Run *parallel_pg_loader.pl* to generate the SQL necessary for importing the
 188 authority records into your system. This script will create files in your
 189 current directory with filenames like `pg_loader-output.are.sql` and
 190 `pg_loader-output.sql` (which runs the previous SQL file). To continue with the
 191 previous example by processing our new `auth.are` file:
 192 +
 193 ----
 194 cd Open-ILS/src/extras/import/
 195 perl parallel_pg_loader.pl --auto are --order are auth.are
 196 ----
 197 +
 198 [TIP]
 199 To save time for very large batches of records, you could simply pipe the
 200 output of *marc2are.pl* directly into *parallel_pg_loader.pl*.
 201
 202  . Load the authority records from the SQL file that you generated in the
 203 last step into your Evergreen database using the psql tool. Assuming the
 204 default user name, host name, and database name for an Evergreen instance,
 205 that command looks like:
 206 +
 207 ----
 208 psql -U evergreen -h localhost -d evergreen -f pg_loader-output.sql
 209 ----
 210
 211 Juvenile-to-adult batch script
 212 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 213
 214 The batch `juv_to_adult.srfsh` script is responsible for toggling a patron
 215 from juvenile to adult. It should be set up as a cron job.
 216
 217 This script changes patrons to adult when they reach the age value set in the
 218 library setting named "Juvenile Age Threshold" (`global.juvenile_age_threshold`).
 219 When no library setting value is present at a given patron's home library, the
 220 value passed in to the script will be used as a default.
 221
 222 MARC Stream Importer
 223 ~~~~~~~~~~~~~~~~~~~~
 224
 225 The MARC Stream Importer can import authority records or bibliographic records.
 226 A single running instance of the script can import either type of record, based
 227 on the record leader.
 228
 229 This support script has its own configuration file, _marc_stream_importer.conf_,
 230 which includes settings related to logs, ports, uses, and access control.
 231
 232 The importer is even more flexible than the staff client import, including the
 233 following options:
 234
 235  * _--bib-auto-overlay-exact_ and _--auth-auto-overlay-exact_: overlay/merge on
 236 exact 901c matches
 237  * _--bib-auto-overlay-1match_ and _--auth-auto-overlay-1match_: overlay/merge
 238 when exactly one match is found
 239  * _--bib-auto-overlay-best-match_ and _--auth-auto-overlay-best-match_:
 240 overlay/merge on best match
 241  * _--bib-import-no-match_ and _--auth-import-no-match_: import when no match
 242 is found
 243
 244 One advantage to using this tool instead of the staff client Import interface
 245 is that the MARC Stream Importer can load a group of files at once.
 246