<p>Figure 6 also shows the possibility to select among various
categories prior to jumping into one of the available actions. These
categories usually don't have a direct impact on the chosen
workflow. Think of them simply as a simple WebSubmit element place on
the first page, that is common to all the actions of your submission
(indeed you could set up your submissions to have such categories
inside your submission actions pages, but that would require
additional work).</p>
<p>Last, but not least, a submission is usually referred to by a short
name (at most 5 letters), reused in many places in the WebSubmit admin
interface.</p>
To summarize:
<ul>
<li>A <b>submission</b> is made of different actions</li>
<li>An <b>action</b> is a workflow made of pages, checks and a flow of functions.</li>
<li>A <b>page</b> contains several WebSubmit elements, usually input elements with some label.</li>
<li>A <b>WebSubmit element</b> is a control on the interface to input or display values.</li>
<li>Javacript <b>checks</b> can be attached to WebSubmit elements, in order to validate the input data before going to a futher step of the submission.</li>
<li>A <b>function</b> performs some post-processing operations, usually
on data collected thanks to WebSubmit elements. Functions can have side-effects and outputs</li>
<li>Functions are organized in <b>steps</b>, blocks of functions</li>
</ul>
<p style="font-style: italic;">Another concept remains to be explained, but this functionality tends to disappear from submissions, and might be deprecated at some point. We provide the explanation about it below only for completeness, but it is strongly discouraged to go that way:<br/>
<blockquote>
It is possible to group actions in <b>sets</b>: an action set is a succession of actions which should be done in a given order when a user starts.<br/>
For example the submission of a document can be composed of two actions: Submission of Bibliographic Information (SBI) and Fulltext Transfer (FTT) which should be done one after the other.<br/>
When the user starts the submission, we want the submission to get him first in SBI and when he finishes SBI to carry him to FTT. SBI and FTT are in this case in the same action set. They will both have a level of 1 ("level" is a bad name, it should be "action set number"), SBI will have a score of 1, and FTT a score of 2 (which means it will be started after SBI). If you set the stpage of FTT to 2, the user will be directly carried to the 2nd page of the FTT web form. This value is usually set to 1.<br/>
The endtxt field contains the text which will be displayed to the user at the end of the first action (here it could be "you now have to transfer your files")<br/>
A single action like "Modify Bibliographic Information" should have the 3 columns to 0,0 and 1.
</blockquote>
</p>
<h3><a name="behindthescenes">1.2 Behind the scenes</a></h3>
<p>This section highlights a few key behaviours of WebSubmit which are
particularly important to understand when designing a submission.</p>
<p>When a user starts a new submission, a working directory is created
on disk in order to store all the collected values. This working
directory is usually called the "<code>curdir</code>". It is located
in a subdirectory
of <code>/opt/invenio/var/data/submit/storage/</code><small><em>{action
<p>To circumvent this limitation (as well as the impossibility to
delete files), you might combine this technique with one of the
techniques described below (For eg: with
the <code>Move_Revised_Files_To_Storage</code> function detailed in
the <a href="#2.2revise">Revising/deleting files</a> section of
the <a href="#2.2">File Input element + Move_Files_To_Storage
function</a> technique) </p>
<a name="5.2"></a><h3>5.2 File Input element + Move_Files_To_Storage function</h3>
<p>This way of doing is similar to the <a href="#2.1">technique
described above</a>. The main difference is that it leaves the job of
actually uploading/revisings the file(s) to a WebSubmit functions,
instead of the FFT in the uploaded MARCXML.</p>
<b>Limitations:</b>
<ul>
<li>revision of files requires
well-defined <code>doctype</code>. The consequence is that you can
have only one file per doctype (1 "Main", 1 "Additionnal",
etc.)</li>
<li>cannot easily delete files</li>
<li>does not support setting some additional file attributes (description, name, etc.)</li>
<li>uploaded doctypes must inherit the names of their <code>File Input</code> elements. For eg. "DEMO_FILE", instead of "Main", "Additional", "Figure", etc.</li>
</ul>
<p><b>1-4)</b> Add a file input field to your submission page as
describe in <a href="#2.1">previous technique</a>.</p>
<p>As before, the file is uploaded to the server once the user ends
the submission, but it is not attached to the created record. The
solution is to rely on the "<code>Move_Files_To_Storage</code>" function:</p>
<p><b>5)</b> Add the "<code>Move_Files_To_Storage</code>" function to your submission
functions. It is suggested to insert it after the function
"Insert_Record".</p>
<p><b>6)</b> Configure the <code>Move_Files_To_Storage</code>
function. The key parameter is <code>paths_and_suffixes</code>, which
must contain your <code>File Input</code> element names, and possibly
map to some suffixes to be added to the corresponding uploaded
files.<br/> For example, add <code>{'DEMO_FILE':'',
'DEMO_FILE2':'_additional'}</code> to have the files uploaded with
DEMO_FILE and DEMO_FILE2 elements attached to the record (with the
DEMO_FILE2 filename suffixed with
"_additional"). The <code>paths_and_restriction</code> works similarly
to set the files restrictions.
</p>
<p>Each file is simply attached to the record, with its document type
(<code>doctype</code>) being the name of your input file element (for e.g. file
uploaded with the "<code>DEMO_FILE</code>" element is attached with document type
"<code>DEMO_FILE</code>"). The filenames are kept.</p>
<p>The "<code>Move_Revised_Files_To_Storage</code>" must be added to your modification
workflow ("MBI"). It will use the file uploaded with your "<code>DEMO_FILE</code>"
input element to revise the file with <code>doctype</code> "<code>DEMO_FILE</code>", the file
from "<code>DEMO_FILE2</code>" input element to revise file with <code>doctype</code>
"<code>DEMO_FILE2</code>", etc.</p>
<p><b>1)</b> Go to your modification workflow (MBI), and add
<code>Move_Revised_Files_To_Storage</code> to your submission
functions (usually after the "<code>Insert_Modify_Record</code>").</p>
<p><b>2)</b> Set up the <code>elementNameToDoctype</code> parameter of
this function so it maps your <code>File Input</code> field name to
the doctype to revise. For eg: "<code>DEMO_FILE=Main</code>" so that
file uploaded using the <code>DEMO_FILE</code> input field will be
used to replace the file with <code>doctype</code> "Main". This makes
the assumption that you indeed previously uploaded (for eg. with an
FFT during an SBI step) a file with this doctype.<br/> You can define
several mappings, by using character <code>|</code> as separator. For
eg:
<code>DEMO_FILE=Main|DEMO_FILE2=Additional</code>.<br/> If you have
initially uploaded your files with
the <code>Move_Files_To_Storage</code> function, you will for
eg. configure the parameter with "<code>DEMO_FILE=DEMO_FILE</code>",
so that file uploaded with <code>DEMO_FILE</code> input field will
replace the files that have been previously uploaded with doctype
"DEMO_FILE".
</p>
<p>Note that function <code>Move_Revised_Files_To_Storage</code> can
be used in combination with other techniques, as long as the mapping
in <code>elementNameToDoctype</code> can be done unambiguously.</p>
<p>Check
the <a href="<CFG_SITE_URL>/admin/websubmit/websubmitadmin.py/functionedit?funcname=Move_Revised_Files_to_Storage"><code>Move_Revised_Files_To_Storage</code>
function documentation for more detailed information.</p>
<p>This option offers a full-featured file manager, that can be
easily configured to support file upload, revision, deletion,
commenting, restrictions, etc. It can handle an "unlimited" number of
files.</p>
<p>The strategy consists in adding a WebSubmit function
("<code>Create_Upload_Files_Interface</code>") to your submission functions list,
in order to display a file submission interface. The interface will
therefore only show up after all the submission pages have been filled
in and submitted. Once displayed, the interface lets the user upload
new/revised files: the function refreshes the interface for each
upload (runs through the functions list again and stops on the
<code>Create_Upload_Files_Interface</code>). When the user applies the
modifications, the submission "step" is incremented and executes the
submissions function of step 2, skipping the display of the
interface. In this step 2 you can perform the usual tasks of your
submission. You also must add an additional function
(<code>Move_Uploaded_Files_To_Storage</code>) to run at step 2 in order to attach
the files that have been submitted at step 1.</p>
<p>These functions are incompatible with function
"Create_Modify_Interface". It is therefore suggested to create a
dedicated submission action (in addition to "SBI" and "MBI") to let
your users edit the files independently of the bibliographic data. An
example of such setup can be found in DEMOPIC submission.</p>
<b>Limitations:</b>
<ul>
<li>Use of a WebSubmit function to draw the interface, which prevents
the interface to be used inside a submission form (is displayed at a
later step). Not as integrated as a simple input file form
element.</li>
<li>Requires Javascript to be enabled user-side (is applicable to all
submissions anyway.</li>
</ul>
<p><b>1)</b> Go to your submission in WebSubmit admin, and add a new
submission action (for e.g. "[SRV] Submit New File"). If necessary,
create your own action in <a href="<CFG_SITE_URL>/admin/websubmit/websubmitadmin.py/actionlist">WebSubmit admin "Available WebSubmit Actions"</a>
page. You can clone from another existing action (in that case move to
point 4 below), or simply create an empty action.</p>
<p><b>2)</b> Go to the new SRV action interface ("View Interface"), add a
page, open it and add fields that will allow users to specify the record
to update. Typically you will add a "<code>DEMO_RN</code>" field to enter the
report number, and "<code>DEMO_CONTINUE</code>" button to submit the form.</p>
<p><b>3)</b> Go the the new SRV action functions ("View" functions) and add
the necessary functions: for e.g. at step 1, "<code>Get_Report_Number</code>",
"<code>Get_Recid</code>" and "<code>Create_Upload_Files_Interface</code>". At step 2,
"<code>Get_Recid</code>", "<code>Move_Uploaded_Files_to_Storage</code>" and "<code>Print_Success</code>".</p>
<p><b>4)</b> Configure the <code>Create_Upload_Files_Interface</code> parameters. There
are many options available. Briefly, the most important one is the
"<code>doctype</code>" parameter, which lets you specify the document types users
are allowed to submit. Use "<code>|</code>" to separate doctypes, and "<code>=</code>" to
separate <code>doctype</code> and <code>doctype</code> description. For e.g. input "<code>Main=Main
File|Additional=Additional Document</code>" to let users choose either Main
or Additional types (which will show as "Main File" and "Additional
Document" to users). Other parameters will let you define for which
<code>doctype</code> users can revise or delete files (for e.g. specify for
<code>canDeleteDoctypes</code> "Additional" so that only these
documents can be deleted once they have been uploaded). Use
"<code>*</code>" to specify "any declared doctype", and
"<code>|</code>" as separator (for all <code>can_*_doctypes</code>
parameters).</p>
<p>To read more about the parameters available for this function, check the <a href="<CFG_SITE_URL>/admin/websubmit/websubmitadmin.py/functionedit?funcname=Create_Upload_Files_Interface"><code>Create_Upload_Files_Interface</code> function documentation</a>.</p>
<p><b>5)</b> Configure the <code>Move_Uploaded_Files_To_Storage</code>. There are less options
than in <code>Create_Upload_Files_Interface</code> function. Specify for e.g. in
<code>createIconDoctypes</code> for which doctypes icons will be
created, or in "<code>forceFileRevision</code>" if revisions of file
attributes trigger a new file revision. For an up-to-date
documentation check
the <a href="<CFG_SITE_URL>/admin/websubmit/websubmitadmin.py/functionedit?funcname=Move_Uploaded_Files_to_Storage"><code>Move_Uploaded_Files_to_Storage</code>
function documentation</a>.</p>
<h4>Revising/deleting files</h4>
<p>File revisions and deletions comes for free with the
functions. Simply allow deletion or revision of files when
<p>Depending on the way your submission is built, you might <strong>have</strong> also to specify the category of the document to modify (the category is usually chosen on page "0" of the submission):</p>
<p>(Note how the category field is constructed: <code>combo{submission_code}</code> )</p>
<p>You can add as many parameters as needed to ensure that the form is filled with adequate values before being presented to the user. The parameters names correspond to the fields names in WebSubmit. For eg:</p>
<p>The parameters that you have to specify will depend on the usage which is made of them on the submission side.</p>
<p>For fields that can take several values as input (for eg. selection lists, as in the <code>DEMOART_CHANGE</code> example above) and that translate into a file in the submission direction with one value per line, you would have to specify all the values in the same URL argument, separated by <code>"%0A"</code> (newline <code>"\n"</code> encoded for URL):</p>
<p>Depending on how your submission is build, you can also move to another page ("<code>curpage</code>" param) or another step of the workflow("<code>step</code>" param):</p>
<p>(In the above example a logged in user would skip the submission splash page AND the modificaton interface to select the document and fields to update, to jump directly to the <code>DEMOART_TITLE</code> modification field)</p>
<p>In such cases you have to make sure that you provide all the information requested by the submission at each of the steps/pages until the provided step/page. Depending on how your submission is built it might be simply not possible to do that. This would be especially true when advancing steps, as functions netween the steps would not be run — most probably advancing directly to step 1 will be a maximum one can easily support — while controlling "<code>curpage</code>" parameter might be easier.</p>
<a name="terminology"></a><h2>8. Terminology</h2>
<a name="terminologydocumenttype"></a><h3>8.1 The document type of a file (<code>doctype</code>)</h3>
<p>The document type is an attribute of a file. It can be seen as a
category which lets you organize your files: "Main" file,
"Additional", "Figures", "source", whatever you need. It is not so
much used excepted on <code><CFG_SITE_RECORD>/XXX/files/</code> pages to group
files by category. It can however come handy during file upload
processes, to assign different kinds of restrictions based on the
document type, or simply to make the configuration of the submission
easier, depending on which technique you use to manage files.</p>
<a name="terminologycurdir"></a><h3>8.2 The submission directory (<code>curdir</code>)</h3>
<p>The WebSubmit workflow mainly splits in two parts: data gathering
(user interface side, with WebSubmit pages and elements) and data
integration part as a second step (with WebSubmit functions involved,
plus BibConvert templates). In the middle stands the submission
directory (also called "<code>curdir</code>"). Each submission session corresponds
to a unique submission directory, which stores the values collected
from the submission pages, in the form of a series of textual files,
one for each input field. These files are named after the submission
WebSubmit elements, and their content is the value input by the
submitter. Note that uploaded files are stored in
a <code>/files/</code> subdirectory.</p>
<p>WebSubmit functions process the files in this directory. For example
"<code>Make_Record</code>" which creates the MARCXML (through BibConvert
templates), or the <code>Stamp_Uploaded_Files</code>, which will stamp
the uploaded files in the <code>/files/</code> directory. If you
happen to write a customized WebSubmit response element that writes
files to disk, or implement a WebSubmit function that must retrieve
submitted values, you will certainly use the submission directory.</p>
<p>These submission directories are also helpful to debug submissions,
and can act as a backup when something goes wrong during a submission.</p>
<p>An example of submission directory could be found at this
<span class="guideheader">T</span>o add a document type to WebSubmit, you should go to the <a target=top href="<CFG_SITE_URL>/admin/websubmit/index.php">main page</a>
and click on "New Doctype" in the left blue panel.<br/><br/>
<span class="guideheader">E</span>ven once created, a document type will not appear automatically on this page. To configure the list of catalogues and document
types displayed on this page, the administrator shall go to the <a target=top href="<CFG_SITE_URL>/admin/websubmit/editCatalogues.php">edit catalogues</a>
page. (see the <a href="#catalogues">guide section</a>)<br clear="all"/>
<h3>The user can then click on the document type he is interested in.</h3>
<IMG src="<CFG_SITE_URL>/img/admin/websubmit-admin-guide-menu_doc.png" alt="Document type Page" class="guideimg" align="left">
<span class="guideheader">T</span>he text appearing under the header containing the name of the document
can be configured by going to the <a target=top href="websubmit-admin">main page</a>, click on
the title of the document type then on the "Edit Document Types Details" button.<br/><br/>
<span class="guideheader">Y</span>ou can associate several categories to a document type which can be defined by going to the
<a target=top href="websubmit-admin">main page</a>, click on the title of the document type
then on the "View Categories" button. The selected category will be saved in a file named "comboXXX"
(where XXX is the short name of the document type) in the submission directory.<br/><br/>
<span class="guideheader">T</span>o add an action button to this page, first implement this action by going to the
<a target=top href="websubmit-admin">main page</a>, click on the title of the document type then
on the "Add a new submission" button. If the action is already implemented and the button still does not appear
on the submision page, then you should edit the details of this implementation: go to the
<a target=top href="websubmit-admin">main page</a>, click on the title of the document type then
on the icon in the "Edit Submission" column and in the line of the desired action. There you should set the
"Displayed" form field to "YES".<br/><br/>
<span class="guideheader">Y</span>ou can also change the order of the buttons, by going to the <a target=top href="websubmit-admin">
main page</a>, click on the title of the document type then on the icon in the "Edit Submission" column and in the
line of the desired action. There you can set the "buttonorder" form field.<br/><br clear="all"/>
<h3>The user now may choose a category, then click on the action button he wishes.<br/>The submission starts, the first page of the web form appears.</h3>
<IMG src="<CFG_SITE_URL>/img/admin/websubmit-admin-guide-form.png" alt="Document type Page" class="guideimg" align="left">
<span class="guideheader">T</span>his web form is composed of several pages, on each of these
pages form fields can be found. To modify the number of pages, add or withdraw form fields and modify
the texts before each form field, you shall go to the <a target=top href="websubmit-admin">main page</a>,
click on the title of the document type then on the icon in the "Edit Submission Pages" column and in the line of the
desired action. (see the <a href="#actionimplement">guide section</a>)<br/><br clear="all"/>
<h3>On the last page of the submission, there should be a button like in the following image which will
trigger the end script</h3>
<IMG src="<CFG_SITE_URL>/img/admin/websubmit-admin-guide-end_action.png" alt="Document type End Page" class="guideimg" align="left">
<span class="guideheader">T</span>his button is defined like any other form field. Its definition should include
a <i> onclick="finish();"</i> javascript attribute.<br/><br/>
<span class="guideheader">A</span>fter clicking this button, WebSubmit will apply the end script functions
to the gathered data. To modify the end script, you shall go to the <a target=top href="websubmit-admin">
main page</a>, click on the title of the document type then on the icon in the "Edit Functions" column and in the line
of the desired action. (see the <a href="#implementfunctions">guide section</a>)<br clear="all"/>
This function searches for the document in the database and stores the recid of this document in the "SN" file and in a global variable "sysno".<br/>
The function conducts the search based upon the document's report-number (and relies upon the global variable "rn") so the "Get_Report_Number" function should be called before this one.<br/>
<i>This function replaces the older function "Get_Sysno".</i><br/>
This value depends on the web form configuration you did. It should contain the name of the form element used for storing the reference of the document.
If the authentication module (login) is active in webSubmit, this function compares the current login with the email of the original submitter. If it is the same (or if the current user has superuser rights), we go on. If it differs, an error message is issued.
indicates the file in which the program will find the counter for this reference generation.<br/>
The value of this parameter may contain one of:<br/>
"<b><PA>categ</PA></b>": in this case this string is replaced with the content of the file [altrnin]<br/>
"<b><PA>yy</PA></b>": in this case this string is replaced by the current year (4 digits) if [altyeargen]
is set to "AUTO", or by the content of the [altyeargen] file in any other case. (this content should be formatted
as a date (dd/mm/yyyy).<br/>
"<b><PA>file:<i>name_of_file</i></PA></b>": in this case, this string is replaced by the first line of the given file<br />
"<b><PA>file*:<i>name_of_file</i></PA></b>": in this case, this string is replaced by all the lines of the given file, separated by a dash ('-') character.
This is the format used by the program to create the reference. The program computes the value of the
parameter and appends a "-" followed by the current value of the counter increased by 1.<br/>
The value of this parameter may contain one of:<br/>
"<b><PA>categ</PA></b>": in this case this string is replaced with the content of the file [altrnin]<br/>
"<b><PA>yy</PA></b>": in this case this string is replaced by the current year (4 digits) if [altyeargen]
is set to "AUTO", or by the content of the [altyeargen] file in any other case. (this content should be formatted
as a date (dd/mm/yyyy).
<br/>
"<b><PA>file:<i>name_of_file</i></PA></b>": in this case, this string is replaced by the first line of the given file<br />
"<b><PA>file*:<i>name_of_file</i></PA></b>": in this case, this string is replaced by all the lines of the given file, separated by a dash ('-') character.
</small></td>
</tr>
<tr>
<td valign="top"><small><b>rnin</b></small></td>
<td><small>
This parameter contains the name of the file in which the program will find the category if needed. The content
of thif file will then replace the string <PA>categ</PA> in the reference format or in the counter
email addresses of the people who will receive this email (comma separated list). this parameter may contain the <b><CATEG></b> string. In which case the variable computed from the [categformatDAM] parameter replaces this string.<br/>
contains a regular expression used to compute the category of the document given the reference of the document.<br/>
eg.: if [categformatAFP]="TEST-<CATEG>-.*" and the reference of the document is "TEST-CATEGORY1-2001-001", then the computed category equals "CATEGORY1"
email addresses of the people who will receive this email (comma separated list). this parameter may contain the <b><CATEG></b> string. In which case the variable computed from the [categformatDAM] parameter replaces this string.<br/>
The subdirectory g0 is used to split the documents accross the filesystem. The CFG_FILE_DIR_SIZE variable from
invenio.conf determines how many documents will be stored under one subdirectory.<br/><br/>
Several files may be stored under the same document directory: they are the different formats and versions of the
same document. Versions are indicated by a string of the form ";1.0" concatenated to the name of the file.<br/><br/>
Please see the <href="/help/admin/howto-fulltext">HOWTO Manage Fulltext Files</a> for more information on the administrative command line tools available to manipulate fulltext files.