Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:user:the_depositor [2014/10/29 11:27] (current)
Line 1: Line 1:
 +====== The Depositor ======
 +
 +<TABAREA tabs="​Greenstone3,​Greenstone2">​
 +<TAB>
 +The depositor is a web interface for adding new documents, along with metadata, to existing collections. It is specifically aimed to mimic the structured submission workflow of a institutional repository. The Depositor for Greenstone3 is still in development. ​
 +</​TAB>​
 +<TAB>
 +<!-- id:d002 --> The depositor is a web interface for adding new documents, along with metadata, to existing collections. Derived from the [[#​the_collector|Collector]],​ it is specifically aimed to mimic the structured submission workflow of a institutional repository. As such there are several requirements for using the Depositor in your collection:
 +
 +  * <!-- id:d004 -->You must have already created the collection via the [[en:​beginner:​building_collections#​Greenstone_librarian_interface|Librarian'​s Interface]] or [[en:​user_advanced:​command_line_building|command line scripts]]. The depositor is used for adding new material to an existing collection, not creating a new collection or configuring one. The collection should be built at least once before using the Depositor for it, even if it has no content yet.
 +  * <!-- id:d003 -->The collection should use Lucene as the indexer. Lucene provides incremental rebuilding ability - where just the newly uploaded document is added and indexed in the collection. MG or MGPP can be used, but each time a document is added, the full collection must be rebuilt, so the deposit part of the submission will be much slower, particularly as the collection becomes large. If the user will be only depositing and not rebuilding each time, then the choice of indexer is not important.
 +  * <!-- id:d005 -->You must be serving your collection using Apache or similar web-server (Greenstone'​s built-in ''​local library''​ on Windows is **not** supported)
 +
 +
 +===== Enable the Depositor =====
 +
 +<!-- id:d008 -->To enable the Depositor tool modify ''​main.cfg''​ (in the ''​GSDLHOME/​etc''​ directory): change<​code>​depositor disabled</​code>​to<​code>​depositor enabled</​code>​
 +
 +<!-- id:d009 -->​Note: ​
 +  * <!-- id:d010 -->You might need to change file permissions for the ''​GSDLHOME/​tmp'',​ ''​GSDLHOME/​collect'',​ and ''​GSDLHOME/​collect/​your_accessable_collection''​ directories so as to allow the web-server to write to them
 +  * <!-- id:d011 -->To modify a collection, a user needs to be in a group that has permission. The '''​all-collections-editor'''​ user group (or '''​colbuilder'''​ for Greenstone version 2.80 and earlier) has permission to modify all collections. The '''​xxx-collection-editor'''​ has permission to modify the xxx collection. Note that the ''​admin''​ user, created when installing Greenstone, is in the '''​all-collections-editor'''​ group by default.
 +  * <!-- id:d012 -->​Remember,​ the Depositor only works with the Web server, not the local server
 +
 +===== Use the Depositor =====
 +
 +  - <!-- id:d014 -->Go to the Greenstone'​s home page and click the "The Depositor"​ button.
 +  - <!-- id:d015 -->Sign in to the page
 +  - <!-- id:d016 -->​Select a collection from the collection list
 +  - <!-- id:d017 -->Fill in the metadata fields
 +  - <!-- id:d018 -->Click the "​Select File" button ​
 +  - <!-- id:d019 -->​Select the file you want to deposit, then click the "​Confirmation"​ button
 +  - <!-- id:d020 -->Click the "​Deposit Item" button and wait for the process being finished
 +  - <!-- id:d021 -->Try the newly built collection
 +
 +<!-- id:d022 -->​Notes:​
 +  * <!-- id:d023 -->The Depositor uses the Dublin Core metadata set by default. So if the target collection doesn'​t use DC, it is possible that the new added document(s) will not show up when previewing the collection. For example, when the classifiers are built with other metadata sets. You will need to either configure the Depositor to use the same metadata fields as the other documents in your collection, or extend the classifier and format configurations to include Dublin Core metadata fields
 +  * <!-- id:d024 -->If you want to upload more than one file at a time, zip them first. Don't forget to include ZipPlugin in your collection'​s ''​config.cfg''​
 +  * <!-- id:d025 -->You will see "​Collection built successfully"​ message or error messages if something goes wrong
 +
 +===== Configure the Depositor =====
 +
 +The default set up for the depositor is as described [[#​use_the_depositor|above]]. The user selects a collection, signs in, adds metadata (Dublin Core Title, Creator, Description),​ selects a file, confirms selection, deposits the item and the collection is rebuilt.
 +This workflow can be changed to suit each collection.
 +
 +The depositor workflow is defined in the **deposit.dm** macro file in the main greenstone macros folder.
 +Editing this file will change the workflow for **all** collections. To change it for just one collection, copy **deposit.dm** into the collection'​s macros folder (greenstone2/​collect/​collname/​macros),​ and edit it there. Alternatively,​ you can add the redefined macros into the collection'​s extra.dm file. This can be done in GLI by adding macros into the Format->​Collection Specific Macros pane. 
 +You'll need to start by adding the line <​code>​package depositor</​code>​ Put any redefined macros after that. 
 +
 +==== Deposit only ====
 +
 +In some cases, you may want users to be able to deposit items but not trigger a collection rebuild. Perhaps the items and metadata need monitoring or checking by the librarian before being added to the collection.
 +
 +<!-- id:d028 -->To make the depositor deposit the item in the collection but not import/​build it, edit ''​deposit.dm''​ and change<​code>​_laststep_ {bild}</​code>​to<​code>​_laststep_ {depositonly}</​code>​
 +
 +Note, to do this for a single collection, you can add
 +<​code>​
 +package depositor
 +
 +_laststep_ {depositonly}
 +</​code>​
 +
 +to the Collection Specific Macros pane in the collection in GLI.
 +==== Configure the Metadata Fields ====
 +
 +<!-- id:d030 -->By default, the Depositor uses three fields (Title, Creator and Description) from the Dublin Core metadata set, but you can easily customize this in the GLI Format panel (from Greenstone version 2.81)
 +
 +  - <!-- id:d031 -->​Launch GLI, open the collection you want to customize. Go to the Format Panel, click the "​Depositor Metadata"​ section in the left section, a list of available metadata fields will appear in the right section.
 +  - <!-- id:d032 -->​Select fields that you want to be used in the Depositor. A drop-down list will appear right after the selected element, which is used to specify the text input type for that element in the web page: "​text"​ will display a single line text input whereas "​textarea"​ will display a multi-line input area. Hover the mouse over an element will display a tool-tip describing that element.
 +    * <!-- id:d033 -->It is recommended to select metadata fields that have been used to build classifiers,​ so that the newly added items can show up when previewing the collection.
 +    * <!-- id:d034 -->​Please note that at least one metadata element must be selected. If there is only one element left selected in the list, de-select the element will fail and pop up a warning message.
 +  - Save the collection. Note, if GLI doesn'​t save the changes to depositor metadata, then try closing the collection in GLI to force a rewrite of the collection config file.
 +
 +GLI writes out a macro into the collect.cfg file which lists all the metadata fields that should be used. The default list is:
 +<​code>​
 +collectionmeta ​ depositormetadata [l=en] "​{\"​name\":​\"​dc.Title\",​\"​label\":​\"​Title\",​\"​tooltip\":​\"​dc.Title:​ A name given to the resource.\",​\"​type\":​\"​text\"​}, ​
 +{\"​name\":​\"​dc.Creator\",​\"​label\":​\"​Creator\",​\"​tooltip\":​\"​dc.Creator:​ An entity primarily responsible for making the content of the resource.\",​\"​type\":​\"​text\"​},​
 +{\"​name\":​\"​dc.Description\",​\"​label\":​\"​Description\",​\"​tooltip\":​\"​dc.Description:​ An account of the content of the resource.\",​\"​type\":​\"​text\"​}"​
 +</​code>​
 +
 +You can edit this by hand if you like, but its probably easier to let GLI do it for you. For each item, the '​name'​ is the metadata name, and '​label'​ is what gets displayed to the user on the metadata page.
 +
 +=== Multiple metadata values or change the order ===
 +
 +If you want to have the user add more than one value for a metadata element, for example, multiple Subjects, or if you want to change the order of the fields, you'll have to edit the depositormetadata list by hand. You can add multiple entries for any of the metadata fields and change the order to suit the collection.
 +
 +Because GLI does not offer this functionality,​ if you edit the collect.cfg and then reopen in GLI, your changes will be deleted. If you are not using GLI, then feel free to edit the depositormetadata list.
 +
 +If you do want to open the collection in GLI, then you will need to define the custommetadataconf macro instead of depositormetadata. (Note, this available from 2.87 or nightly releases after 23 October 2014)
 +
 +You can do this in two ways: as a collectionmacro in collect.cfg,​ or in the Collection Specific Macros area in GLI (in extra.dm).
 +
 +  * In the collect.cfg file, add by hand (remember to close in GLI before editing)
 +<​code>​
 +collectionmacro depositor:​custommetadataconf "var DepositorMDFields = new Array({\"​name\":​\"​dc.Title\",​\"​label\":​\"​Title\",​\"​tooltip\":​\"​dc.Title:​ A name given to the resource.\",​\"​type\":​\"​text\"​});"​
 +</​code>​
 +
 +  * In Collection Specific Macros:
 +<​code>​
 +_custommetadataconf_ {var DepositorMDFields = new Array(\{\"​name\":​\"​dc.Title\",​\"​label\":​\"​Title\",​\"​tooltip\":​\"​dc.Title:​ A name given to the resource.\",​\"​type\":​\"​text\"​\});​}
 +</​code>​
 +
 +The content is basically the same for the two cases. Note, in the second case, internal '​{'​ and '​}'​ are escaped: \{, \}.
 +
 +The collectionmacro in collect.cfg has priority over the macro in extra.dm, if they were both defined.
 +
 +
 +
 +
 +
 +
 +==== Add a deposit link to a collection ====
 +(Note this is  only available for 2.87 or nightly releases after 20 October 2014.)
 +
 +By default, the depositor link is available from the home page, and the user needs to select a collection and log in. They can access the depositor page again from within the depositor by clicking the ''​The depositor''​ link at the top right of the page. However, they'​ll need to select a collection again, and log in again.
 +
 +To add a link in a collection for depositing an item, that bypasses the collection selection page, do the following.
 + 
 +In the Collection Specific Macros pane in GLI, add:
 +<​code>​
 +package Global
 +
 +_optdepositlink_ {_depositlink_}
 +
 +</​code>​
 +This will add a DEPOSIT button in the row of HOME, HELP, PREFERENCES button. It will be available for every page in the collection.
 +
 +To add a link just on one page, add some text and link to **__httppagedepositorcurrentcollection_**
 +You'll need to add this into the **_content_** macro of the relevant page.
 +
 +For example, to add a link on the about page, you might add the following to the Collection Specific Macros:
 +
 +<​code>​
 +package about
 +
 +_content_ {
 +_optnavigationbar_
 +
 +<div class="​document">​
 +_If_("​_cgiargqt_"​ ne "​1",​
 +     ​_If_("​_cgiargu_"​ ne "​1",​_aboutqueryform_)
 +    )
 +    ​
 +<div style="​text-align:​ right;"><​a href="​_httppagedepositorcurrentcollection_">​Deposit an item into the collection</​a>​
 +</​div> ​      
 +_If_(_Global:​collectionextra_,<​p>​_textabout_)
 +_textsubcollections_
 +
 +<div class="​section">​
 +<​h3>​_help:​textsimplehelpheading_</​h3>​
 +_help:​simplehelp_
 +</​div>​
 +
 +</​div>​
 +}
 +</​code>​
 +
 +This will add a link **Deposit an item into the collection** at the right of the page underneath the quick search form. Note that this is the default **_content_** macro from the about page, copied into the collection, with one **<​div>​** added containing the link.
 +
 +=== Metadata Field Caching ===
 +
 +When you are using the Despositor in a local collection manner, you will remain logged in between deposits, and the system will cache the metadata values. This means that next time you return to the "​Specify Metadata"​ page, the previously entered values will be filled in. This may be useful if you are entering a lot of related documents that share metadata. If it is not useful for your situation you can turn off this behaviour by adding the following to the collection specific macros:
 +<​code>​
 +package depositor
 +_cacheoption_{0}
 +</​code>​
 +
 +Note that the ''​package depositor''​ line is not needed if it is already present due to other modifications. Just make sure that all the depositor statements are together without other package declarations in between them.
 +
 +=== Removing the depositor link on the home page ===
 +
 +If you have a deposit button in a collection, then you may want to remove the main depositor link from the home page. To do this, edit //​greenstone2/​macros/​home.dm//,​ look for the **_content_** macrco, and remove the line **_textgodepositor_**.
 +
 +==== Single page Submission ====
 +
 +You can combine the metadata field entry and file selection into a single page if you like.
 +
 +In the Collection Specific Macros section in GLI (or in the collection'​s extra.dm), to the **package depositor** section, add macros like the following:
 +
 +<​code>​
 +_numsteps_ {1}
 +</​code>​
 +
 +This will make it only have one page of data entry. After this page, it will go to deposit item or deposit and build, depending on the other settings.
 +
 +<​code>​
 +_textstep1_ {Specify File and Metadata}
 +_textstep1description_ {Please enter the metadata values, select a file, then click _textbild_ }
 +</​code>​
 +
 +These define the heading and description at the top of the page, as the default ones don't fit this scenario so well.
 +
 +<​code>​
 +_step1content_ {
 +
 +<form name="​depositorform"​ method=post action="​_gwcgi_"​ enctype="​multipart/​form-data">​
 +
 +<input type=hidden name="​e"​ value="​_decodedcompressedoptionsAttrsafe_">​
 +<input type=hidden name="​p"​ value="​_cgiargpAttrsafe_">​
 +
 +
 +<​center>​
 +<table width=_pagewidth_>​
 +<​tr><​td>​
 +<div class="​divbar">&​nbsp;</​div>​
 +<​center>​
 +<​h2>​_textstep1_</​h2>​
 +<​p>​_textstep1description_</​p> ​
 +</​center>​
 +<div class="​divbar">&​nbsp;</​div>​
 +
 +<​!--input goes here-->
 +<​!--dynamic load the metadata elements as configured in the collection'​s collect.cfg-->​
 +<​p><​table><​tbody id="​formcontainer"></​tbody></​table>​
 +
 +<div class="​divbar">&​nbsp;</​div>​
 +
 +<​p>​_textfilename_:​ <input type=file name=di1userfileinfo value="​_userfile_"/></​p>​
 +<div class="​divbar">&​nbsp;</​div>​
 +
 +</​td></​tr>​
 +
 +
 +<​tr><​td>​_depositorbar_</​td></​tr>​
 +</​table></​center>​
 +
 +</​form>​
 +
 +}
 +</​code>​
 +
 +This is the _step1content_ macro copied from greenstone2/​macros/​deposit.dm,​ with a few changes. It is printing out _textstep1description_ instead of _textdepositorblurb_ underneath the heading - we have defined the former above.
 +
 +And then we have added the file input element so that the user can select the file on this page.
 +
 +In a Deposit-Only situation, the user gets a Confirmation page, listing the file name and file size. You can change this by redefining the _depositonlycontent_ macro. For example:
 +
 +<​code>​
 +_depositonlycontent_ {
 +<​center>​
 +<​em>​Thanks for your submission. A librarian will process it in due course.</​em>​
 +<table width=_pagewidth_>​
 +<​tr><​td>​
 +<div class="​divbar">&​nbsp;</​div>​
 +<​center><​h2>​Submitted:</​h2></​center>​
 +<div class="​divbar">&​nbsp;</​div>​
 +<​p>​_textfilename_:​ _di1userfile_ </p>
 +<​p>​_textfilesize_:​ _di1userfilesize_ </​p> ​
 +<div class="​divbar">&​nbsp;</​div>​
 +</​td></​tr>​
 +<​tr><​td></​td></​tr>​
 +</​table>​
 +</​center>​
 +}
 +
 +</​code>​
 +
 +==== DSpace-inspired Depositor ====
 +
 +Greenstone comes with a version of the depositor that behaves like the DSpace repository. It provides a multi-page submission process.
 +  - Describe 1: Add Author, Title, Series/​Report No. Identifiers,​ Type, Language
 +  - Describe 2: Add Subject Keywords, Abstract, Sponsors, Description
 +  - Upload 1: Select a file to upload
 +  - Upload 2: Check the details of uploaded file
 +  - Verfiy: Check all the metadata, with options to go back and change it
 +  - License: accept the DSpace distribution license for the document
 +  - Deposit Item: add the item to the collection and rebuild the indexes.
 +
 +  * To use this for all collections, ​ edit etc/​main.cfg to mention **depositdspace.dm** in place of where it mentions **deposit.dm**. Don't forget to enable the depositor in etc/​main.cfg.
 +  * To use it for just one collection, copy depositdspace.dm from greenstone2/​macros into the collection'​s macro folder, and rename it deposit.dm. ​
 +
 +  *The Dspace Depositor works with Dublin Core (dc) metadata and some extra fields defined in the Dspace inspired metadata set "​ds"​. If you'll be using GLI to work with a collection that uses the DSpace depositor, then you will need to add the DSpace metadata set into it. On the Enrich panel, click "​Manage Metadata Sets", click "​Add",​ and choose "​DSpace"​ from the list. Otherwise when GLI opens the collection and sees metadata from this unknown set, it will ask you which known elements you want to merge the metadata into.
 +
 +
 +
 +
 +===== Additional Resources =====
 +
 +  *The [[http://​wiki.greenstone.org/​gsdoc/​tutorial/​gs2-current/​en/​depositor.htm|Depositor tutorial]] covers basic depositor use such as setting up users, adding documents to a collection, and batch addition of documents using ZIP files.
 +
 +  *Diego has provided a [[http://​wiki.greenstone.org/​wiki/​images/​b/​bb/​Depositor.pdf|presentation]] (in PDF format) from 2011, demonstrating how to use The Depositor.
 +
 +</​TAB></​TABAREA>​