docs/development/support_scripts.txt

   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  * autogen.sh
  27    -- Generates web files used by the OPAC, especially files related to
  28       organization unit hierarchy, fieldmapper IDL, locales selection,
  29       facet definitions, compressed JS files and related cache key
  30  * clark-kent.pl
  31    -- Used to start and stop the reporter (which runs scheduled reports)
  32  * <<_creating_the_evergreen_database,eg_db_config>>
  33    -- Creates database and schema, updates config files, sets Evergreen
  34       administrator username and password
  35  * fine_generator.pl
  36  * hold_targeter.pl
  37  * <<_importing_authority_records_from_command_line,marc2are.pl>>
  38    -- Converts authority records from MARC format to Evergreen objects
  39       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
  40  * marc2bre.pl
  41    -- Converts bibliographic records from MARC format to Evergreen objects
  42       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
  43  * marc2sre.pl
  44    -- Converts serial records from MARC format to Evergreen objects
  45       suitable for importing via pg_loader.pl (or parallel_pg_loader.pl)
  46  * <<_marc_export,marc_export>>
  47    -- Exports authority, bibliographic, and serial holdings records into
  48       any of these formats: USMARC, UNIMARC, XML, BRE, ARE
  49  * osrf_control
  50    -- Used to start, stop and send signals to OpenSRF services
  51  * parallel_pg_loader.pl
  52    -- Uses the output of marc2bre.pl (or similar tools) to generate the SQL
  53       for importing records into Evergreen in a parallel fashion
  54
  55
  56 anchor:_marc_export[]
  57
  58 === marc_export: Exporting Bibliographic Records into MARC files
  59
  60 indexterm:[marc_export]
  61
  62 The following procedure explains how to export Evergreen bibliographic
  63 records into MARC files using the *marc_export* support script. All steps
  64 should be performed by the `opensrf` user from your Evergreen server.
  65
  66 [NOTE]
  67 Processing time for exporting records depends on several factors such as
  68 the number of records you are exporting. It is recommended that you divide
  69 the export ID files (records.txt) into a manageable number of records if
  70 you are exporting a large number of records.
  71
  72  . Create a text file list of the Bibliographic record IDs you would like
  73 to export from Evergreen. One way to do this is using SQL:
  74 +
  75 [source,sql]
  76 ----
  77 SELECT DISTINCT bre.id FROM biblio.record_entry AS bre
  78     JOIN asset.call_number AS acn ON acn.record = bre.id
  79     WHERE bre.deleted='false' and owning_lib=101 \g /home/opensrf/records.txt;
  80 ----
  81 +
  82 This query creates a file called `records.txt` containing a column of
  83 distinct IDs of items owned by the organizational unit with the id 101.
  84
  85  . Navigate to the support-scripts folder
  86 +
  87 ----
  88 cd /home/opensrf/Evergreen-ILS*/Open-ILS/src/support-scripts/
  89 ----
  90
  91  . Run *marc_export*, using the ID file you created in step 1 to define which
  92    files to export. The following example exports the records into MARCXML format.
  93 +
  94 ----
  95 cat /home/opensrf/records.txt | ./marc_export --store -i -c /openils/conf/opensrf_core.xml \
  96     -x /openils/conf/fm_IDL.xml -f XML --timeout 5 > exported_files.xml
  97 ----
  98
  99 [NOTE]
 100 ====================
 101 `marc_export` was updated in Evergreen 2.6 and now does not output progress
 102 as it executes.
 103 ====================
 104
 105 [NOTE]
 106 ====================
 107 You can use the `--since` option to export records modified after a
 108 certain date and time.
 109 ====================
 110
 111 [NOTE]
 112 ====================
 113 By default, marc_export will use the reporter storage service, which should
 114 work in most cases. But if you have a separate reporter database and you
 115 know you want to talk directly to your main production database, then you
 116 can set the `--store` option to `cstore` or `storage`.
 117 ====================
 118
 119 [NOTE]
 120 ====================
 121 For more information, run marc_export with the -h option:
 122
 123  ./marc_export -h
 124 ====================
 125
 126
 127
 128 === Importing Authority Records from Command Line
 129
 130 indexterm:[marc2are.pl]
 131 indexterm:[pg_loader.pl]
 132
 133 The major advantages of the command line approach are its speed and its
 134 convenience for system administrators who can perform bulk loads of
 135 authority records in a controlled environment. For alternate instructions,
 136 see <<_importing_authority_records_from_the_staff_client,Importing
 137 Authority Records from the Staff Client>>.
 138
 139  . Run *marc2are.pl* against the authority records, specifying the user
 140 name, password, MARC type (USMARC or XML). Use `STDOUT` redirection to
 141 either pipe the output directly into the next command or into an output
 142 file for inspection. For example, to process a file with authority records
 143 in MARCXML format named `auth_small.xml` using the default user name and
 144 password, and directing the output into a file named `auth.are`:
 145 +
 146 ----
 147 cd Open-ILS/src/extras/import/
 148 perl marc2are.pl --user admin --pass open-ils --marctype XML auth_small.xml > auth.are
 149 ----
 150 +
 151 [NOTE]
 152 The MARC type will default to USMARC if the `--marctype` option is not specified.
 153
 154  . Run *pg_loader.pl* to generate the SQL necessary for importing the
 155 authority records into your system. To save time for very large batches
 156 of records, you could simply pipe the output of *marc2are.pl* directly
 157 into *pg_loader.pl*.
 158 +
 159 ----
 160 cd Open-ILS/src/extras/import/
 161 perl pg_loader.pl --auto are --order are auth.are > auth_load.sql
 162 ----
 163
 164  . Load the authority records from the SQL file that you generated in the
 165 last step into your Evergreen database using the psql tool. Assuming the
 166 default user name, host name, and database name for an Evergreen instance,
 167 that command looks like:
 168 +
 169 ----
 170 psql -U evergreen -h localhost -d evergreen -f auth_load.sql
 171 ----
 172
 173