Homec4science
Diffusion invenio-infoscience (maint-0.99) Browse

R3600/modules/bibsword/doc/admin/bibsword-client-admin-guide.webdoc
dca5db9a0932maint-0.99

Last Change
Raw File

bibsword-client-admin-guide.webdoc
View Options

## -*- mode: html; coding: utf-8; -*-
## This file is part of Invenio.
## Copyright (C) 2010 CERN.
##
## Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
<!-- WebDoc-Page-Title: BibSword client Admin Guide -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/admin<lang:link/>">_(Admin Area)_</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->
<h2>Contents</h2>
<strong>1. <a href="#1">Overview</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.1. <a href="#1.1">Remote authentication</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.2. <a href="#1.2">Forwarding status</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1.3. <a href="#1.3">Forwarding options</a><br />
<strong>2. <a href="#2">BibSword client - Admin Web Interface</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.1. <a href="#2.1">Submission state table</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.2. <a href="#2.2">Refresh forwarded record status</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.3. <a href="#2.3">Setting up a record forwarding</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.4. <a href="#2.4">Forwarding process</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2.5. <a href="#2.4">Email acknowlegement</a><br />
<strong>3. <a href="#3">BibSword client - User Web Interface</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3.1. <a href="#3.1">The "Demo Export via SWORD action</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 3.2. <a href="#3.2">Adding the "Export via SWORD" action in an existing workflow</a><br />
<strong>4. <a href="#4">Configuring a new remote server</a></strong><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4.1. <a href="#4.1">The swrREMOTESERVER table</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4.2. <a href="#4.2">The metadata file type</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 4.3. <a href="#4.3">The link to the new remote server</a><br />
<strong>5. <a href="#5">References</a></strong><br />
<a name="1"></a><h2>1. Overview</h2>
<p>BibSword client enables you to forward a record from Invenio to any remote server that has an interface implementing the SWORD protocol. The aim of the BibSword client module is to simplify and to speed up the submission process of a digital report. Basically, the fulltext and the metadata are automatically taken from the record stored on Invenio. For more flexibility, they can be manually added and modified during the forwarding process.</p>
<a name="1.3"></a><h3>1.1 Remote authentication</h3>
<p>For reasons of conveniency, it is enoying to ask user already authencticated on Invenio to log in a remote server before forwarding a record. This problem is solved by using the "mediated deposit" function discribed by the SWORD protocol specification.<p>
<p>The mediated deposit function allows any user to forward a document in the name of the author. The solution was then to create a global user that is always used to connect to the remote server. This user submit the record "on behalf of" the real author of the file. So the user do not even need to have an account on the remote server.</p>
<p>Because of this function, users are allows to submit what they want as soon as they know the global user. To avoid users to do everything they want, the access of the BibSword client module is restricted to a group of user named "bibsword_curator". However, users can forward their own record through the WebSubmit workflow that already manage the record access right.</p>
<a name="1.3"></a><h3>1.2 Forwarding status</h3>
<p>When a record is forwarded to a remote SWORD server, it goes through several well-defined states:</p>
<ol><li>submitted: the record is waiting for approval</li>
<li>published: the record has been approved and is published</li>
<li>unknown: the record has been refused or has never been submitted</li></ol>
<p>For each states, an information is stored on the MARC file of the submitted record:</p>
<ul><li>submitted: an information field (by default the tag '595__a') is added. It contains informations about the time and the user having done the submission but also the remote id given by the SWORD server for the record.</li>
<li>published: the remote id is added to the MARC file as an additionnal record id (by default the tag '088_a').</li>
<li>unknown: the record has been refused by the remote server or a problem happened during the submission. In this case, the information field (by default the tag '595__a') and the additionnal record id field (by default the tag '088_a') are removed.</li></ul>
<a name="1.4"></a><h3>1.3 Forwarding options</h3>
<p>By default, BibSword client send the fulltext and the metadata stored on Invenio.</p>
<p>It also allows to select the fulltext to forward and even to upload new fulltext. If a new fulltext is uploaded, it is stored in the Invenio record fulltext as a "Pushed_via_Sword" file.
<a name="2"></a><h2>2. BibSword client : Admin Web Interface</h2>
<p>To access the Admin Web interface, please go to <a href="<CFG_SITE_URL>/bibsword"> BibSword Client Admin Interface</a>. Note that you first have to be logged with a user of the group "bibSword_curator".</p>
<
<p>This interface allows to:
<ul><li>Consult information about the forwarded records</li>
<li>Refresh the status of the forwarded records on the remote server</li>
<li>Forward any record to any available SWORD remote server.</li></ul>
<a name="2.1"></a><h3>2.1 Submission state</h3>
<p>The main BibSword Admin Interface shows a table containing information about every forwarded record.
<h4>Submission state table fields</h4>
<table border="1" width="600px">
<thead>
<tr> <th>Field</th> <th>Definition</th> <th>Link</th> </tr>
</thead>
<tbody>
<tr> <td>Remote server</td> <td>id and name of the remote server where the record has been submitted</td> <td>Go to the information table where to find credential and link to the remote server</td> </tr>
<tr> <td>Submitter</td> <td>username and email of the user that made the submission</td> <td>None</td> </tr>
<tr> <td>Report number</td> <td>database id and report number of the forwarded record</td> <td>Go to the record information page on Invenio</td> </tr>
<tr> <td>Remote id</td> <td>id given by the remote server</td> <td>Go to the record page on the remote server</td> </tr>
<tr> <td>Status</td> <td>the status of the forwarded record (submitted, published or removed)</td> <td>None</td> </tr>
<tr> <td>Date</td> <td>Date of each state changes of the submitted record</td> <td>None</td> </tr>
<tr> <td>Links</td> <td>Link to fulltext, metadata and status information URL</td> <td>Media: consult, modify, add and delete fulltext<br />Metadata: consult, modify, add and delete metadata<br />Status: Get an XML atom entry containing the status of the record</td> </tr>
</tbody>
</table>
<p>The record are display in order of state change date. The moste recent change first and the less recent change last. To consult a none displayed record, navigate between pages using the "Prev" - "Next" and the "First" - "Last" buttons.<br /> You also can select another amount of displayed record on the same page by changing the displayed record number.</p>
<a name="2.2"></a><h3>2.2 Refresh forwarded record status</h3>
<p>Each time the submission state table is loaded, the BibSword client module check each displayed record in status "submitted" to know if their status has been changed to "published" or to "removed".<br />
To minimize the table loading time, the default amount of displayed record is set to 10.
However it is possiblie to select another number of displayed field. (5 - 10 - 25 - 50 - all)</p>
<p>In some unusual cases, a "published" record can be removed from the SWORD remote server. In this case, the status of the submitted record is not automatically updated. To update "published" record, clic the "Refresh all" button. It will check the status of every forwarded record in each remote server.</p>
<a name="2.3"></a><h3>2.3 Setting up a record forwarding</h3>
<p>The forwarding of record from the admin interface is done through four different formular. Each of them has a precise purpose and is generated dynamically according to the record and the remote server informations.</p>
<ol> <li>Select the record and the remote server</li>
<li>Select the remote server collection</li>
<li>Select the remote server categories</li>
<li>Check, add, modify and/or delete media and metadate to forward</li> </ol>
<p>To forward a record, clic the "New Submission" button from the BibSword Admin Interface.<br />
Alternatively, you can access to the SWORD forward interface from any record information page by clicking the "Push to <i>Remote Server</i>" located on the toolbar bellow the record information box. Note that on this case, you are directly redirect to the step two of the forward process.</p>
<b>Step 1/4: Select record and remote server</b>
<p>Fields of the formular are the following:</p>
<ul> <li><b>Report number:</b> specify the record to forward, enter its report number (e.g: <i>PUPT-1665</i>)</li>
<li><b>Remote server:</b> specify the remote server where to forward the record, select it in the dropdown list</li> </ul>
<p>Both fields are mandatory. If you forgot one of them or if you give an unexisting report number, an error message will be displayed and you will be invited to give all information correctly.</p>
<p>You can abort the submission by pushing the "cancel" button and be redirected to the BibSword Admin Interface.</p>
<b>Step 2/4: Select the remote server collection</b>
<p>The second step displays information about the selected remote server as well as the implemented version of sword and the maximum size of file to forward. At this point, it is possible to modify the remote server and the record by pushing "Modify server".</p>
<p>The pupose of this step is to select the remote collection. The collection contains the URL where to sent information to the remote server.</p>
<p>Fields of the formular are the following:</p>
<ul> <li><b>Remote collection:</b> specify the collection in the dropdown list.</li> </ul>
<p>Most of the remote server has a collection called "test". This colleciton is very usefull to check the correct function of the implementation of a remote server. When a record is sent to the "test" collection of a remote server, the SWORD remote interface will act exactly the same as with a normal forward but without to save the record.</p>
<p>You can abort the submission by pushing the "Cancel" button and be redirected to the BibSword Admin Interface.</p>
<b>Step 3/4: Select Remote Categories</b>
<p>The third step display information about the Remote Server as well as information concerning the selected collection. At this point, it is possible to modify the remote server and the record by pushing "Modify server". It is also possible to modify the selected Remote Collection by pushing "Modify collection".</p>
<p>This step allows to select remote categories. Categories are used for two purposes:
<ul> <li>Specify the exact place where the record will be stored in the remote server</li>
<li>Specify all the topics related to the record for an easiest localisation of the record</li> </ul>
<p>Fields of the formular are the following:</p>
<ul><li><b>Mandated category:</b> Select the specific topic of the record for the collection from the dropdown list</li>
<li><b>Optionnal categories:</b> Select all categories related to the record from the multiple choice list (CTRL+CLICK to select many)</li></ul>
<p>If you forget to select a mandatory category, a message will be display and you will be invited to give a mandatory category.</p>
<p>You can abort the submission by pushing the "Cancel" button and be redirected to the BibSword Admin Interface.</p>
<b>Step 4/4: Select fulltext and check metadata</b>
<p>The last step contains many boxes, one for each following pupose:</p>
<ul> <li><b>Submitter:</b> Shows the remote server, the collection and the categories you have selected in the step 1 to 3. You can modify it by pushing the button "Modify destination"</li>
<li><b>Submitter:</b> Shows the username and the email address used for the forward. Once the record is accespted, an email will be sent back to this email address.</li>
<li><b>Media:</b> Displays each file of the fulltext as a checkbox field. The files are organized by categories as they where found on Invenio. The files from the "Main" category are selected by default. The user can choose the file he wants to forward and also decide to add a file by uploading it directly in this function. An uploaded file will be stored on Invenio in the "Pushed_via_SWORD" category.</li>
<li><b>Metadata:</b> Display each metadata found in the MARC file of the record. The submitter can modify them as he want. Be carefull, changing a metadata before forwarding a record to a SWORD Remote Server will not change it on Invenio. The result of modifing metadata will then be that those data will not be the same on Invenio and on the Remote Server.</li> </ul>
<p>Mandatory field are display with a * after the field label. Il one mandatory field is missing or not well formed, an error message specifying the wrong field will be display and you will be invited to enter a correct value.</p>
<p>You can abort the submission by pushing the "Cancel" button and be redirected to the BibSword Admin Interface.</p>
<a name="2.4"></a><h3>2.4 Forwarding process</h3>
<p>Once a record is submitted to a Remote Server, many action are launched:</p>
<ul><li><b>Data integrity:</b> Before sending anything, the BibSword Client module check if the record has already been submitted. If it is the case, the action will be aborted and an error message will be return to the user.</li>
<li><b>Media deposit:</b> The media is sent to the Remote Collection URL. If many files have been selected, they are set in a compressed zip archiv. If the action failed for any reason such as bad credential, no response or corrupted media, it will be aborted and an error message will be send back to the user.</li>
<li><b>Response parsing:</b> The response of the media deposit is a XML Atom Element file. This file contains the URL of the media on the Remote Server. The BibSword client module parse this file to retreive the URL and send it to the next step.</li>
<li><b>Metadata submission:</b>Before submitting the metadata, they are formatted according to the informations given in the last formular. If any error happens during the metadata deposit process, an error message is sent back to the end user.</li>
<li><b>Forward acknowlegment:</b> Enventually, when the metadata have been correctly submitted to the Remote Server, a acknowlegment XML Atom Entry is sent back containing the URL to the media, the metadata and the status of the forwarded record. Those inforations allows the user to consult, modify and delete the submitted record</li> </ul>
<a name="2.5"></a><h3>2.5 Email acknowlegment</h3>
<p>Once a record has been submitted, it is not directly published on the remote server. It needs to be accepted by the remote mandator. To informe the user of the publication of the record, the remote server sent him an Email containing the link to the record and the password to be able to do any modification. This email is also sent to the SWORD Invenio user.</p>
<a name="3"></a><h2>3. BibSword client : User Web Interface</h2>
Users are allows to forward their document to a SWORD remote server using the BibSword client module. For security and integrity reasons, this action can be reach by users only via the WebSubmit module. This module define different workflow for the submission of report. The idea hier is to add the "Forward from Invenio to any remote server" function in some existing workflow. These workflow already implements the control of credential. So it is easy ensure that an user will not be able to forward a report he is not autorized to manage.</p>
<a name="3.1"></a><h3>3.1 The "Demo Export via SWORD" Action</h3>
<a name="3.2"></a><h3>3.2 Adding the an "Export via SWORD" in an existing workflow</h3>
<a name="4"></a><h2>4. Configuring a new remote server</h2>
<p>To add a new remote server, following actions has to be done:</p>
<ul><li>Inserting remote server information is the swrREMOTESERVER table</li>
<li>Setting up the type of metadata file</li>
<li>Adding a link button in the record information page</li></ul>
<a name="4.1"></a><h3>3.1 The swrREMOTESERVER table</h3>
<p>The swrREMOTESERVER table contains credential and link information about any SWORD remote server.</p>
<h4>srwREMOTESERVER table fields</h4>
<table border="1" width="600px">
<thead>
<tr> <th>Field</th> <th>Definition</th> <th>Type</th> </tr>
</thead>
<tbody>
<tr> <td>id</td> <td>unique identification key of the table</td> <td> int(15) unique primary_key</td> </tr>
<tr> <td>name</td> <td>name of the remote server (e.g.: <i>arXiv</i>)</td> <td>varchar(50) unique</td> </tr>
<tr> <td>host</td> <td>URL where to send the authentication request (e.g.: <i>arXiv.org</i>)</td> <td>varchar(50) unique</td> </tr>
<tr> <td>username</td> <td>username of the global user allows to connect to the SWORD remote interface</td> <td>varchar(50)</td> </tr>
<tr> <td>password</td> <td>password of the global user allows to connect to the SWORD remote interface</td> <td>varchar(50)</td> </tr>
<tr> <td>email</td> <td>email address where the remote server will send the acknowlegment</td> <td>varchar(50)</td> </tr>
<tr> <td>realm</td> <td>name of the space where to authenticate on remote host (e.g.: <i>SWORD at arXiv</i>)</td> <td>varchar(50)</td> </tr>
<tr> <td>url_base_record</td><td>base URL where the record are stored (usually followed by the remote record id)</td><td>varchar(50) unique</td></tr>
<tr> <td>url_servicedocument</td> <td>URL where to GET the remote servicedocument</td> <td>varchar(50)</td> </tr>
<tr> <td>xml_servicedocument</td> <td>Full servicedocument XML file</td> <td>logblog</td> </tr>
<tr> <td>last_update</td><td>Timestamp of the last GET on the servicedocument. If > than 1 hour, the servicedocument is reset from the remote server. That is used to speed up the process.</td> <td> varchar(50) unique</td> </tr>
</tbody>
</table>
<a name="4.2"></a><h3>3.2 The metadata file type</h3>
<a name="4.3"></a><h3>3.3 The link to a new remote server</h3>
<a name="5"></a><h2>5. References</h2>
c4science · Help