hazza/DSpace
1
0
Fork 0
mirror of https://github.com/DSpace/DSpace.git synced 2025-10-07 01:54:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated all sections to be consistent in format and style.

Browse Source 
git-svn-id: http://scm.dspace.org/svn/repo/dspace/trunk@4524 9c30dcfa-912a-0410-8fc2-9e0234be79fd
This commit is contained in:
Jeffrey Trimble
2009-11-14 20:24:08 +00:00
parent 845b88d575
commit 1d21beb31e
1 changed files with 1417 additions and 1037 deletions
Download Patch File Download Diff File Expand all files Collapse all files

632
dspace/docs/docbook/sys_admin.xml
View File

@@ -1,8 +1,8 @@
<?xml version='1.0' encoding='UTF-8'?>
<chapter remap="h1">
<title><anchor id="docbook-sys_admin.html"/>DSpace System Documentation: System Administration</title>
<title><anchor id="docbook-sys_admin.html"/>System Administration</title>
<para>DSpace operates on several levels: as a Tomcat servlet, cron jobs, and on-demand operations. This section explains many of the on-demand operations. Some of the command operations may be also set up as cron jobs. Many of these operations are performed at the Command Line Interface (CLI) also known as the Unix prompt ($:) Future reference will use the term CLI when the use needs to be at the command line.</para>
<para>Many of the commands use &apos;arguments&apos; to assist in the processing at hand. In many of the sections before you, there is present the following table to give you information about the command and what the &apos;arguments&apos; are. </para>
<para>Below is the &quot;Command Help Table&quot;. This table explains what data is contained in the individual command/help tables in the sections that follow.</para>
<table>
<title>Command Help Table</title>
<?dbhtml table-width="75%" ?>
@@ -23,20 +23,47 @@
<row>
<entry>Arguments:</entry>
<entry>
<emphasis>The necessary or optional arguments available to the user</emphasis>
<emphasis>The required/mandatory or optional arguments available to the user.</emphasis>
</entry>
</row>
</tbody></tgroup>
</table>
<para>&nbsp;</para>
<section remap="h2">
<title><anchor id="docbook-sys_admin.html-structbuilder" xreflabel="Community and
Collection Structure Importer"/>Community and Collection Structure Importer</title>
<para>This command-line tool gives you the ability to import a community and collection structure directly from a source XML file. It is executed as follows:</para>
<para>
<literal>[dspace]/bin/structure-builder -f [source xml] -o [output xml file] -e [administrator email]</literal>
</para>
<para>This will examine the contents of <literal>[source xml]</literal>, import the structure into DSpace while logged in as the supplied administrator, and then output the same structure to the output file, but including the handle for each imported community and collection as an attribute.</para>
<para>The source xml document needs to be in the following format:</para>
<title><anchor id="docbook-sys_admin.html-structbuilder" xreflabel="Community and Collection Structure Importer"/>Community and Collection Structure Importer</title>
<para>This CLI tool gives you the ability to import acommunity and collection structure directory froma source XML file.</para>
<table>
<title>Structure Importer Command Table</title>
<?dbhtml table-width="75%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry><literal>[dspace]/bin/dspace structure-builder</literal></entry>
</row>
<row>
<entry>Java class:</entry>
<entry><literal>org.dspace.administer.StructBuilder</literal></entry>
</row>
<row>
<entry>Argument: short and long (if available) forms:</entry>
<entry>Description of the argument</entry>
</row>
<row>
<entry><literal>-f</literal></entry>
<entry>Source xml file. </entry>
</row>
<row>
<entry><literal>-o</literal></entry>
<entry>Output xml file.</entry>
</row>
<row>
<entry><literal>-e</literal></entry>
<entry>Email of DSpace Administrator.</entry>
</row>
</tbody></tgroup>
</table>
<para>The administrator need to build the source xml document in the following format:</para>
<screen>&lt;import_structure&gt;
&lt;community&gt;
&lt;name&gt;Community Name&lt;/name&gt;
@@ -86,6 +113,9 @@ Collection Structure Importer"/>Community and Collection Structure Importer</tit
&lt;/community&gt;
&lt;/import_structure&gt;
</screen>
<para>This command-line tool gives you the ability to import a community and collection structure directly from a source XML file. It is executed as follows:</para>
<para><literal>[dspace]/bin/dspace structure-builder -f /path/to/source.xml -o path/to/output.xml -e admin@user.com</literal></para>
<para>This will examine the contents of <literal>[source xml]</literal>, import the structure into DSpace while logged in as the supplied administrator, and then output the same structure to the output file, but including the handle for each imported community and collection as an attribute.</para>
<section remap="h3">
<title>Limitation</title>
<itemizedlist>
@@ -131,8 +161,8 @@ Collection Structure Importer"/>Community and Collection Structure Importer</tit
</section>
<section remap="h3">
<title>METS packages</title>
<para>DSpace 1.4 includes a package disseminator and matching ingester for the DSpace METS SIP (Submission Information Package) format. They were created to help end users prepare sets of digital resources and metadata for submission to the archive using well-defined standards such as <ulink url="http://www.loc.gov/standards/mets/">METS</ulink>, <ulink url="http://www.loc.gov/standards/mods/">MODS</ulink>, and <ulink url="http://www.loc.gov/standards/premis/"
>PREMIS</ulink>. The plugin name is <literal>METS</literal> by default, and it uses MODS for descriptive metadata.</para>
<para>Since DSpace 1.4 release, the software includes a package disseminator and matching ingester for the DSpace METS SIP (Submission Information Package) format. They were created to help end users prepare sets of digital resources and metadata for submission to the archive using well-defined standards such as <ulink url="http://www.loc.gov/standards/mets/">METS</ulink>, <ulink url="http://www.loc.gov/standards/mods/">MODS</ulink>, and <ulink
url="http://www.loc.gov/standards/premis/">PREMIS</ulink>. The plugin name is <literal>METS</literal> by default, and it uses MODS for descriptive metadata.</para>
<para>The DSpace METS SIP profile is available at: <ulink url="http://www.dspace.org/standards/METS/SIP/profilev1p0/metsipv1p0.pdf">
<emphasis role="underline">http://www.dspace.org/standards/METS/SIP/profilev1p0/metsipv1p0.pdf</emphasis></ulink> .</para>
</section>
@@ -142,7 +172,7 @@ Collection Structure Importer"/>Community and Collection Structure Importer</tit
<title><anchor id="docbook-sys_admin.html-itemimporter" xreflabel="Item Importer and Exporter"/>Item Importer and Exporter</title>
<para>DSpace has a set of command line tools for importing and exporting items in batches, using the DSpace simple archive format. The tools are not terribly robust, but are useful and are easily modified. They also give a good demonstration of how to implement your own item importer if desired.</para>
<section remap="h3">
<title>DSpace Simple Archive Format</title>
<title><anchor id="docbook-sys_admin.html-dsaf" xreflabel="Dspace SAF"/>DSpace Simple Archive Format</title>
<para>The basic concept behind the DSpace&apos;s simple archive format is to create an archive, which is directory full of items, with a subdirectory per item. Each item directory contains a file for the item&apos;s descriptive metadata, and the files that make up the item.</para>
<screen>
archive_directory/
@@ -198,10 +228,8 @@ archive_directory/
<note>
<para>Before running the item importer over items previously exported from a DSpace instance, please first refer to <link linkend="docbook-sys_admin.html-transferitem">Transferring Items Between DSpace Instances</link>.</para>
</note>
<section remap="h4">
<title>Basic Introduction</title>
<table>
<title>Import Items Information table</title>
<title>Import Items Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
@@ -221,7 +249,7 @@ archive_directory/
</entry>
</row>
<row>
<entry>Arguments short and (long) forms):</entry>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
@@ -277,7 +305,6 @@ archive_directory/
<para>&Dagger; These are mutually exclusive.</para>
<para>The item importer is able to batch import unlimited numbers of items for a particular collection using a very simple CLI command and &apos;arguments&apos;
</para>
</section>
<section remap="h4">
<title>Adding Items to a Collection</title>
<para>To add items to a collection, you gather the following information:</para>
@@ -337,56 +364,195 @@ archive_directory/
</section>
<section remap="h3">
<title><anchor id="docbook-sys_admin.html-exportingitems"/>Exporting Items</title>
<para>The item exporter can export a single item or a collection of items, and creates a DSpace simple archive for each item to be exported. To export a collection&apos;s items you type:</para>
<screen>
[dspace]/bin/export --type=COLLECTION --id=collID --dest=dest_dir
--number=seq_num
</screen>
<para>The item exporter can export a single item or a collection of items, and creates a DSpace simple archive for each item to be exported.</para>
<table>
<title>Export Items Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry>
<emphasis><literal>[dspace]</literal></emphasis><literal>/bin/dspace export</literal>
</entry>
</row>
<row>
<entry>Java class:</entry>
<entry>
<literal>org.dspace.app.itemexport.ItemExport</literal>
</entry>
</row>
<row>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-t</literal> or <literal>--type</literal></entry>
<entry>Type of export. <literal>COLLECTION</literal> will inform the program you want the whole collection. <literal>ITEM</literal> will be only the specific item. (You will actually key in the keywords in all caps. See examples below.)</entry>
</row>
<row>
<entry><literal>-i</literal> or <literal>--ed</literal></entry>
<entry>The ID or Handle of the Collection or Item to export.</entry>
</row>
<row>
<entry><literal>-d</literal> or <literal>--dest</literal></entry>
<entry>The destination of where you want the file of items to be placed. You place the path if necessary. </entry>
</row>
<row>
<entry><literal>-n</literal> or <literal>--number</literal></entry>
<entry>Sequence number to begin export the items with. Whatever number you give, this will be the name of the first directory created for your export. The layout of the export is the same as you would set your layout for an Import.</entry>
</row>
<row>
<entry><literal>-m</literal> or <literal>--migrate</literal></entry>
<entry>Export the item/collection for migration. This will remove the handle and metadata that will be re-created in the new instance of DSpace.</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Brief Help.</entry>
</row>
</tbody></tgroup>
</table>
<para><emphasis role="bold">Exporting a Collection</emphasis></para>
<para>To export a collection's items you type at the CLI:</para>
<para>[dspace]/bin/dspace export --type=COLLECTION --id=collID --dest=dest_dir --number=seq_num</para>
<para>Short form:</para>
<para><literal>[dspace]/bin/dspace export -t COLLECTION -d CollID or Handle -d /path/to/destination -n Some_number</literal></para>
<para><emphasis role="bold">Exporting a Single Item</emphasis></para>
<para>The keyword <literal>COLLECTION</literal> means that you intend to export an entire collection. The ID can either be the database ID or the handle. The exporter will begin numbering the simple archives with the sequence number that you supply. To export a single item use the keyword <literal>ITEM</literal> and give the item ID as an argument:</para>
<screen>
[dspace]/bin/export --type=ITEM --id=itemID --dest=dest_dir
--number=seq_num
</screen>
<para><literal>[dspace]/bin/dspace export --type=ITEM --id=itemID --dest=dest_dir --number=seq_num</literal></para>
<para>Short form:</para>
<para><literal>[dspace]/bin/dspace export -t ITEM -i itemID or Handle -d /path/to/destination -n some_unumber</literal></para>
<para>Each exported item will have an additional file in its directory, named &apos;handle&apos;. This will contain the handle that was assigned to the item, and this file will be read by the importer so that items exported and then imported to another machine will retain the item&apos;s original handle.</para>
<para><emphasis role="bold">The <literal>-m</literal> Arugment</emphasis></para>
<para>Using the <literal>-m</literal> argument will export the item/collection and also perform the migration step. It will perform the same process that the next section <link linkend="docbook-sys_admin.html-transferitem">Transferring Items Between DSpace Instances </link> performs. We recommend that the next section be read in conjunction with this flag being used. </para>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-sys_admin.html-transferitem" xreflabel="Transferring Items
Between DSpace Instances"/>Transferring Items Between DSpace Instances</title>
<title><anchor id="docbook-sys_admin.html-transferitem" xreflabel="Transferring Items Between DSpace Instances"/>Transferring Items Between DSpace Instances</title>
<subtitle>Migration of Data</subtitle>
<para>Where items are to be moved between DSpace instances (for example from a test DSpace into a production DSpace) the item exporter and item importer can be used in conjunction with a script to assist in this process.</para>
<para>After running the item exporter each <literal>dublin_core.xml</literal> file will contain metadata that was automatically added by DSpace. These fields are as follows:</para>
<itemizedlist>
<listitem>
<para> date.accessioned</para>
<para>date.accessioned</para>
</listitem>
<listitem>
<para> date.available</para>
<para>date.available</para>
</listitem>
<listitem>
<para> date.issued</para>
<para>date.issued</para>
</listitem>
<listitem>
<para> description.provenance</para>
<para>description.provenance</para>
</listitem>
<listitem>
<para> format.extent</para>
<para>format.extent</para>
</listitem>
<listitem>
<para> format.mimetype</para>
<para>format.mimetype</para>
</listitem>
<listitem>
<para> identifier.uri</para>
<para>identifier.uri</para>
</listitem>
</itemizedlist>
<para>In order to avoid duplication of this metadata, run</para>
<para>
<literal>dspace_migrate &lt;exported item directory&gt;</literal>
</para>
<para>prior to running the item importer. This will remove the above metadata items, except for date.issued - if the item has been published or publicly distributed before and identifier.uri - if it is not the handle, from the <literal>dublin_core.xml</literal> file and remove all <literal>handle</literal> files. It will then be safe to run the item exporter. Use</para>
<para>
<literal>dspace_migrate --help</literal>
</para>
<para>for instructions on use of the script.</para>
<para><literal>dspace_migrate &lt;/path/to/exported item directory&gt;</literal></para>
<para>prior to running the item importer. This will remove the above metadata items, except for date.issued - if the item has been published or publicly distributed before and <literal>identifier.uri</literal> - if it is not the handle, from the <literal>dublin_core.xml</literal> file and remove all <literal>handle</literal> files. It will then be safe to run the item exporter.</para>
</section>
<section remap="h2">
<title><anchor id="docbook-sys_admin.html-itemupdate" xreflabel="Item Update"/>Item Update</title>
<para>ItemUpdate is a batch-mode command-line tool for altering the metadata and bitstream content of existing items in a DSpace instance. It is a companion tool to ItemImport and uses the DSpace simple archive format to specify changes in metadata and bitstream contents. Those familiar with generating the source trees for ItemImporter will find a similar environment in the use of this batch processing tool.</para>
<para>For metadata, ItemUpdate can perform &apos;add&apos; and &apos;delete&apos; actions on specified metadta elements. For bitstreams, &apos;add&apos; and &apos;delete&apos; are similarly available. All these actions can be combined in a single batch run.</para>
<para>ItemUpdate supports an undo feature for all actions except bitstream deletion. There is also a test mode, as with ItemImport. However, unlike ItemImport, there is no resume feature for incomplete processing. There is more extensive logging with a summary statement at the end with counts of successful and unsuccessful items processed.</para>
<para>One probable scenario for using this tool is where there is an external primary data source for which the DSpace instance is a secondary or down-stream system. Metadata and/or bitstream content changes in the primary system can be exported to the simple archive format to be used by ItemUpdate to synchronize the changes.</para>
<para>A note on terminology: <emphasis role="bold">item</emphasis> refers to a DSpace item. <emphasis role="bold">metadata element</emphasis> refers generally to a qualified or unqualified element in a schema in the form <literal>[schema].[element].[qualifier]</literal> or <literal>[schema].[element]</literal> and occasionally in a more specific way to the second part of that form. <emphasis role="bold"
>metadata field</emphasis> refers to a specific instance pairing a metadata element to a value.</para>
<section remap="h3">
<title>DSpace simple Archive Format</title>
<para>As with ItemImporter, the idea behind the DSpace&apos;s simple archive format is to create an archive directory with a subdirectory per item. There are a few additional features added to this format specifically for ItemUpdate. Note that in the simple archive format, the item directories are merely local references and only used by ItemUpdate in the log output.</para>
<para>The user is referred to the previous section <link linkend="docbook-sys_admin.html-dsaf">DSpace Simple Archive Format.</link></para>
<para>Additionally, the use of a <emphasis role="bold">delete_contents</emphasis> is now available. This file lists the bitstreams to be deleted, one bitstream ID per line. Currently, no other identifiers for bitstreams are usable for this function. This file is an addition to the Archive format specifically for ItemUpdate.</para>
<para>The optional suppress_undo file is a flag to indicate that the &apos;undo archive&apos; should not be written to disk. This file is usually written by the application in an undo archive to prevent a recursive undo. This file is an addition to the Archive format specifically for ItemUpdate.</para>
</section>
<section remap="h3">
<title>ItemUpdate Commands</title>
<table>
<title>ItemUpdate Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry>
<emphasis>
<literal>[dspace]</literal>
</emphasis>
<literal>/bin/dspace itemupdate</literal>
</entry>
</row>
<row>
<entry>Java class:</entry>
<entry>
<literal>org.dspace.app.itemimport.ItemUpdate</literal>
</entry>
</row>
<row>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-a</literal> or <literal>--addmetadata [metadata element]</literal></entry>
<entry>Repeatable for multiple elements. The metadata element should be in the form dc.x or dc.x.y. The mandatory argument indicates the metadata fields in the dublin_core.xml file to be added unless already present. However, duplicate fields will not be added to the item metadata without warning or error.</entry>
</row>
<row>
<entry><literal>-d</literal> or <literal>--deletemetadata [metadata element]</literal></entry>
<entry>Repeatable for multiple elements. All metadata fields matching the element will be deleted.</entry>
</row>
<row>
<entry><literal>-A</literal> or <literal>--addbitstream</literal></entry>
<entry>Adds bitstreams listed in the contents file with the bistream metadata cited there.</entry>
</row>
<row>
<entry><literal>-D</literal> or <literal>--deletebitstream [filter plug classname or alis]</literal></entry>
<entry>Not repeatable. With no argument, this operation deletes bistreams listed in the <literal>deletes_contents</literal> file. Only bitstream ids are recognized identifiers for this operatiotn. The optional filter argument is the classname of an implementation of <literal>org.dspace.app.itemdupate.BitstreamFilter</literal> class to identify files for deletion or one of the aliases (ORIGINAL, ORIGINAL_AND_DERIVATIVES, TEXT, THUMBNAIL) which reference existing filters based on membership in a bundle of that name. IN this case, the <literal>delete_contents</literal> file is not required for any item. The filter properties file will contains properties pertinent to the particular filer used. Multiple filters are not allowed.</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Displays brief command line help.</entry>
</row>
<row>
<entry><literal>-e</literal> or <literal>--eperson</literal></entry>
<entry>Email address of the person or the user's database ID <emphasis role="bold">(Required)</emphasis></entry>
</row>
<row>
<entry><literal>-s</literal> or <literal>--source</literal></entry>
<entry>Directory archive to process <emphasis role="bold">(Required)</emphasis></entry>
</row>
<row>
<entry><literal>-i</literal> or <literal>--itemidentifier</literal></entry>
<entry>Specifies an alternate metadata field (not a handle) used to hold an identifier used to match the DSpace item with that in the archive. If omitted, the item handle is expected to be located in the <literal>dc.identifier.uri</literal> field. (Optional)</entry>
</row>
<row>
<entry><literal>-t</literal> or <literal>--test</literal></entry>
<entry>Runs the process in test mode with logging but no changes applied to the DSpace instance. (Optional)</entry>
</row>
<row>
<entry><literal>-P</literal> or <literal>--alterprovenance</literal></entry>
<entry>Prevents any changes to the provenance field to represent changes in the bitstream content resulting from an Add or Delete. No provenance statements are written for thumbnails or text derivative bitstreams, un keepin with the practice of MediaFilterManager. (Optional)</entry>
</row>
<row>
<entry><literal>-F</literal> or <literal>--filterproperties</literal></entry>
<entry>The filter properties files to be used by the delete bitstreams action (Optional)</entry>
</row>
</tbody></tgroup>
</table>
</section>
<section>
<title>CLI Examples</title>
<para><emphasis role="bold">Adding Metadata</emphasis>:</para>
<para><literal>[dspace]/bin/dspace updateitem -e joe@user.com -s [path/to/archive] -a dc.description</literal></para>
<para><emphasis>This will add from your archive the dc element description based on the handle from the URI (since the -i argument wasn't used).</emphasis></para>
</section>
</section>
<section remap="h2">
<title><anchor id="docbook-sys_admin.html-registration" xreflabel="Registering (Not Importing) Bitstreams"/>Registering (Not Importing) Bitstreams</title>
@@ -403,14 +569,10 @@ Between DSpace Instances"/>Transferring Items Between DSpace Instances</title>
<para>The archive format for registration does not include the actual content files (bitstreams) being registered. The format is however a directory full of items to be registered, with a subdirectory per item. Each item directory contains a file for the item&apos;s descriptive metadata (<literal>dublin_core.xml</literal>) and a file listing the item&apos;s content files (<literal>contents</literal>), but not the actual content files themselves.</para>
<para>The <literal>dublin_core.xml</literal> file for item registration is exactly the same as for regular item import.</para>
<para>The <literal>contents</literal> file, like that for regular item import, lists the item&apos;s content files, one content file per line, but each line has the one of the following formats:</para>
<screen>
-r -s n -f filepath
<screen>-r -s n -f filepath
-r -s n -f filepath\tbundle:bundlename
-r -s n -f filepath\tbundle:bundlename\tpermissions: -[r|w] &apos;group
name&apos;
-r -s n -f filepath\tbundle:bundlename\tpermissions: -[r|w] &apos;group
name&apos;\tdescription: some text
</screen>
-r -s n -f filepath\tbundle:bundlename\tpermissions: -[r|w] &apos;group name&apos;
-r -s n -f filepath\tbundle:bundlename\tpermissions: -[r|w] &apos;group name&apos;\tdescription: some text</screen>
<para>where</para>
<itemizedlist>
<listitem>
@@ -437,16 +599,9 @@ Between DSpace Instances"/>Transferring Items Between DSpace Instances</title>
</itemizedlist>
<para>The bundle, that is everything after the filepath, is optional and is normally not used.</para>
<para>The command line for registration is just like the one for regular import:</para>
<screen>
dsrun org.dspace.app.itemimport.ItemImport --add
--eperson=joe@user.com --collection=collectionID --source=items_dir
--mapfile=mapfile
</screen>
<para>(or by using the short form)</para>
<screen>
dsrun org.dspace.app.itemimport.ItemImport -a -e joe@user.com -c
collectionID -s items_dir -m mapfile
</screen>
<para><literal>[dspace]/bin/dspace import -a -e joe@user.com -c collectionID -s items_dir -m mapfile</literal></para>
<para>(or by using the long form)</para>
<para><literal>[dspace]/bin/dspace import --add -eperson=joe@user.com --collection=collectionID --source=items_dir --map=mapfile</literal></para>
<para>The <literal>--workflow</literal> and <literal>--test</literal> flags will function as described in <link linkend="docbook-sys_admin.html-importingitems">Importing Items</link>.</para>
<para>The <literal>--delete</literal> flag will function as described in <link linkend="docbook-sys_admin.html-importingitems">Importing Items</link> but the registered content files will not be removed from storage. See <link linkend="docbook-sys_admin.html-deletingregistereditems">Deleting Registered Items</link>.</para>
<para>The <literal>--replace</literal> flag will function as described in <link linkend="docbook-sys_admin.html-importingitems">Importing Items</link> but care should be taken to consider different cases and implications. With old items and new items being registered or ingested normally, there are four combinations or cases to consider. Foremost, an old registered item deleted from DSpace using <literal>--replace</literal> will not be removed from the storage. See <link
@@ -482,27 +637,57 @@ dsrun org.dspace.app.itemimport.ItemImport -a -e joe@user.com -c
<section remap="h3">
<title>The Export Tool</title>
<para>This tool is obsolete, and does not export a complete AIP. It's use is strongly deprecated.</para>
<para>The METS export tool is invoked via the command line like this:</para>
<screen>
<emphasis> [dspace]</emphasis>/bin/dsrun org.dspace.app.mets.METSExport
--help
</screen>
<para>The tool can export an individual item, the items within a given collection, or everything in the DSpace instance. To export an individual item, use:</para>
<screen>
<emphasis> [dspace]</emphasis>/bin/dsrun org.dspace.app.mets.METSExport --item <emphasis>
[handle]</emphasis>
</screen>
<para>To export the items in collection <literal>hdl:123.456/789</literal>, use:</para>
<screen>
<emphasis> [dspace]</emphasis>/bin/dsrun org.dspace.app.mets.METSExport --collection
hdl:123.456/789
</screen>
<para>To export all the items DSpace, use:</para>
<screen>
<emphasis> [dspace]</emphasis>/bin/dsrun org.dspace.app.mets.METSExport
--all
</screen>
<para>With any of the above forms, you can specify the base directory into which the items will be exported, using <literal>--destination [directory]</literal>. If this parameter is omitted, the current directory is used.</para>
<table>
<title>Mets Export Command table</title>
<?dbhtml table-width="100%"?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry>
<emphasis>
<literal>[dspace]</literal>
</emphasis>
<literal>/bin/dspace mets-export</literal>
</entry>
</row>
<row>
<entry>Java class:</entry>
<entry><literal>org.dspace.app.mets.METSExport</literal></entry>
</row>
<row>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-a</literal> or <literal>--all</literal></entry>
<entry>Export all items in the archive.</entry>
</row>
<row>
<entry><literal>-c</literal> or <literal>--collection</literal></entry>
<entry>Handle of the collection to export.</entry>
</row>
<row>
<entry><literal>-d</literal> or <literal>--destination</literal></entry>
<entry>Destination directory.</entry>
</row>
<row>
<entry><literal>-i</literal> or <literal>--item</literal></entry>
<entry>Handle of the item to export.</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Help</entry>
</row>
</tbody></tgroup>
</table>
<para>The following are examples of the types of process the METS tool can provide.</para>
<para><emphasis role="bold">Exporting an individual item.</emphasis> From the CLI:</para>
<para><emphasis><literal>[dspace]</literal></emphasis><literal>/bin/dspace mets-export -i </literal><emphasis><literal>[handle] -d /path/to/destination</literal></emphasis></para>
<para><emphasis role="bold">Exporting a collection</emphasis>. From the CLI:</para>
<para><literal>[dspace]/bin/dspace mets-export -c [handle] -d /path/to/destination</literal></para>
<para><emphasis role="bold">Exporting all the items in DSpace.</emphasis> From the CLI:</para>
<para><literal>[dspace]/bin/dspace mets-export -a -d /path/to/destination</literal></para>
</section>
<section remap="h3">
<title>The AIP Format</title>
@@ -576,9 +761,7 @@ dsrun org.dspace.app.itemimport.ItemImport -a -e joe@user.com -c
Transforming DSpace Content"/>MediaFilters: Transforming DSpace Content</title>
<para>DSpace can apply filters to content/bitstreams, creating new content. Filters are included that extract text for <emphasis role="bold">full-text searching</emphasis>, and create <emphasis role="bold">thumbnails</emphasis> for items that contain images. The media filters are controlled by the <literal>MediaFilterManager</literal> which traverses the asset store, invoking the <literal>MediaFilter</literal> or <literal
>FormatFilter</literal> classes on bitstreams. The media filter plugin configuration <literal>filter.plugins</literal> in <literal>dspace.cfg</literal> contains a list of all enabled media/format filter plugins (see <link linkend="docbook-configure.html-mediafilters">Configuring Media Filters</link> for more information). The media filter system is intended to be run from the command line (or regularly as a cron task):</para>
<screen>
[dspace]/bin/filter-media
</screen>
<screen>[dspace]/bin/filter-media</screen>
<para>With no options, this traverses the asset store, applying media filters to bitstreams, and skipping bitstreams that have already been filtered.</para>
<para>
<emphasis role="bold">Available Command-Line Options:</emphasis>
@@ -664,29 +847,61 @@ Transforming DSpace Content"/>MediaFilters: Transforming DSpace Content</title>
</section>
<section remap="h2">
<title><anchor id="docbook-sys_admin.html-filiator" xreflabel="Sub-Community Management"/>Sub-Community Management</title>
<para>DSpace provides an administrative tool - &apos;CommunityFiliator&apos; - for managing community sub-structure. Normally this structure seldom changes, but prior to the 1.2 release sub-communities were not supported, so this tool could be used to place existing pre-1.2 communities into a hierarchy. It has two operations, either establishing a community to sub-community relationship, or dis-establishing an existing relationship.</para>
<para>The familiar parent/child metaphor can be used to explain how it works. Every community in DSpace can be either a &apos;parent&apos; community - meaning it has at least one sub-community, or a &apos;child&apos; community - meaning it is a sub-community of another community, or both or neither. In these terms, an &apos;orphan&apos; is a community that lacks a parent (although it can be a parent); &apos;orphans&apos; are referred to as &apos;top-level&apos; communities in the DSpace user-interface, since there is no parent community &apos;above&apos; them. The first operation - establishing a parent/child relationship - can take place between any community and an orphan. The second operation - removing a parent/child relationship - will make the child an orphan.</para>
<para>Using the dsrun utility in the dspace/bin directory, the establish operation looks like this:</para>
<screen>
dsrun org.dspace.administer.CommunityFiliator --set --parent=parentID
--child=childID
</screen>
<para>DSpace provides an administrative tool&mdash;&apos;CommunityFiliator&apos;&mdash;for managing community sub-structure. Normally this structure seldom changes, but prior to the 1.2 release sub-communities were not supported, so this tool could be used to place existing pre-1.2 communities into a hierarchy. It has two operations, either establishing a community to sub-community relationship, or dis-establishing an existing relationship.</para>
<para>The familiar parent/child metaphor can be used to explain how it works. Every community in DSpace can be either a &apos;parent&apos; community&mdash;meaning it has at least one sub-community, or a &apos;child&apos; community&mdash;meaning it is a sub-community of another community, or both or neither. In these terms, an &apos;orphan&apos; is a community that lacks a parent (although it can be a parent); &apos;orphans&apos; are referred to as &apos;top-level&apos; communities in the DSpace user-interface, since there is no parent community &apos;above&apos; them. The first operation&mdash;establishing a parent/child relationship - can take place between any community and an orphan. The second operation - removing a parent/child relationship&mdash;will make the child an orphan.</para>
<table>
<title>Community Filiator Command table</title>
<?dbhtml table-width="100%"?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry>
<emphasis>
<literal>[dspace]</literal>
</emphasis>
<literal>/bin/dspace community-filiator</literal>
</entry>
</row>
<row>
<entry>Java class:</entry>
<entry><literal>org.dspace.administer.CommunityFiliator</literal></entry>
</row>
<row>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-s</literal> or <literal>--set</literal></entry>
<entry>Set a parent/child relationship</entry>
</row>
<row>
<entry><literal>-r</literal> or <literal>--remove</literal></entry>
<entry>Remove a parent/child relationship</entry>
</row>
<row>
<entry><literal>-c</literal> or <literal>--child</literal></entry>
<entry>Child community (Handle or database ID)</entry>
</row>
<row>
<entry><literal>-p</literal> or <literal>--parent</literal></entry>
<entry>Parent community (Handle or database ID</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Online help.</entry>
</row>
</tbody></tgroup>
</table>
<para><emphasis role="bold">Set</emphasis> a parent/child relationship, issue the following at the CLI:</para>
<para><literal>dsrun org.dspace.administer.CommunityFiliator --set --parent=parentID --child=childID</literal></para>
<para>(or using the short form)</para>
<screen>
dsrun org.dspace.administer.CommunityFiliator -s -p parentID -c
childID
</screen>
<para><literal>[dspace]/bin dspace community-filiator -s -p parentID -c childID</literal></para>
<para>where &apos;-s&apos; or &apos;--set&apos; means establish a relationship whereby the community identified by the &apos;-p&apos; parameter becomes the parent of the community identified by the &apos;-c&apos; parameter. Both the &apos;parentID&apos; and &apos;childID&apos; values may be handles or database IDs.</para>
<para>The reverse operation looks like this:</para>
<screen>
dsrun org.dspace.administer.CommunityFiliator --remove
--parent=parentID --child=childID
</screen>
<para><literal>[dspace]/bin dspace community-filiator --remove --parent=parentID --child=childID</literal></para>
<para>(or using the short form)</para>
<screen>
dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
childID
</screen>
<para><literal>[dspace]/bin dspace community-filiator -r -p parentID -c childID</literal></para>
<para>where &apos;-r&apos; or &apos;--remove&apos; means dis-establish the current relationship in which the community identified by &apos;parentID&apos; is the parent of the community identified by &apos;childID&apos;. The outcome will be that the &apos;childID&apos; community will become an orphan, i.e. a top-level community.</para>
<para>If the required constraints of operation are violated, an error message will appear explaining the problem, and no change will be made. An example in a removal operation, where the stated child community does not have the stated parent community as its parent: &quot;Error, child community not a child of parent community&quot;.</para>
<para>It is possible to effect arbitrary changes to the community hierarchy by chaining the basic operations together. For example, to move a child community from one parent to another, simply perform a &apos;remove&apos; from its current parent (which will leave it an orphan), followed by a &apos;set&apos; to its new parent.</para>
@@ -694,7 +909,7 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
</section>
<section remap="h2">
<title><anchor id="docbook-sys_admin.thml-bulkedits" xreflabel="Bulk Metadata Editing"/>Batch Metadata Editing</title>
<para>Dspace provides a batch metadata editing tool. The batch editing tool is able to produce a comma delimited file in the CVS format. The batch editing tool facilitates the user to perform the following:</para>
<para>DSpace provides a batch metadata editing tool. The batch editing tool is able to produce a comma delimited file in the CVS format. The batch editing tool facilitates the user to perform the following:</para>
<itemizedlist>
<listitem>
<para>Batch editing of metadata (e.g. perform an external spell check)</para>
@@ -719,7 +934,7 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
<title>Export Function</title>
<para>The following table summarizes the basics.</para>
<table>
<title>Batch metatdata export information table</title>
<title>Batch Editing Metatdata Export Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
@@ -775,7 +990,7 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
<title>Import Function</title>
<para>The following table summarizes the basics.</para>
<table>
<title>Batch metatdata export information table</title>
<title>Batch Editing Metatdata Import Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="30*"/><colspec colname="c2" colwidth="70*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
@@ -793,7 +1008,7 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
<entry>org.dspace.app.bulkedit.MetadataImport</entry>
</row>
<row>
<entry>Arguments short and (long) forms):</entry>
<entry>Arguments short and (long) forms:</entry>
<entry>Description</entry>
</row>
<row>
@@ -998,23 +1213,27 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
<para>The checker will keep starting new bitstream checks for the specific durations, so actual execution duration will be slightly longer than the specified duration. Bear this in mind when scheduling checks.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Specific Bistream mode:</emphasis> <literal>[dspace]/bin/dspace checker -b</literal></para>
<para><emphasis role="bold">Specific Bistream mode:</emphasis>
<literal>[dspace]/bin/dspace checker -b</literal></para>
<para>Checker will only look at the internal bitsteam IDs.</para>
<para>Example: <literal>[dspace]/bin/dspace checker -b 112 113 4567</literal> Checker will only check bitstream IDs 112, 113 and 4567.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Specific Handle mode:</emphasis> <literal>[dspace]/bin/dspace checker -a</literal></para>
<para><emphasis role="bold">Specific Handle mode:</emphasis>
<literal>[dspace]/bin/dspace checker -a</literal></para>
<para>Checkr will only check bistreams within the Community, Community or the item itself.</para>
<para>Example: <literal>[dspace]/bin/dspace checker -a 123456/999</literal> Checker will only check this handle. If it is a Collection or Community, it will run through the entire Collection or Community.</para>
<para>The Check</para>
</listitem>
<listitem>
<para><emphasis role="bold">Looping mode:</emphasis> <literal>[dspace]/bin/dspace checker -l</literal> or <literal>[dspace]/bin/dspace checker -L</literal></para>
<para><emphasis role="bold">Looping mode:</emphasis>
<literal>[dspace]/bin/dspace checker -l</literal> or <literal>[dspace]/bin/dspace checker -L</literal></para>
<para>There are two modes. The lowercase &apos;el&apos; (-l) specifies to check every bitstream in the repository once. This is recommended for smaller repositories who are able to loop through all their content in just a few hours maximum. An uppercase &apos;L&apos; (-L) specifies to continuously loops through the repository. This is not recommended for most repository systems. </para>
<para><emphasis role="bold">Cron Jobs</emphasis>. For large repositories that cannot be completely checked in a couple of hours, we recommend the -d option in cron.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Pruning mode:</emphasis> <literal>[dspace]/bin/dspace checker -p</literal></para>
<para><emphasis role="bold">Pruning mode:</emphasis>
<literal>[dspace]/bin/dspace checker -p</literal></para>
<para>The Checksum Checker will store the result of every check in the checksum_histroy table. By default, successful checksum matches that are eight weeks old or older will be deleted when the -p option is used. (Unsuccessful ones will be retained indefinitel). Without this option, the retention settings are ignored and the database table may grow rather large!</para>
</listitem>
</itemizedlist>
@@ -1029,16 +1248,14 @@ dsrun org.dspace.administer.CommunityFiliator -r -p parentID -c
</listitem>
<listitem>
<para>Pass in a properties file containting retention policies when using the -p option.</para>
<para>To do this, create a file with the following two property keys:
<screen>checker.retention.default = 10y
checker.retention.CHECKSUM_MATCH = 8w</screen>
You can use the table above for your time units.</para>
<para>At the command line:
<screen>[dspace]/bin/dspace checker -p retention_file_name &lt;ENTER&gt;</screen></para></listitem>
<para>To do this, create a file with the following two property keys: <screen>checker.retention.default = 10y
checker.retention.CHECKSUM_MATCH = 8w</screen> You can use the table above for your time units.</para>
<para>At the command line: <screen>[dspace]/bin/dspace checker -p retention_file_name &lt;ENTER&gt;</screen></para>
</listitem>
</orderedlist>
</section>
<section remap="h3">
<title>Chcker Reporting</title>
<title>Checker Reporting</title>
<para>Checksum Checker uses log4j to report its results. By default it will report to a log called <literal>[dspace]/log/checker.log</literal>, and it will report only on bitstreams for which the newly calculated checksum does not match the stored checksum. To report on all bitstreams checked regardless of outcome, use the <literal>-v</literal> (verbose) command line option:</para>
<para><literal>[dspace]/bin/dspace checker -l -v</literal> (This will loop through the repository once and report in detail about every bitstream checked.</para>
<para>To change the location of the log, or to modify the prefix used on each line of output, edit the <literal>[dspace]/config/templates/log4j.properties</literal> file and run <literal>[dspace]/bin/install_configs</literal>.</para>
@@ -1047,15 +1264,14 @@ checker.retention.CHECKSUM_MATCH = 8w</screen>
<title>Cron or Automatic Execution of Checksum Checker</title>
<para>You should schedule the Checksum Checker to run automatically, based on how frequently you backup your DSpace instance (and how long you keep those backups). The size of your repository is also a factor. For very large repositories, you may need to schedule it to run for an hour (e.g. <literal>-d 1h</literal> option) each evening to ensure it makes it through your entire repository within a week or so. Smaller repositories can likely get by with just running it weekly.</para>
<para><emphasis role="bold">Unix, Linux, or MAC OS</emphasis>. You can schedule it by adding a cron entry similar to the following to the crontab for the user who installed DSpace:</para>
<para><literal>0 4 ** 0 <emphasis>[dspace]</emphasis>/bin/dspace checker -d2h -p</literal></para>
<para><literal>0 4 ** 0 [dspace]/bin/dspace checker -d2h -p</literal></para>
<para>The above cron entry would schedule the checker to run the checker every Sunday at 400 (4:00 a.m.) for 2 hours. It also specifies to &apos;prune&apos; the database based on the retention settings in <literal>dspace.cfg</literal>.</para>
<para><emphasis role="bold">Windows OS</emphasis>. You will be unable to use the checker shell script. Instead, you should use Windows Schedule Tasks to schedule the following command to run at the appropriate times:</para>
<para><literal>&apos;&apos;[dspace]&apos;&apos;/bin/dsrun.bat org.dspace.app.checker.ChecksumChecker -d2h -p</literal> (This command should appear on a single line).</para>.
<para><literal>&apos;&apos;[dspace]&apos;&apos;/bin/dsrun.bat org.dspace.app.checker.ChecksumChecker -d2h -p</literal> (This command should appear on a single line).</para>
</section>
<section remap="h3">
<title>Automated Checksum Checkers&apos; Results</title>
<para>Optionally, you may choose to receive automated emails listing the Checksum Checkers&apos; results. Schedule it to run <emphasis role="bold">after</emphasis> the Checksum Checker has completed its processing (otherwise the email may not contain all the results).</para>
<title>Daily Report Email Information Table</title>
<informaltable frame="all">
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
@@ -1100,8 +1316,7 @@ checker.retention.CHECKSUM_MATCH = 8w</screen>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Help</entry>
</row>
</tbody>
</tgroup>
</tbody></tgroup>
</informaltable>
<tip>
<para>You can also combine options (e.g. -m -c) for combined reports.</para>
@@ -1109,5 +1324,170 @@ checker.retention.CHECKSUM_MATCH = 8w</screen>
<para><emphasis role="bold">Cron</emphasis>. Follow the same steps above as you would running checker in cron. Change the time but match the regularity. Remember to schedule this **after** Checksum Checker has run.</para>
</section>
</section>
<section>
<title><anchor id="docbook-sys_admin-html-embargo" xreflabel="Embargo"/>Embargo</title>
<para>If you have implemented the Embargo feature, you will need to run it periodically to check for Items with expired embargoes and lift them.</para>
<table>
<title>Embargo Manager Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="40*"/><colspec colname="c2" colwidth="60*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry><emphasis><literal>[dspace]</literal></emphasis><literal>/bin/dspace embargo-lifter</literal></entry>
</row>
<row>
<entry>Java class:</entry>
<entry>org.dspace.embargo.EmbargoManager</entry>
</row>
<row>
<entry>Arguments short and (long) forms):</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-c</literal> or <literal>--check</literal></entry>
<entry>ONLY check the state of embargoed Items, do NOT lift any embargoes</entry>
</row>
<row>
<entry><literal>-i</literal> or <literal>--identifier</literal></entry>
<entry>Process ONLY this handle identifier(s), which must be an Item. Can be repeated.</entry>
</row>
<row>
<entry><literal>-l</literal> or <literal>--lift</literal></entry>
<entry>Only lift embargoes, do NOT check the state of any embargoed items.</entry>
</row>
<row>
<entry><literal>-n</literal> or <literal>--dryrun</literal></entry>
<entry>Do no change anything in the data model, print message instead.</entry>
</row>
<row>
<entry><literal>-v</literal> or <literal>--verbose</literal></entry>
<entry>Print a line describing the action taken for each embargoed item found.</entry>
</row>
<row>
<entry><literal>-q</literal> or <literal>--quiet</literal></entry>
<entry>No output except upon error.</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Display brief help screen.</entry>
</row>
</tbody></tgroup>
</table>
<para>You must run the Embargo Lifter task periodically to check for items with expired embargoes and lift them from being embargoed. For example, to check the status, at the CLI:</para>
<para><literal>[dspace]/bin/dspace embargo-lifter -c</literal></para>
<para>To lift the actual embargoes on those items that meet the time criteria, at the CLI:</para>
<para><literal>[dspace]/bin/dspace embargo-lifter -l</literal></para>
</section>
<section>
<title><anchor id="docbook-sys_admin.html-indexbrowse" xreflabel="Browse Index Creation"/>Browse Index Creation</title>
<para>To create all the various browse indexes that you define in the <link linkend="docbook-configure.html-browse-index">Configuration Section</link> (Chapter 5) there are a variety of options available to you. You can see these options below in the command table.</para>
<table>
<title>Browse Index Command Table</title>
<?dbhtml table-width="100%" ?>
<?dbfo table-width="100%"?>
<tgroup cols="2" align="left"><colspec colname="c1" colwidth="40*"/><colspec colname="c2" colwidth="60*"/><spanspec spanname="hspan" namest="c1" nameend="c2" align="center"/><tbody>
<row>
<entry>Command used:</entry>
<entry><emphasis><literal>[dspace]</literal></emphasis><literal>/bin/dspace index-init</literal></entry>
</row>
<row>
<entry>Java class:</entry>
<entry>org.dspace.browse.IndexBrowse</entry>
</row>
<row>
<entry>Arguments short and long forms):</entry>
<entry>Description</entry>
</row>
<row>
<entry><literal>-r</literal> or <literal>--rebuild</literal></entry>
<entry>Should we rebuild all the indexes, which removes old tables and creates new ones. For use with <literal>-f</literal>. Mutually exclusive with <literal>-d</literal></entry>
</row>
<row>
<entry><literal>-s</literal> or <literal>--start</literal></entry>
<entry><literal>[-s &lt;int&gt;] </literal>start from this index number and work upwards (mostly only useful for debugging). For use with <literal>-t</literal> and <literal>-f</literal></entry>
</row>
<row>
<entry><literal>-x</literal> or <literal>--execute</literal></entry>
<entry>Execute all the remove and create SQL against the database. For use with <literal>-t </literal>and <literal>-f</literal></entry>
</row>
<row>
<entry><literal>-i</literal> or <literal>--index</literal></entry>
<entry>Actually do the indexing. Mutually exclusive with <literal>-t</literal> and <literal>-f</literal>.</entry>
</row>
<row>
<entry><literal>-o</literal> or <literal>--out</literal></entry>
<entry><literal>[-o&lt;filename&gt;]</literal> write the remove and create SQL to the given file. For use with <literal>-t</literal> and <literal>-f</literal></entry>
</row>
<row>
<entry><literal>-p</literal> or <literal>--print</literal></entry>
<entry>Write the remove and create SQL to the stdout. For use with <literal>-t</literal> and <literal>-f</literal>.</entry>
</row>
<row>
<entry><literal>-t</literal> or <literal>--tables</literal></entry>
<entry>Create the tables only, do no attempt to index. Mutually exclusive with <literal>-f</literal> and <literal>-i</literal></entry>
</row>
<row>
<entry><literal>-f</literal> or <literal>--full</literal></entry>
<entry>Make the tables, and do the indexing. This forces <literal>-x</literal>. Mutually exclusive with <literal>-f</literal> and <literal>-i</literal>.</entry>
</row>
<row>
<entry><literal>-v</literal> or <literal>--verbose</literal></entry>
<entry>Print extra information to the stdout. If used in conjunction with <literal>-p</literal>, you cannot use the stdout to generate your database structure.</entry>
</row>
<row>
<entry><literal>-d</literal> or <literal>--delete</literal></entry>
<entry>Delete all the indexes, but do not create new ones. For use with <literal>-f</literal>. This is mutually exclusive with <literal>-r</literal>.</entry>
</row>
<row>
<entry><literal>-h</literal> or <literal>--help</literal></entry>
<entry>Show this help documentation. Overrides all other arguments.</entry>
</row>
</tbody></tgroup>
</table>
<section>
<title>Running the Indexing Programs</title>
<para><emphasis role="bold">Complete Index Regeneration</emphasis>. By running <literal>[dspace]/bin/dspace index-init</literal> you will completely regenerate your indexes, tearing down all old tables and reconstructing with the new cofiguration. Running this is the same as:</para>
<para><literal>[dspace]/bin/dsrun org.dspace.browse.IndexBrowse -f -r</literal></para>
<para><emphasis role="bold">Updating the Indexes</emphasis>. By running <literal>dspace/bin/dspace index-update</literal> you will reindex your full browse wihtout modifying the table structure. (This should be your default approach if indexing, for example, via a cron job periodically). Running this is the same as:</para>
<para><literal>[dspace]/bin/dsrun org.dspace.browse.IndexBrowse -i</literal></para>
<para><emphasis role="bold">Destroy and rebuild.</emphasis> You can destroy and rebuild the database, but do not do the indexing. Output the SQL to do this to the screen and a file, as well as executing it against the database, while being verbose. At the CLI screen:</para>
<para><literal>[dspace]/bin/dsrun org.dspace.browse.IndexBrowse -r -t -p -v -x -o myfile.sql</literal></para>
</section>
<section>
<title>Indexing Customization</title>
<para>DSpace provides robust browse indexing. It is possible to expand upon the default indexes delivered at the time of the installation. The System Administrator should review <link linkend="docbook-configure.html-browse-index-define">&quot;Defining the Indexes&quot; from the Chapter 5. Configuration</link> to become familiar with the property keys and the definitions used therein before attempting heavy customizations.</para>
<para>Through customization is is possible to:</para>
<itemizedlist>
<listitem><para>Add new browse indexes besides the four that are delivered upon installation. Examples:
<itemizedlist>
<listitem><para>Series</para></listitem>
<listitem><para>Specific subject fields (Library of Congress Subject Headings.<emphasis>(It is possible to create a browse index based on a controlled vocabulary or thesauris.)</emphasis></para></listitem>
<listitem><para>Other metadata schema fields</para></listitem>
</itemizedlist></para></listitem>
<listitem><para>Combine metadata fields into one browse</para></listitem>
<listitem><para>Combine different metadata schemas in one browse</para></listitem>
</itemizedlist>
<para><emphasis role="bold">Examples of new browse indexes that are possible.</emphasis> <emphasis>(The system administrator is reminded to read the section on Defining the Indexes in Chapter 5. Configuration.)</emphasis></para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Add a Series Browse</emphasis>. You want to add a new browse using a previously unused metadata element. </para>
<para><literal>webui.browse.index.6 = series:metadata:dc.relation.ispartofseries:text:single</literal></para>
<para>Note: the index # need to be adjusted to your browse stanza in the <literal>dspace.cfg</literal> file. Also, you will need to update your <literal>Messages.properties</literal> file. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Combine more than one metadata field into a browse.</emphasis> You may have other title fields used in your repository. You may only want one or two of them added, not all title fields. And/or you may want your series to file in there. </para>
<para><literal>webui.browse.index.3 = title:metadata:dc.title,dc:title.uniform,dc:relation.ispartofseries:title:full</literal></para>
</listitem>
<listitem>
<para><emphasis role="bold">Separate subject browse.</emphasis> You may want to have a separate subject browse limited to only one type of subject. </para>
<para><literal>webui.browse.index.7 = lcsubject.metdata:dc.subject.lcsh.text:single</literal></para>
</listitem>
</itemizedlist>
<para>As one can see, the choices are limited only by your metadata schema, the metadata, and your imagination.</para>
<tip>
<para>Remember to run <literal>index-init</literal> after adding any new defitions in the <literal>dspace.cfg</literal> to have the indexes created and the data indexed.</para>
</tip>
</section>
</section>
</chapter>