Editing Coversheets Ingredient (section)

== Usage ==

This section describes how to use the script in the `bin/` directory of the coverhseets ingredient. 

=== Update Coversheets ===

This is the script below will check a specified number (i.e. <code>LIMIT</code>) of eprint records in your archive (i.e. <code>ARCHIVE_ID</code> that have their <code>coversheets_dirty</code> field set to <code>TRUE</code> because relevant metadata has been changed in those eprint records that requires the associated PDF documents to have their coversheeted versions updated because their coversheet information is no longer up to date.

 bin/check_coversheets &lt;ARCHIVE_ID&gt; &lt;LIMIT&gt;

==== As a Cron Job ====
Typically you would want to run this as the <code>eprints</code> user as a regular cron job.  The following is a typical cron job you would want to add to the <code>eprints</code> user's crontab. (It is assumed EPrints is installed under the path <code>/opt/eprints3</code>):

 */15 * * * * /opt/eprints3/ingredients/coversheets/bin/check_coversheets_cron my_archive 50 3600 2>&1 | grep -v -f /opt/eprints3/ingredients/coversheets/bin/ignore_warnings.txt

This uses an envelope script for <code>check_coversheets</code> called <code>check_coversheets_cron</code> to make sure that multiple instances are not being run by cron at the same time. The <code>3600</code> specifies how many seconds to wait until it assumes that a previous run of <code>check_coversheets_cron</code> has died without completing.  If this is not specified it will assume 7200 seconds (2 hours). The above cron job will try to coversheet the PDF documents for up to 50 eprints every 15 minutes.  This is a conservative estimate of how long this will take to complete.  Having the protection of `check_coversheets_cron` means 15 could probably be reduced to 5 or fewer minutes.  The <code>grep</code> command after the script is intended to remove arbitrary noise generated by Apache PDFBox, as PDFs often have syntax issues which produce warning messages but these can typically be ignored rather than generate emails to the eprints' user's inbox.

==== Temporarily Disable Cron Job ====
If you need to make some changes to your EPrints repository codebase or configuration and don't want cron job to run for a while, rather than disabling the cron job (and potentially forgetting to re-enable it), you can use the following command to disable the cron job for a set amount of time:

 bin/disable_coversheets &lt;ARCHIVE_ID&gt; &lt;SECONDS&gt;

E.g. 
 bin/disable_coversheets my_archive 3600

==== For Specific EPrint Records ====
If there is a specific eprint record for which you want to update its PDF documents, then you can use a slightly modified version of the <code>check_coversheets</code> command:

 bin/check_coversheets &lt;ARCHIVE_ID&gt; &lt;LIMIT&gt; [--eprintid=EPRINT_ID]
 
Let us say you want to update coversheets for eprint with ID 1234 for your archived called <code>my_archive</code>, then command would be:

 bin/check_coversheets my_archive 1 --eprintid=1234

=== Add Coversheets to Specific Documents ===

Generally, you should use the <code>check_coversheets</code> script to just update all PDF documents for a specific eprint but if you have some reason you only want to update a particular PDF document you can use the following command:

 bin/add_coversheet &lt;ARCHIVE_ID&gt; &lt;DOCUMENT_ID&gt;

This will use the specific coversheet template whose criteria is applicable to the document's associated eprint record.  


=== Remove Coversheets ===

You might decide that you no longer want to use coversheets and want to remove all coversheeted PDFs to save disk space.  You can use this command to remove all of these coversheeted PDF files:

 bin/delete_coversheets &lt;ARCHIVE_ID&gt;

Alternatively, if some EPrints no longer need coversheets due to a change in the criteria for a coversheet template and these do not get tidied up in good time automatically, thenyou can removed coversheets from the documents of one of more individual eprint records. (Make sure there are no spaces between each eprint ID).  E.g. 

 bin/delete_coversheets my_archive 1,2,3,4


=== Update Coversheet-related Metadata ===

If you have only just started using coversheets then updating coversheet-related metadata should not be necessary.  However, if you were using an old version of coversheets, such as the on available in the [https://bazaar.eprints.org/350/EPrints Bazaar], then you will want to run the following command to make sure all the metadata is in the correct format:

 bin/update_coversheet_data &lt;ARCHIVE_ID&gt;