doc/src/docbook/admin/plugins.xml

Code
Comments
Other
Rev Date Author Line
3158 05 Mar 07 martin 1 <?xml version="1.0" encoding="UTF-8"?>
3159 05 Mar 07 martin 2 <!DOCTYPE chapter PUBLIC 
3159 05 Mar 07 martin 3     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
3192 13 Mar 07 martin 4     "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
3158 05 Mar 07 martin 5 <!--
3192 13 Mar 07 martin 6   $Id$
3158 05 Mar 07 martin 7
4889 06 Apr 09 nicklas 8   Copyright (C) 2007 Johan Enell, Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson
5178 02 Nov 09 jari 9   Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg
5178 02 Nov 09 jari 10   Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg, Martin Svensson
3158 05 Mar 07 martin 11
3158 05 Mar 07 martin 12   This file is part of BASE - BioArray Software Environment.
3158 05 Mar 07 martin 13   Available at http://base.thep.lu.se/
3158 05 Mar 07 martin 14
3158 05 Mar 07 martin 15   BASE is free software; you can redistribute it and/or
3158 05 Mar 07 martin 16   modify it under the terms of the GNU General Public License
4477 05 Sep 08 jari 17   as published by the Free Software Foundation; either version 3
3158 05 Mar 07 martin 18   of the License, or (at your option) any later version.
3158 05 Mar 07 martin 19
3158 05 Mar 07 martin 20   BASE is distributed in the hope that it will be useful,
3158 05 Mar 07 martin 21   but WITHOUT ANY WARRANTY; without even the implied warranty of
3158 05 Mar 07 martin 22   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
3158 05 Mar 07 martin 23   GNU General Public License for more details.
3158 05 Mar 07 martin 24
3158 05 Mar 07 martin 25   You should have received a copy of the GNU General Public License
4509 11 Sep 08 jari 26   along with BASE. If not, see <http://www.gnu.org/licenses/>.
3158 05 Mar 07 martin 27 -->
3158 05 Mar 07 martin 28
3329 11 May 07 nicklas 29 <chapter id="plugins">
5737 14 Sep 11 nicklas 30   <title>Plug-ins and extensions</title>
3175 08 Mar 07 enell 31
3175 08 Mar 07 enell 32   <para>
5737 14 Sep 11 nicklas 33     BASE can get extended functionality by the use of plug-ins and extensions. 
5737 14 Sep 11 nicklas 34     Much of the hard work, such as data import/export and analysis is done with plug-ins.
3329 11 May 07 nicklas 35     BASE ships with a number of standard plug-ins, the core plug-ins, which gives
5737 14 Sep 11 nicklas 36     basic import/export and analysis functionality. Typically a plug-in interacts with
5737 14 Sep 11 nicklas 37     a user by asking for parameters that it need to be able to do it's work. For
5737 14 Sep 11 nicklas 38     example, which file to import data from, and maybe some regular expressions that
5737 14 Sep 11 nicklas 39     should be used when parsing the file and then some information about how the data
5737 14 Sep 11 nicklas 40     in the file should be mapped to items and properties in BASE. When the plug-in has
5737 14 Sep 11 nicklas 41     all parameters it needs a <guilabel>Job</guilabel> is added to a job queue. A job
5737 14 Sep 11 nicklas 42     agent or similar is then responsible for sceduling and executing (possibly on a 
5737 14 Sep 11 nicklas 43     different machine) the plug-in code.
3175 08 Mar 07 enell 44   </para>
5737 14 Sep 11 nicklas 45   
5737 14 Sep 11 nicklas 46   <para>
5737 14 Sep 11 nicklas 47     Extensions are historically more targeted at additions to the user interface,
5737 14 Sep 11 nicklas 48     such as additional menu items, toolbar buttons, etc. As a result, extensions have 
5737 14 Sep 11 nicklas 49     a lot more flexibility when it comes to the visual appearance. On the other
5737 14 Sep 11 nicklas 50     hand they are executed immediately as a result of user interaction and are expected
5737 14 Sep 11 nicklas 51     to perform quickly and without delay. 
5737 14 Sep 11 nicklas 52   </para>
5737 14 Sep 11 nicklas 53   
5737 14 Sep 11 nicklas 54   <para>
5737 14 Sep 11 nicklas 55     Starting with BASE 3 the extension mechanism has been somewhat extended to cover
5737 14 Sep 11 nicklas 56     other things that are not directly related to the web interface. For example, 
5737 14 Sep 11 nicklas 57     extensions can be used to add support for other protocols than HTTP when using
5737 14 Sep 11 nicklas 58     external files. The main difference between a plug-in and extension is that an
5737 14 Sep 11 nicklas 59     extension must execute immediately it's service is requested, but a plug-in can
5737 14 Sep 11 nicklas 60     be scheduled for later execution.
5737 14 Sep 11 nicklas 61   </para>
3175 08 Mar 07 enell 62
3182 12 Mar 07 enell 63
3329 11 May 07 nicklas 64   <sect1 id="plugins.installation">
5737 14 Sep 11 nicklas 65     <title>Managing plug-ins and extensions</title>
3329 11 May 07 nicklas 66     
5801 12 Oct 11 nicklas 67     <important>
5737 14 Sep 11 nicklas 68       <title>Changes since BASE 2</title>
5737 14 Sep 11 nicklas 69       <para>
5737 14 Sep 11 nicklas 70         The plug-in and extensions installation has changed since BASE 2. The major
5737 14 Sep 11 nicklas 71         changes are:
5737 14 Sep 11 nicklas 72       </para>
5737 14 Sep 11 nicklas 73       <itemizedlist>
5737 14 Sep 11 nicklas 74         <listitem>
5737 14 Sep 11 nicklas 75         <para>
5737 14 Sep 11 nicklas 76           The main JAR file must be installed in the directory specified by the
5737 14 Sep 11 nicklas 77           <constant>plugins.dir</constant> setting in <filename>base.config</filename>.
5737 14 Sep 11 nicklas 78           Subdirectories are not allowed. This applies to both plug-ins and
5737 14 Sep 11 nicklas 79           extensions. The <filename>WEB-INF/extensions</filename> is not used for
5737 14 Sep 11 nicklas 80           extensions anymore.
5737 14 Sep 11 nicklas 81         </para>
5737 14 Sep 11 nicklas 82         </listitem>
5737 14 Sep 11 nicklas 83         <listitem>
5737 14 Sep 11 nicklas 84         <para>
5737 14 Sep 11 nicklas 85           A package must be installed as a whole. It is no longer possible to only
5737 14 Sep 11 nicklas 86           select some of the plug-ins to install. If neccessary, the administrator can 
5737 14 Sep 11 nicklas 87           always disable plug-ins that is not wanted.
5737 14 Sep 11 nicklas 88         </para>
5737 14 Sep 11 nicklas 89         </listitem>
5737 14 Sep 11 nicklas 90       </itemizedlist>
5801 12 Oct 11 nicklas 91     </important>
3329 11 May 07 nicklas 92     
3329 11 May 07 nicklas 93     <para>
5737 14 Sep 11 nicklas 94       The first step is to install the actual code on the web server. The recommendation
5737 14 Sep 11 nicklas 95       to developers is to ship the entire package as a single JAR file. If everything is
5737 14 Sep 11 nicklas 96       JAVA based this should not be a problem. A common exception is that configuration
5737 14 Sep 11 nicklas 97       files should be installed (and configured) separately. Always read the installation
5737 14 Sep 11 nicklas 98       instructions for the package you are installing. The rest of the instructions in
5737 14 Sep 11 nicklas 99       this section assume that the plug-in/extensions comes as a single JAR file.
3329 11 May 07 nicklas 100     </para>
3329 11 May 07 nicklas 101     
3329 11 May 07 nicklas 102     <note>
5737 14 Sep 11 nicklas 103       <title>Make sure the extensions folder is writable by Tomcat</title>
3329 11 May 07 nicklas 104       <para>
5737 14 Sep 11 nicklas 105         The package you are installing may include resources such as HTML
5737 14 Sep 11 nicklas 106         files, JSP scripts, images, etc. that needs to be extracted to the 
5737 14 Sep 11 nicklas 107         web application path before they can be used. This extraction is
5737 14 Sep 11 nicklas 108         automatically done by the installation wizard, but you have to make
5737 14 Sep 11 nicklas 109         sure that the user account Tomcat is running as has permission
5737 14 Sep 11 nicklas 110         to create (and delete) new files in the 
5737 14 Sep 11 nicklas 111         <filename class="directory">&lt;base-dir&gt;/www/extensions</filename>
5737 14 Sep 11 nicklas 112         directory.
3329 11 May 07 nicklas 113       </para>
3329 11 May 07 nicklas 114     </note>
3329 11 May 07 nicklas 115     
3329 11 May 07 nicklas 116     <para>
5737 14 Sep 11 nicklas 117       So, the first step should be simple. Just put the JAR file in the
5737 14 Sep 11 nicklas 118       dedicated plug-ins directory. This is the directory that is specified
5737 14 Sep 11 nicklas 119       in the <constant>plugins.dir</constant> setting in <filename>base.config</filename>.
3329 11 May 07 nicklas 120     </para>
3329 11 May 07 nicklas 121     
6410 31 Jan 14 nicklas 122     <important>
6410 31 Jan 14 nicklas 123       <title>Content security policy</title>
6410 31 Jan 14 nicklas 124       <para>
6410 31 Jan 14 nicklas 125         Since BASE 3.3 the default configuration specify a setting that tell web browsers
6410 31 Jan 14 nicklas 126         to not execute code (including JavaScript) that is considered unsafe. Older extensions
6410 31 Jan 14 nicklas 127         may not adhere to the restrictions implied by this and may thus not work unless
6410 31 Jan 14 nicklas 128         the configured <emphasis>Content security policy</emphasis> is relaxed a bit. 
6410 31 Jan 14 nicklas 129         The extension installation wizard will try to detect if a plug-in violates the
6410 31 Jan 14 nicklas 130         policy and display a warning message. If you see the warning please read 
6410 31 Jan 14 nicklas 131         <xref linkend="appendix.web.xml.csp-filter" /> for more information.
6410 31 Jan 14 nicklas 132       </para>
6410 31 Jan 14 nicklas 133     </important>
6410 31 Jan 14 nicklas 134     
5737 14 Sep 11 nicklas 135     <sect2 id="plugins.installation.wizard">
5737 14 Sep 11 nicklas 136       <title>Automatic installation wizard</title>
5737 14 Sep 11 nicklas 137     
3753 18 Sep 07 martin 138       <para>
5737 14 Sep 11 nicklas 139         When the plug-in/extensions package is installed on the server you must register 
5737 14 Sep 11 nicklas 140         it with BASE. Go to
5737 14 Sep 11 nicklas 141         <menuchoice>
5737 14 Sep 11 nicklas 142           <guimenu>Administrate</guimenu>
5737 14 Sep 11 nicklas 143           <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
5737 14 Sep 11 nicklas 144           <guimenuitem>Overview</guimenuitem>
5737 14 Sep 11 nicklas 145         </menuchoice>. 
3753 18 Sep 07 martin 146       </para>
5737 14 Sep 11 nicklas 147       
5737 14 Sep 11 nicklas 148       <figure id="extensions.figures.installedextensions">
5737 14 Sep 11 nicklas 149         <title>Installed extensions &amp; plug-ins</title>
5737 14 Sep 11 nicklas 150         <screenshot>
5737 14 Sep 11 nicklas 151           <mediaobject>
5737 14 Sep 11 nicklas 152             <imageobject>
5737 14 Sep 11 nicklas 153               <imagedata fileref="figures/installed_extensions.png" format="PNG" />
5737 14 Sep 11 nicklas 154             </imageobject>
5737 14 Sep 11 nicklas 155           </mediaobject>
5737 14 Sep 11 nicklas 156         </screenshot>
5737 14 Sep 11 nicklas 157       </figure>  
5737 14 Sep 11 nicklas 158       
5737 14 Sep 11 nicklas 159       <helptext 
5737 14 Sep 11 nicklas 160         external_id="extensions.details.main" 
5737 14 Sep 11 nicklas 161         title="Installed extensions">
3866 19 Oct 07 nicklas 162         
5737 14 Sep 11 nicklas 163         <para>
5737 14 Sep 11 nicklas 164           The left-hand side of the screen shows a tree with all installed 
5737 14 Sep 11 nicklas 165           plug-ins and extensions, sorted by extension point and by file. Use 
5737 14 Sep 11 nicklas 166           the + and - icons to expand and collapse parts of the tree. Click on an item
5737 14 Sep 11 nicklas 167           in the tree to display detailed information about it
5737 14 Sep 11 nicklas 168           on the right-hand side of the screen. Click on the 
5737 14 Sep 11 nicklas 169           <guibutton>Install/uninstall</guibutton> button to start
5737 14 Sep 11 nicklas 170           the installation wizard (which can also be used for uninstallation).
5737 14 Sep 11 nicklas 171         </para>
3866 19 Oct 07 nicklas 172         
3866 19 Oct 07 nicklas 173         <seeother>
5737 14 Sep 11 nicklas 174           <other external_id="extensions.install-wizard">Install/uninstall wizard</other>
3866 19 Oct 07 nicklas 175         </seeother>
5737 14 Sep 11 nicklas 176       </helptext>
5737 14 Sep 11 nicklas 177       
5737 14 Sep 11 nicklas 178       <figure id="plugins.figures.installwizard">
5737 14 Sep 11 nicklas 179         <title>Extensions and plug-ins installation wizard</title>
5737 14 Sep 11 nicklas 180         <screenshot>
5737 14 Sep 11 nicklas 181           <mediaobject>
5737 14 Sep 11 nicklas 182             <imageobject>
5737 14 Sep 11 nicklas 183               <imagedata fileref="figures/plugins_install_wizard.png" format="PNG"
5737 14 Sep 11 nicklas 184                 scalefit="1" width="100%" />
5737 14 Sep 11 nicklas 185             </imageobject>
5737 14 Sep 11 nicklas 186           </mediaobject>
5737 14 Sep 11 nicklas 187         </screenshot>
5737 14 Sep 11 nicklas 188       </figure>
3866 19 Oct 07 nicklas 189         
5737 14 Sep 11 nicklas 190   
5737 14 Sep 11 nicklas 191       <helptext 
5737 14 Sep 11 nicklas 192         external_id="extensions.install-wizard"
5737 14 Sep 11 nicklas 193         title="Extensions and plug-ins installation wizard">
5737 14 Sep 11 nicklas 194         
5737 14 Sep 11 nicklas 195         <para>
5737 14 Sep 11 nicklas 196           This wizard can be used for both installing, re-installing and un-installing
5737 14 Sep 11 nicklas 197           plug-in and extension packages. The first dialog shows a list with all 
5737 14 Sep 11 nicklas 198           currently installed packages as well as any new packages that has been
5737 14 Sep 11 nicklas 199           found on the server. The list includes the name of the JAR file,
5737 14 Sep 11 nicklas 200           the current status and some information provided by the author of the package.
7234 17 Nov 16 nicklas 201           There are also three columns <guilabel>Install</guilabel>, <guilabel>Uninstall</guilabel> and
7234 17 Nov 16 nicklas 202           <guilabel>Ignore</guilabel> which may or may not have a checkbox in them.
5737 14 Sep 11 nicklas 203           For new packages there should be a checkbox in the install column that is already
5737 14 Sep 11 nicklas 204           checked. Already installed packages can either be re-installed or uninstalled by
5737 14 Sep 11 nicklas 205           checking the appropriate checkbox. If there is a problem with a package an error 
5737 14 Sep 11 nicklas 206           message is displayed and neither installation or uninstallation is possible.
5737 14 Sep 11 nicklas 207         </para>
5737 14 Sep 11 nicklas 208         
5737 14 Sep 11 nicklas 209         <para>
7234 17 Nov 16 nicklas 210           The <guilabel>Ignore</guilabel> column can be used to tell the wizard to
7234 17 Nov 16 nicklas 211           ignore the selected file from now on. Ignored files are moved to a 
7234 17 Nov 16 nicklas 212           separate section at the bottom of the installation wizard and you will
7234 17 Nov 16 nicklas 213           not be asked about installing them every time you run the wizard. Ignored
7234 17 Nov 16 nicklas 214           files can either be brought back to the regular flow with the 
7234 17 Nov 16 nicklas 215           <guilabel>Stop ignore</guilabel> option or directly installed with
7234 17 Nov 16 nicklas 216           the <guilabel>Install</guilabel> button.
7234 17 Nov 16 nicklas 217         </para>
7234 17 Nov 16 nicklas 218         
7234 17 Nov 16 nicklas 219         <para>
5737 14 Sep 11 nicklas 220           Click on <guibutton>Next</guibutton> to perform the selected actions. The next 
5737 14 Sep 11 nicklas 221           dialog should display a summary with the installation results. 
5737 14 Sep 11 nicklas 222           Hopefully everything was succeessful. Close the dialog and refresh the overview tree
5737 14 Sep 11 nicklas 223           to see the changes.
5737 14 Sep 11 nicklas 224         </para>
5737 14 Sep 11 nicklas 225       
5737 14 Sep 11 nicklas 226         <note>
5737 14 Sep 11 nicklas 227           <para>
5737 14 Sep 11 nicklas 228             Uninstalling a package doesn't remove the plug-in definitions from BASE nor
5737 14 Sep 11 nicklas 229             does it remove the JAR file from the server. This is because there may be jobs 
5737 14 Sep 11 nicklas 230             and other items referencing the plug-ins. The plug-ins are only marked as disabled
5737 14 Sep 11 nicklas 231             and it is up to the administrator to actually delete them if it is possible.
5737 14 Sep 11 nicklas 232           </para>
5737 14 Sep 11 nicklas 233         </note>
3753 18 Sep 07 martin 234       </helptext>
5737 14 Sep 11 nicklas 235       
5737 14 Sep 11 nicklas 236       <figure id="plugins.figures.installresults">
5737 14 Sep 11 nicklas 237         <title>Extensions and plug-ins installation results</title>
5737 14 Sep 11 nicklas 238         <screenshot>
5737 14 Sep 11 nicklas 239           <mediaobject>
5737 14 Sep 11 nicklas 240             <imageobject>
5737 14 Sep 11 nicklas 241               <imagedata fileref="figures/plugins_install_wizard_2.png" format="PNG"
5737 14 Sep 11 nicklas 242                 scalefit="1" width="100%" />
5737 14 Sep 11 nicklas 243             </imageobject>
5737 14 Sep 11 nicklas 244           </mediaobject>
5737 14 Sep 11 nicklas 245         </screenshot>
5737 14 Sep 11 nicklas 246       </figure>
3753 18 Sep 07 martin 247     </sect2>
3753 18 Sep 07 martin 248
5737 14 Sep 11 nicklas 249     <sect2 id="plugins.installation.manual">
5737 14 Sep 11 nicklas 250       <title>Manual plug-in registration</title>
3329 11 May 07 nicklas 251     
5737 14 Sep 11 nicklas 252       <para>
5737 14 Sep 11 nicklas 253         Manual installation of a plug-in should almost never be neccessary.
5737 14 Sep 11 nicklas 254         One exception is that developers may want to do this as a first step
5737 14 Sep 11 nicklas 255         before everything has been properly packaged. Another exception is plug-ins
5737 14 Sep 11 nicklas 256         developed for BASE 2 that doesn't support the automatic installation procedure.
5737 14 Sep 11 nicklas 257         If the old plug-in still works API-wise in BASE 3, manual installation
5737 14 Sep 11 nicklas 258         can be used to install it. Repackaging such a plug-in is however not difficult
5737 14 Sep 11 nicklas 259         so we recommend that the plug-in author is asked to provide an updated
5737 14 Sep 11 nicklas 260         version.
5737 14 Sep 11 nicklas 261       </para>
5737 14 Sep 11 nicklas 262       
5737 14 Sep 11 nicklas 263       <para>
5830 27 Oct 11 nicklas 264         To perform a manual installation the plug-in's JAR file must be
5830 27 Oct 11 nicklas 265         located in the the directory specified by the <constant>plugins.dir</constant>
5830 27 Oct 11 nicklas 266         setting in <filename>base.config</filename>. Subdirectories are not
5830 27 Oct 11 nicklas 267         allowed. This is a change since BASE 2 were plug-ins could be installed
5830 27 Oct 11 nicklas 268         almost anywhere. When the JAR file is in place, go to 
5830 27 Oct 11 nicklas 269         <menuchoice>
5737 14 Sep 11 nicklas 270         <guimenu>Administrate</guimenu>
5737 14 Sep 11 nicklas 271         <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
5737 14 Sep 11 nicklas 272         <guimenuitem>Plug-in definitions</guimenuitem>
5737 14 Sep 11 nicklas 273         </menuchoice> and click on the <guibutton>New</guibutton> button.
5737 14 Sep 11 nicklas 274       </para>
3866 19 Oct 07 nicklas 275     
5737 14 Sep 11 nicklas 276       <figure id="plugins.figures.installmanual">
5737 14 Sep 11 nicklas 277         <title>Manually installing a plug-in</title>
5737 14 Sep 11 nicklas 278         <screenshot>
5737 14 Sep 11 nicklas 279           <mediaobject>
5737 14 Sep 11 nicklas 280             <imageobject><imagedata 
5737 14 Sep 11 nicklas 281               fileref="figures/plugins_install_manual.png" format="PNG"
5737 14 Sep 11 nicklas 282               /></imageobject>
5737 14 Sep 11 nicklas 283           </mediaobject>
5737 14 Sep 11 nicklas 284         </screenshot>
5737 14 Sep 11 nicklas 285       </figure>
3329 11 May 07 nicklas 286     
3329 11 May 07 nicklas 287     <helptext external_id="plugindefinition.edit" 
3339 15 May 07 nicklas 288       title="Plug-in properties">
3329 11 May 07 nicklas 289       
3329 11 May 07 nicklas 290       <variablelist>
3329 11 May 07 nicklas 291       <varlistentry>
3329 11 May 07 nicklas 292         <term><guilabel>Name</guilabel></term>
3329 11 May 07 nicklas 293         <listitem>
3329 11 May 07 nicklas 294           <para>
3329 11 May 07 nicklas 295             The name of the plug-in. This name is set automatically by
3487 13 Jun 07 peter 296             the plug-in and cannot be changed.
3329 11 May 07 nicklas 297           </para>
3329 11 May 07 nicklas 298         </listitem>
3329 11 May 07 nicklas 299       </varlistentry>
3329 11 May 07 nicklas 300       <varlistentry>
3329 11 May 07 nicklas 301         <term><guilabel>Class</guilabel></term>
3329 11 May 07 nicklas 302         <listitem>
3329 11 May 07 nicklas 303           <para>
5737 14 Sep 11 nicklas 304             The full Java class name of the plug-in.
3329 11 May 07 nicklas 305           </para>
3329 11 May 07 nicklas 306         </listitem>
3329 11 May 07 nicklas 307       </varlistentry>
3329 11 May 07 nicklas 308       <varlistentry>
5737 14 Sep 11 nicklas 309         <term><guilabel>JAR file</guilabel></term>
3329 11 May 07 nicklas 310         <listitem>
3329 11 May 07 nicklas 311           <para>
5737 14 Sep 11 nicklas 312             The name of the JAR file on the web server. The JAR file must
5737 14 Sep 11 nicklas 313             be installed in the directory specified by the <constant>plugins.dir</constant>
5737 14 Sep 11 nicklas 314             setting in <filename>base.config</filename> If left empty
3329 11 May 07 nicklas 315             the plug-in must be on the web server's class path (not 
3329 11 May 07 nicklas 316             recommended).
3329 11 May 07 nicklas 317           </para>
3329 11 May 07 nicklas 318         </listitem>
3329 11 May 07 nicklas 319       </varlistentry>
3329 11 May 07 nicklas 320       <varlistentry>
3329 11 May 07 nicklas 321         <term><guilabel>Max memory</guilabel></term>
3329 11 May 07 nicklas 322         <listitem>
3329 11 May 07 nicklas 323           <para>
3329 11 May 07 nicklas 324             The maximum amount of memory the plug-in may use. This setting
3329 11 May 07 nicklas 325             only applies when the plug-in is executed with a job agent. If
3345 16 May 07 martin 326             the internal job queue is used this setting has no effect and the
3329 11 May 07 nicklas 327             plug-in may use as much memory as it likes. 
5738 15 Sep 11 nicklas 328             <nohelp>See <xref linkend="installation.jobagents.configuration" /> for more information.</nohelp>
3329 11 May 07 nicklas 329           </para>
3329 11 May 07 nicklas 330         </listitem>
3329 11 May 07 nicklas 331       </varlistentry>
3329 11 May 07 nicklas 332       <varlistentry>
3329 11 May 07 nicklas 333         <term><guilabel>Trusted</guilabel></term>
3329 11 May 07 nicklas 334         <listitem>
3329 11 May 07 nicklas 335           <para>
3329 11 May 07 nicklas 336             If the plug-in is trusted enough to be executed in an
3329 11 May 07 nicklas 337             unprotected environment. This setting has currently no
3487 13 Jun 07 peter 338             effect since BASE cannot run in a protected environment.
3329 11 May 07 nicklas 339             When this becomes implemented in the future a 
3329 11 May 07 nicklas 340             <guilabel>no</guilabel> value will apply security restrictions
3345 16 May 07 martin 341             to plug-ins similar to those a web browser put on applets.
3329 11 May 07 nicklas 342             For example, the plug-in is not allowed to access the file
3329 11 May 07 nicklas 343             system, open ports, shut down the server, and a lot of
3329 11 May 07 nicklas 344             other nasty things.
3329 11 May 07 nicklas 345           </para>
3329 11 May 07 nicklas 346         </listitem>
3329 11 May 07 nicklas 347       </varlistentry>
3329 11 May 07 nicklas 348       <varlistentry>
3329 11 May 07 nicklas 349         <term><guilabel>Allow immediate execution</guilabel></term>
3329 11 May 07 nicklas 350         <listitem>
3329 11 May 07 nicklas 351           <para>
3329 11 May 07 nicklas 352             If the plug-in is allowed to bypass the job queue
3329 11 May 07 nicklas 353             and be executed immediately. 
3329 11 May 07 nicklas 354             
3329 11 May 07 nicklas 355             <itemizedlist>
3329 11 May 07 nicklas 356               <listitem>
3329 11 May 07 nicklas 357                 <para>
3329 11 May 07 nicklas 358                 <guilabel>No</guilabel>: The plug-in must always use
3329 11 May 07 nicklas 359                 the job queue.
3329 11 May 07 nicklas 360                 </para>
3329 11 May 07 nicklas 361               </listitem>
3329 11 May 07 nicklas 362               <listitem>
3329 11 May 07 nicklas 363                 <para>
3329 11 May 07 nicklas 364                 <guilabel>Yes</guilabel>: The plug-in is allowed to bypass
3329 11 May 07 nicklas 365                 the job queue. This also means that the plug-in always 
3329 11 May 07 nicklas 366                 executes on the web server, job agents are not used. 
3329 11 May 07 nicklas 367                 This setting is mainly useful for export plug-ins that
3329 11 May 07 nicklas 368                 needs to support immediate download of the exported data.
3329 11 May 07 nicklas 369                 <nohelp>
3329 11 May 07 nicklas 370                 See <xref linkend="import_export_data.export.immediatedownload" />.
3329 11 May 07 nicklas 371                 </nohelp>
3329 11 May 07 nicklas 372                 </para>
3329 11 May 07 nicklas 373                 
3329 11 May 07 nicklas 374                 <note>
3329 11 May 07 nicklas 375                   If a plug-in should be executed immediately or not
3329 11 May 07 nicklas 376                   is always decided by the plug-in. BASE will never give
3329 11 May 07 nicklas 377                   the users a choice.
3329 11 May 07 nicklas 378                 </note>
3329 11 May 07 nicklas 379                 
3329 11 May 07 nicklas 380               </listitem>
3329 11 May 07 nicklas 381               <listitem>
3329 11 May 07 nicklas 382                 <para>
3329 11 May 07 nicklas 383                 <guilabel>Auto</guilabel>: BASE will allow export plug-ins
3329 11 May 07 nicklas 384                 to execute immediately, and deny all other types of plug-ins.
3329 11 May 07 nicklas 385                 This alternative is only available when registering a new 
3329 11 May 07 nicklas 386                 plug-in.
3329 11 May 07 nicklas 387                 </para>
3329 11 May 07 nicklas 388               </listitem>
3329 11 May 07 nicklas 389             </itemizedlist>
3329 11 May 07 nicklas 390             
3329 11 May 07 nicklas 391           </para>
3329 11 May 07 nicklas 392         </listitem>
3329 11 May 07 nicklas 393       </varlistentry>
3329 11 May 07 nicklas 394       </variablelist>
3329 11 May 07 nicklas 395       
3329 11 May 07 nicklas 396       <para>
3394 28 May 07 martin 397         Click on &gbSave; to finish the registration
3394 28 May 07 martin 398         or on &gbCancel; to abort.
3329 11 May 07 nicklas 399       </para>
3329 11 May 07 nicklas 400       
3329 11 May 07 nicklas 401       <seeother>
3339 15 May 07 nicklas 402         <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other>
3339 15 May 07 nicklas 403         <other external_id="plugindefinition.jobagents">Job agents</other>
3866 19 Oct 07 nicklas 404         <other external_id="plugindefintion.autoinstaller">Automatic installation</other>
3329 11 May 07 nicklas 405       </seeother>    
3329 11 May 07 nicklas 406       
3329 11 May 07 nicklas 407     </helptext>
3329 11 May 07 nicklas 408     </sect2>
3329 11 May 07 nicklas 409     
5737 14 Sep 11 nicklas 410
3329 11 May 07 nicklas 411     <sect2 id="plugins.installation.base1">
4441 03 Sep 08 jari 412       <title>BASE version 1 plug-ins</title>
3339 15 May 07 nicklas 413       <para>
4441 03 Sep 08 jari 414         BASE version 1 plug-ins are supported through the use of
4441 03 Sep 08 jari 415         the <emphasis>Base1PluginExecuter</emphasis> plug-in. This is
4441 03 Sep 08 jari 416         itself a plug-in and BASE version 1 plug-ins are added as
5178 02 Nov 09 jari 417         configurations to this plug-in (cf.
5178 02 Nov 09 jari 418         <xref linkend="plugins.configuration" />). To install a BASE
4441 03 Sep 08 jari 419         version 1 plug-in follow these instructions:
3339 15 May 07 nicklas 420       </para>
3339 15 May 07 nicklas 421       
3339 15 May 07 nicklas 422       <orderedlist>
3339 15 May 07 nicklas 423         <listitem>
3339 15 May 07 nicklas 424         <para>
5178 02 Nov 09 jari 425           Install the BASE version 1 plug-in executable and any other
5178 02 Nov 09 jari 426           files needed by it on the BASE server. Check the
5178 02 Nov 09 jari 427           documentation for the plug-in for information about what is
5178 02 Nov 09 jari 428           needed.
3339 15 May 07 nicklas 429         </para>
3339 15 May 07 nicklas 430         </listitem>
3339 15 May 07 nicklas 431         
3339 15 May 07 nicklas 432         <listitem>
3339 15 May 07 nicklas 433         <para>
5737 14 Sep 11 nicklas 434           Upload the <filename>*.base</filename> file for the BASE
5737 14 Sep 11 nicklas 435           version 1 plug-in. If you cannot find the file, you can let
5737 14 Sep 11 nicklas 436           your BASE version 1 server create one for you. In your BASE
5737 14 Sep 11 nicklas 437           version 1 installation go to
5737 14 Sep 11 nicklas 438           <menuchoice>
5737 14 Sep 11 nicklas 439             <guimenu>Analyze data</guimenu>
5737 14 Sep 11 nicklas 440             <guimenuitem>Plug-ins</guimenuitem>
5737 14 Sep 11 nicklas 441           </menuchoice>
5737 14 Sep 11 nicklas 442           and use the <guilabel>Export</guilabel> function. This will
5737 14 Sep 11 nicklas 443           create a configuration file for your BASE version 1 plug-in
5737 14 Sep 11 nicklas 444           that you can upload to your new BASE server.
3339 15 May 07 nicklas 445         </para>
3339 15 May 07 nicklas 446         </listitem>
3339 15 May 07 nicklas 447
3329 11 May 07 nicklas 448         <listitem>
3329 11 May 07 nicklas 449           <para>
5737 14 Sep 11 nicklas 450             Create a new plug-in configuration using, for example,
5737 14 Sep 11 nicklas 451             the <guibutton>New configuration</guibutton> button in
5737 14 Sep 11 nicklas 452             single-item view for
5737 14 Sep 11 nicklas 453             the <emphasis>Base1PluginExecuter</emphasis> plug-in.
3329 11 May 07 nicklas 454           </para>
3329 11 May 07 nicklas 455         </listitem>
5737 14 Sep 11 nicklas 456
3329 11 May 07 nicklas 457         <listitem>
3329 11 May 07 nicklas 458           <para>
5737 14 Sep 11 nicklas 459             Start the configuration wizard and select parameters:
3329 11 May 07 nicklas 460           </para>
5737 14 Sep 11 nicklas 461           <itemizedlist>
5737 14 Sep 11 nicklas 462             <listitem>
5737 14 Sep 11 nicklas 463             <para>
5737 14 Sep 11 nicklas 464               <guilabel>File</guilabel>: The <filename>*.base</filename> file 
5737 14 Sep 11 nicklas 465               describing the BASE version 1 plug-in. This can be left empty for
5737 14 Sep 11 nicklas 466               manual configuration, but in reality it is only usable for tweaking
5737 14 Sep 11 nicklas 467               an existing configuration that has been created from a file
5737 14 Sep 11 nicklas 468               in the first place.
5737 14 Sep 11 nicklas 469             </para>
5737 14 Sep 11 nicklas 470             </listitem>
5737 14 Sep 11 nicklas 471             <listitem>
5737 14 Sep 11 nicklas 472             <para>
5737 14 Sep 11 nicklas 473               <guilabel>Plugin executables path</guilabel>: The path to the executable
5737 14 Sep 11 nicklas 474               program that was installed in the first step.
5737 14 Sep 11 nicklas 475               
5737 14 Sep 11 nicklas 476             </para>
5737 14 Sep 11 nicklas 477             </listitem>
5737 14 Sep 11 nicklas 478             <listitem>
5737 14 Sep 11 nicklas 479             <para>
5737 14 Sep 11 nicklas 480               <guilabel>Source intensities</guilabel>: Select if the plug-in can work
5737 14 Sep 11 nicklas 481               with regular or logged data (or both).
5737 14 Sep 11 nicklas 482             </para>
5737 14 Sep 11 nicklas 483             </listitem>
5737 14 Sep 11 nicklas 484             <listitem>
5737 14 Sep 11 nicklas 485             <para>
5737 14 Sep 11 nicklas 486               <guilabel>Resulting intensities</guilabel>: Select if the plug-in generates
5737 14 Sep 11 nicklas 487               regular or logged data.
5737 14 Sep 11 nicklas 488             </para>
5737 14 Sep 11 nicklas 489             </listitem>
5737 14 Sep 11 nicklas 490           </itemizedlist>
5737 14 Sep 11 nicklas 491           
3329 11 May 07 nicklas 492           <para>
5737 14 Sep 11 nicklas 493             Click <guibutton>Next</guibutton> to finish the wizard.
3329 11 May 07 nicklas 494           </para>
5737 14 Sep 11 nicklas 495           
3329 11 May 07 nicklas 496         </listitem>
5737 14 Sep 11 nicklas 497
3329 11 May 07 nicklas 498         <listitem>
3329 11 May 07 nicklas 499           <para>
5737 14 Sep 11 nicklas 500             To check that the new plug-in works correctly, you need to
5737 14 Sep 11 nicklas 501             have an experiment with some data. Go to the single-item
5737 14 Sep 11 nicklas 502             view for a bioassay set and click on the <guibutton>Run
5737 14 Sep 11 nicklas 503             analysis</guibutton> button. Select
5737 14 Sep 11 nicklas 504             the <emphasis>Base1PluginExecuter</emphasis> plug-in. The
5737 14 Sep 11 nicklas 505             list of configurations should include the newly installed
5737 14 Sep 11 nicklas 506             plug-in. Select it and click on &gbNext;.
3329 11 May 07 nicklas 507           </para>
3329 11 May 07 nicklas 508         </listitem>
5737 14 Sep 11 nicklas 509
3329 11 May 07 nicklas 510         <listitem>
3329 11 May 07 nicklas 511           <para>
5737 14 Sep 11 nicklas 512             This will enter regular plug-in execution wizard and you
5737 14 Sep 11 nicklas 513             will have to enter parameters needed by the plug-in.
3329 11 May 07 nicklas 514           </para>
3329 11 May 07 nicklas 515         </listitem>
3175 08 Mar 07 enell 516
5737 14 Sep 11 nicklas 517       </orderedlist>
3329 11 May 07 nicklas 518
5737 14 Sep 11 nicklas 519     </sect2>
5737 14 Sep 11 nicklas 520       
3329 11 May 07 nicklas 521     
5737 14 Sep 11 nicklas 522     <sect2 id="plugins.installation.xjspcompiler">
5737 14 Sep 11 nicklas 523       <title>Installing the X-JSP compiler</title>
5737 14 Sep 11 nicklas 524       <para>
5737 14 Sep 11 nicklas 525         Some extensions may want to use custom JSP files that also uses
5737 14 Sep 11 nicklas 526         classes that are stored in the extension's JAR file. The problem
5737 14 Sep 11 nicklas 527         with this is that Tomcat usually doesn't know to look for classes
5737 14 Sep 11 nicklas 528         in the <filename>plugins.dir</filename> directory. To solve
5737 14 Sep 11 nicklas 529         this problem BASE ships with a X-JSP compiler that can do this.
5737 14 Sep 11 nicklas 530         This compiler has been mapped to files with a <code>.xjsp</code>
5737 14 Sep 11 nicklas 531         extension, which are just regular JSP files with a different extension.
5737 14 Sep 11 nicklas 532       </para>
3339 15 May 07 nicklas 533       
3339 15 May 07 nicklas 534       <para>
5737 14 Sep 11 nicklas 535         The X-JSP compiler must be installed into Tomcat's internal
5737 14 Sep 11 nicklas 536         library folder (<filename>$CATALINA_HOME/lib</filename>)
5737 14 Sep 11 nicklas 537         since this is the only place where Tomcat look for compilers. The installation 
5737 14 Sep 11 nicklas 538         is easy. Simply copy <filename>&lt;base-dir&gt;/bin/jar/base-xjsp-compiler-3.x.jar</filename>
5737 14 Sep 11 nicklas 539         to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat.
3339 15 May 07 nicklas 540       </para>
3339 15 May 07 nicklas 541       
5737 14 Sep 11 nicklas 542       <note>
5737 14 Sep 11 nicklas 543         <title>X-JSP is experimental</title>
5737 14 Sep 11 nicklas 544         <para>
5737 14 Sep 11 nicklas 545           This is an experimental feature that depends on internal functionality
5737 14 Sep 11 nicklas 546           in Tomcat. It may or may not work with future versions of Tomcat.
5737 14 Sep 11 nicklas 547           The compiler will most likely not work with other servlet 
6129 14 Sep 12 nicklas 548           containers.
5737 14 Sep 11 nicklas 549         </para>
5737 14 Sep 11 nicklas 550       </note>
5737 14 Sep 11 nicklas 551     </sect2>
5737 14 Sep 11 nicklas 552     
5737 14 Sep 11 nicklas 553     <sect2 id="plugins.installation.disable">
5737 14 Sep 11 nicklas 554       <title>Disable/enable plug-ins and extensions</title>
3339 15 May 07 nicklas 555       
3339 15 May 07 nicklas 556       <para>
5737 14 Sep 11 nicklas 557         It is possible to disable specific extensions, extension point
5737 14 Sep 11 nicklas 558         and or a plug-in without uninstalling the XML or JAR file.
5737 14 Sep 11 nicklas 559         When you click on an item in the tree on the left-hand side of the 
5737 14 Sep 11 nicklas 560         screen a lot of detailed information about it will show up on the right-hand side.
5737 14 Sep 11 nicklas 561         The right-hand side usually has a <guibutton>Disable</guibutton>
5737 14 Sep 11 nicklas 562         or <guibutton>Disable all</guibutton> button in the toolbar. Click on that button
5737 14 Sep 11 nicklas 563         to disable the plug-in, extension or all extensions
5737 14 Sep 11 nicklas 564         for an extension point. The button will change to <guibutton>Enable</guibutton>
5737 14 Sep 11 nicklas 565         or <guibutton>Enable all</guibutton> which lets you enable the extensions and
5737 14 Sep 11 nicklas 566         plug-ins again. 
3339 15 May 07 nicklas 567       </para>
5737 14 Sep 11 nicklas 568     </sect2>
5737 14 Sep 11 nicklas 569
5737 14 Sep 11 nicklas 570     <sect2 id="plugins.permissions">
5737 14 Sep 11 nicklas 571       <title>Plug-in permissions</title>
5737 14 Sep 11 nicklas 572   
5737 14 Sep 11 nicklas 573       <helptext external_id="plugindefinition.edit.permissions" 
5737 14 Sep 11 nicklas 574         title="Edit plug-in permissions">
5737 14 Sep 11 nicklas 575   
3339 15 May 07 nicklas 576       
5737 14 Sep 11 nicklas 577         <para>
5737 14 Sep 11 nicklas 578           When a plug-in is executed the default is to give it the same
5737 14 Sep 11 nicklas 579           permissions as the user that started it. This can be seen as a 
5737 14 Sep 11 nicklas 580           security risk if the plug-in is not trusted, or if someone manages
5737 14 Sep 11 nicklas 581           to replace the plug-in code with their own code. A malicious plug-in can, 
5737 14 Sep 11 nicklas 582           for example, delete the entire database if invoked by the root user.
5737 14 Sep 11 nicklas 583         </para>
5737 14 Sep 11 nicklas 584         
5737 14 Sep 11 nicklas 585         <para>
5737 14 Sep 11 nicklas 586           To limit this problem it is possible to tune the permissions for
5737 14 Sep 11 nicklas 587           a plug-in so that it only has permission to do things that it
5737 14 Sep 11 nicklas 588           is supposed to do. For example, a plug-in that import reporters
5737 14 Sep 11 nicklas 589           may only need permission to update and create new reporters and
5737 14 Sep 11 nicklas 590           nothing else.
5737 14 Sep 11 nicklas 591         </para>
3339 15 May 07 nicklas 592       
5737 14 Sep 11 nicklas 593         <nohelp>
5737 14 Sep 11 nicklas 594         <para>
5737 14 Sep 11 nicklas 595           To enable the permission system for a plug-in go the
5737 14 Sep 11 nicklas 596           edit view of the plug-in and select the <guilabel>Permissions</guilabel>
5737 14 Sep 11 nicklas 597           tab.
5737 14 Sep 11 nicklas 598         </para>
5737 14 Sep 11 nicklas 599         
5737 14 Sep 11 nicklas 600         <figure id="plugins.figures.permissions">
5737 14 Sep 11 nicklas 601           <title>Setting permissions on a plug-in</title>
5737 14 Sep 11 nicklas 602           <screenshot>
5737 14 Sep 11 nicklas 603             <mediaobject>
5737 14 Sep 11 nicklas 604               <imageobject><imagedata 
5737 14 Sep 11 nicklas 605                 fileref="figures/plugin_permissions.png" format="PNG"
5737 14 Sep 11 nicklas 606                 /></imageobject>
5737 14 Sep 11 nicklas 607             </mediaobject>
5737 14 Sep 11 nicklas 608           </screenshot>
5737 14 Sep 11 nicklas 609         </figure>
5737 14 Sep 11 nicklas 610         </nohelp>
5737 14 Sep 11 nicklas 611   
5737 14 Sep 11 nicklas 612         <variablelist>
5737 14 Sep 11 nicklas 613         <varlistentry>
5737 14 Sep 11 nicklas 614           <term><guilabel>Use permissions</guilabel></term>
5737 14 Sep 11 nicklas 615           <listitem>
5737 14 Sep 11 nicklas 616             <para>
5737 14 Sep 11 nicklas 617               Select if the plug-in should use the permission system
5737 14 Sep 11 nicklas 618               or not. If <guilabel>no</guilabel> is selected, the rest
5737 14 Sep 11 nicklas 619               of the form is disabled.
5737 14 Sep 11 nicklas 620             </para>
5737 14 Sep 11 nicklas 621           </listitem>
5737 14 Sep 11 nicklas 622         </varlistentry>
5737 14 Sep 11 nicklas 623         <varlistentry>
5737 14 Sep 11 nicklas 624           <term><guilabel>Item types</guilabel></term>
5737 14 Sep 11 nicklas 625           <listitem>
5737 14 Sep 11 nicklas 626             <para>
5737 14 Sep 11 nicklas 627               The list contains all item types found in BASE that
5737 14 Sep 11 nicklas 628               can have permissions set on them. The list is more or less the
5737 14 Sep 11 nicklas 629               same as the permission list for roles.
5737 14 Sep 11 nicklas 630               <nohelp>
5738 15 Sep 11 nicklas 631                 See <xref linkend="accounts.roles.edit.permissions" />.
5737 14 Sep 11 nicklas 632               </nohelp>
5737 14 Sep 11 nicklas 633             </para>
5737 14 Sep 11 nicklas 634           </listitem>
5737 14 Sep 11 nicklas 635         </varlistentry>
5737 14 Sep 11 nicklas 636         <varlistentry>
5737 14 Sep 11 nicklas 637           <term><guilabel>Always grant</guilabel></term>
5737 14 Sep 11 nicklas 638           <listitem>
5737 14 Sep 11 nicklas 639             <para>
5737 14 Sep 11 nicklas 640               The selected permissions will always be granted
5737 14 Sep 11 nicklas 641               to the plug-in no matter if the logged in user had the
5737 14 Sep 11 nicklas 642               permission to begin with or not. This makes it possible to 
5737 14 Sep 11 nicklas 643               develop a plug-in that allows users to do things that they 
5737 14 Sep 11 nicklas 644               are normally not allowed to do. The reporter importer is
5737 14 Sep 11 nicklas 645               for example allowed to create and use reporter types.
5737 14 Sep 11 nicklas 646             </para>
5737 14 Sep 11 nicklas 647           </listitem>
5737 14 Sep 11 nicklas 648         </varlistentry>
5737 14 Sep 11 nicklas 649         <varlistentry>
5737 14 Sep 11 nicklas 650           <term><guilabel>Always deny</guilabel></term>
5737 14 Sep 11 nicklas 651           <listitem>
5737 14 Sep 11 nicklas 652             <para>
5737 14 Sep 11 nicklas 653               The selected permissions will always be denied
5737 14 Sep 11 nicklas 654               to the plug-in no matter if the logged in user had the
5737 14 Sep 11 nicklas 655               permission to begin with or not. The default is to always
5737 14 Sep 11 nicklas 656               deny all permissions. Permissions that are not always
5737 14 Sep 11 nicklas 657               denied and not always granted uses permissions from
5737 14 Sep 11 nicklas 658               the logged in user.
5737 14 Sep 11 nicklas 659             </para>
5737 14 Sep 11 nicklas 660           </listitem>
5737 14 Sep 11 nicklas 661         </varlistentry>
5737 14 Sep 11 nicklas 662         <varlistentry>
5737 14 Sep 11 nicklas 663           <term><guilabel>Requested by plug-in</guilabel></term>
5737 14 Sep 11 nicklas 664           <listitem>
5737 14 Sep 11 nicklas 665             <para>
5737 14 Sep 11 nicklas 666               To make it easier for the server administrator
5737 14 Sep 11 nicklas 667               to assign permissions, the plug-in developer can
5737 14 Sep 11 nicklas 668               let the plug-in include a list of permissions that
5737 14 Sep 11 nicklas 669               are needed. Plug-in developers are advised to
5737 14 Sep 11 nicklas 670               only include the minimal set of permissions that are
5737 14 Sep 11 nicklas 671               required for the plug-in to function. Click on the 
5737 14 Sep 11 nicklas 672               <guibutton>Use requested permissions</guibutton>
5737 14 Sep 11 nicklas 673               button to give the plug-in the requested permissions.
5737 14 Sep 11 nicklas 674             </para>
5737 14 Sep 11 nicklas 675           </listitem>
5737 14 Sep 11 nicklas 676         </varlistentry>
5737 14 Sep 11 nicklas 677         </variablelist>
5737 14 Sep 11 nicklas 678       
5737 14 Sep 11 nicklas 679         <seeother>
5737 14 Sep 11 nicklas 680           <other external_id="plugindefinition.edit">Plug-in properties</other>
5737 14 Sep 11 nicklas 681           <other external_id="plugindefinition.jobagents">Job agents</other>
5737 14 Sep 11 nicklas 682           <other external_id="role.edit.permissions">Role permissions</other>
5737 14 Sep 11 nicklas 683         </seeother>    
5737 14 Sep 11 nicklas 684       </helptext>
5737 14 Sep 11 nicklas 685     
5737 14 Sep 11 nicklas 686     </sect2>
5737 14 Sep 11 nicklas 687
3329 11 May 07 nicklas 688   </sect1>
5737 14 Sep 11 nicklas 689
3329 11 May 07 nicklas 690   
3329 11 May 07 nicklas 691   <sect1 id="plugins.configuration">
3329 11 May 07 nicklas 692     <title>Plug-in configurations</title>
3329 11 May 07 nicklas 693
3329 11 May 07 nicklas 694     <para>
3329 11 May 07 nicklas 695       While some plug-ins work right out of the box, some
3329 11 May 07 nicklas 696       may require configuration before they can be used. For example,
3329 11 May 07 nicklas 697       most of the core import plug-ins need configurations in the
3329 11 May 07 nicklas 698       form of regular expressions to be able to find headers and
4441 03 Sep 08 jari 699       data in the data files and the Base1PluginExecuter uses
4441 03 Sep 08 jari 700       configurations to store information about the BASE version 1 plug-ins.
3329 11 May 07 nicklas 701     </para>
3329 11 May 07 nicklas 702
3329 11 May 07 nicklas 703     <para>
3329 11 May 07 nicklas 704       Configurations are managed from a plug-in's single-item view page
3329 11 May 07 nicklas 705       or from the
3329 11 May 07 nicklas 706       <menuchoice>
3329 11 May 07 nicklas 707         <guimenu>Administrate</guimenu>
5737 14 Sep 11 nicklas 708         <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
5737 14 Sep 11 nicklas 709         <guimenuitem>Plug-in configurations</guimenuitem>
3329 11 May 07 nicklas 710       </menuchoice>
5737 14 Sep 11 nicklas 711       page or from the single-item view page of each plug-in.
3329 11 May 07 nicklas 712     </para>
3329 11 May 07 nicklas 713     
3329 11 May 07 nicklas 714     <para>
3394 28 May 07 martin 715       Click on the &gbNew; button
3329 11 May 07 nicklas 716       to create a new configuration.
3329 11 May 07 nicklas 717     </para>
3329 11 May 07 nicklas 718     
3329 11 May 07 nicklas 719     <figure id="plugins.figures.configuration">
3329 11 May 07 nicklas 720       <title>Create plug-in configuration</title>
3329 11 May 07 nicklas 721       <screenshot>
3329 11 May 07 nicklas 722         <mediaobject>
3329 11 May 07 nicklas 723           <imageobject><imagedata 
3329 11 May 07 nicklas 724             fileref="figures/plugin_configuration.png" format="PNG"
3329 11 May 07 nicklas 725             /></imageobject>
3329 11 May 07 nicklas 726         </mediaobject>
3329 11 May 07 nicklas 727       </screenshot>
3329 11 May 07 nicklas 728     </figure>
3329 11 May 07 nicklas 729     
3329 11 May 07 nicklas 730     <helptext external_id="pluginconfiguration.edit" 
3329 11 May 07 nicklas 731       title="Edit plugin configuration">
3329 11 May 07 nicklas 732       
3329 11 May 07 nicklas 733       <variablelist>
3329 11 May 07 nicklas 734       <varlistentry>
3329 11 May 07 nicklas 735         <term><guilabel>Plugin</guilabel></term>
3329 11 May 07 nicklas 736         <listitem>
3329 11 May 07 nicklas 737           <para>
3487 13 Jun 07 peter 738             The plug-in this configuration belongs to. This cannot
3329 11 May 07 nicklas 739             be changed for existing configurations. Use the
3329 11 May 07 nicklas 740             <guibutton>Select&hellip;</guibutton> button
4441 03 Sep 08 jari 741             to open a pop-up window where you can select a plug-in.
3329 11 May 07 nicklas 742           </para>
3329 11 May 07 nicklas 743         </listitem>
3329 11 May 07 nicklas 744       </varlistentry>
3329 11 May 07 nicklas 745       <varlistentry>
3329 11 May 07 nicklas 746         <term><guilabel>Name</guilabel></term>
3329 11 May 07 nicklas 747         <listitem>
3329 11 May 07 nicklas 748           <para>
3329 11 May 07 nicklas 749             The name of the configuration.
3329 11 May 07 nicklas 750           </para>
3329 11 May 07 nicklas 751         </listitem>
3329 11 May 07 nicklas 752       </varlistentry>
3329 11 May 07 nicklas 753       <varlistentry>
3329 11 May 07 nicklas 754         <term><guilabel>Description</guilabel></term>
3329 11 May 07 nicklas 755         <listitem>
3329 11 May 07 nicklas 756           <para>
3329 11 May 07 nicklas 757             A description of the configuration (optional).
3329 11 May 07 nicklas 758           </para>
3329 11 May 07 nicklas 759         </listitem>
3329 11 May 07 nicklas 760       </varlistentry>
3329 11 May 07 nicklas 761       </variablelist>
3329 11 May 07 nicklas 762       
3329 11 May 07 nicklas 763       <note>
3487 13 Jun 07 peter 764         You cannot create configurations for plug-ins that
3487 13 Jun 07 peter 765         does not support being configured.
3329 11 May 07 nicklas 766       </note>
3329 11 May 07 nicklas 767     
3329 11 May 07 nicklas 768       <para>
3394 28 May 07 martin 769         Use the &gbSave; button to save the
3329 11 May 07 nicklas 770         configuration or the <guibutton>Save and configure</guibutton>
3329 11 May 07 nicklas 771         button to save and then start the configuration wizard.
3329 11 May 07 nicklas 772       </para>
3329 11 May 07 nicklas 773     
3329 11 May 07 nicklas 774     </helptext>
3329 11 May 07 nicklas 775     
3329 11 May 07 nicklas 776     <sect2 id="plugins.configuration.wizard">
3329 11 May 07 nicklas 777       <title>Configuring plug-in configurations</title>
3329 11 May 07 nicklas 778
3329 11 May 07 nicklas 779       <helptext external_id="runplugin.configure"
3329 11 May 07 nicklas 780         title="The plug-in configuration wizard">
3329 11 May 07 nicklas 781       
3329 11 May 07 nicklas 782       <para>
3329 11 May 07 nicklas 783         Configuring a plug-in is done with a wizard-like 
3329 11 May 07 nicklas 784         interface. Since the configuration parameters may vary
3329 11 May 07 nicklas 785         from plug-in to plug-in BASE uses a generic interface
3329 11 May 07 nicklas 786         to enter parameter values. In short, it works like this:
3329 11 May 07 nicklas 787         
3329 11 May 07 nicklas 788         <orderedlist>
3329 11 May 07 nicklas 789           <listitem>
3329 11 May 07 nicklas 790             <para>
3329 11 May 07 nicklas 791               BASE asks the plug-in for information about 
3329 11 May 07 nicklas 792               the parameters the plug-in needs. For example,
3329 11 May 07 nicklas 793               if the value is a string or number or should be
3329 11 May 07 nicklas 794               selected among a list of predefined values.
3329 11 May 07 nicklas 795             </para>
3329 11 May 07 nicklas 796           </listitem>
3329 11 May 07 nicklas 797           
3329 11 May 07 nicklas 798           <listitem>
3329 11 May 07 nicklas 799             <para>
3329 11 May 07 nicklas 800               BASE uses this information to create a generic form
3329 11 May 07 nicklas 801               for entering the values. The form consists of three
3329 11 May 07 nicklas 802               parts:
3329 11 May 07 nicklas 803               
3329 11 May 07 nicklas 804               <nohelp>
3329 11 May 07 nicklas 805               <figure id="plugins.figures.wizard">
3329 11 May 07 nicklas 806                 <title>The plug-in configuration wizard</title>
3329 11 May 07 nicklas 807                 <screenshot>
3329 11 May 07 nicklas 808                   <mediaobject>
3329 11 May 07 nicklas 809                     <imageobject><imagedata 
3329 11 May 07 nicklas 810                       fileref="figures/plugin_wizard.png" format="PNG"
3329 11 May 07 nicklas 811                       /></imageobject>
3329 11 May 07 nicklas 812                   </mediaobject>
3329 11 May 07 nicklas 813                 </screenshot>
3329 11 May 07 nicklas 814               </figure>
3329 11 May 07 nicklas 815               </nohelp>
3329 11 May 07 nicklas 816               
3329 11 May 07 nicklas 817               <itemizedlist>
3329 11 May 07 nicklas 818               <listitem>
3329 11 May 07 nicklas 819                 <para>
3329 11 May 07 nicklas 820                 <emphasis>The top part</emphasis>: Displays
3329 11 May 07 nicklas 821                 the name of the selected plug-in and configuration.
3329 11 May 07 nicklas 822                 </para>
3329 11 May 07 nicklas 823               </listitem>
3329 11 May 07 nicklas 824               
3329 11 May 07 nicklas 825               <listitem>
3329 11 May 07 nicklas 826                 <para>
3329 11 May 07 nicklas 827                 <emphasis>The left part</emphasis>: Displays
3329 11 May 07 nicklas 828                 a list of all parameters supported by the plug-in.
3329 11 May 07 nicklas 829                 Parameters with an <guilabel>X</guilabel> in front
3329 11 May 07 nicklas 830                 of their names already have a value. Parameters
3329 11 May 07 nicklas 831                 marked with a blue rectangle are required and
3329 11 May 07 nicklas 832                 must be given a value before it is possible to
3329 11 May 07 nicklas 833                 proceed.
3329 11 May 07 nicklas 834                 </para>
3329 11 May 07 nicklas 835               </listitem>
3329 11 May 07 nicklas 836               
3329 11 May 07 nicklas 837               <listitem>
3329 11 May 07 nicklas 838                 <para>
3329 11 May 07 nicklas 839                 <emphasis>The right part</emphasis>: Click on a parameter
3329 11 May 07 nicklas 840                 in the list to display a form for entering values for
3329 11 May 07 nicklas 841                 that parameter. The form may be a simple free text field,
3329 11 May 07 nicklas 842                 a list of checkboxes or radiobuttons, or something else
3329 11 May 07 nicklas 843                 depending on the kind of values supported by that
3329 11 May 07 nicklas 844                 parameter.
3329 11 May 07 nicklas 845                 </para>
3329 11 May 07 nicklas 846               </listitem>
3329 11 May 07 nicklas 847               </itemizedlist> 
3329 11 May 07 nicklas 848               
3329 11 May 07 nicklas 849             </para>
3329 11 May 07 nicklas 850           </listitem>
3329 11 May 07 nicklas 851
3329 11 May 07 nicklas 852           <listitem>
3329 11 May 07 nicklas 853             <para>
3394 28 May 07 martin 854               When the user clicks &gbNext;
3329 11 May 07 nicklas 855               the entered values are sent to the plug-in which 
3329 11 May 07 nicklas 856               validate the correctness. The plug-in may return
3329 11 May 07 nicklas 857               three different replies:
3329 11 May 07 nicklas 858               
3329 11 May 07 nicklas 859               <itemizedlist>
3329 11 May 07 nicklas 860               <listitem>
3329 11 May 07 nicklas 861                 <para>
3329 11 May 07 nicklas 862                 <emphasis>ERROR</emphasis>:
3329 11 May 07 nicklas 863                 There is an error in the input. BASE will redisplay
3329 11 May 07 nicklas 864                 the same form with any additional error information that
3329 11 May 07 nicklas 865                 the plug-in sends back.
3329 11 May 07 nicklas 866                 </para>
3329 11 May 07 nicklas 867               </listitem>
3329 11 May 07 nicklas 868               <listitem>
3329 11 May 07 nicklas 869                 <para>
3329 11 May 07 nicklas 870                 <emphasis>DONE</emphasis>:
3686 20 Aug 07 jari 871                 All parameter values are okay and no more values
3329 11 May 07 nicklas 872                 are needed. BASE will save the values to the database
3329 11 May 07 nicklas 873                 and finish the configuration wizard.
3329 11 May 07 nicklas 874                 </para>
3329 11 May 07 nicklas 875               </listitem>
3329 11 May 07 nicklas 876               <listitem>
3329 11 May 07 nicklas 877                 <para>
3329 11 May 07 nicklas 878                 <emphasis>CONTINUE</emphasis>:
3686 20 Aug 07 jari 879                 All parameter values are okay, but the plug-in
3329 11 May 07 nicklas 880                 wants more parameters. The procedure is repeated from the
3329 11 May 07 nicklas 881                 first step.
3329 11 May 07 nicklas 882                 </para>
3329 11 May 07 nicklas 883               </listitem>
3329 11 May 07 nicklas 884               </itemizedlist>
3329 11 May 07 nicklas 885             </para>
3329 11 May 07 nicklas 886           </listitem>
3329 11 May 07 nicklas 887           
3329 11 May 07 nicklas 888         </orderedlist>
3329 11 May 07 nicklas 889       </para>
3329 11 May 07 nicklas 890
3329 11 May 07 nicklas 891       <note>
3487 13 Jun 07 peter 892         <title>Do not go back</title>
5737 14 Sep 11 nicklas 893         <para>
3329 11 May 07 nicklas 894         It is not possible to go backwards in the wizard.
3329 11 May 07 nicklas 895         If you try it will most likely result in an
3329 11 May 07 nicklas 896         unexpected error and the configuration must be restarted
3329 11 May 07 nicklas 897         from the beginning.
5737 14 Sep 11 nicklas 898         </para>
3329 11 May 07 nicklas 899       </note>
3329 11 May 07 nicklas 900       
3329 11 May 07 nicklas 901       <seeother>
3329 11 May 07 nicklas 902         <other external_id="runplugin.configure.import">Common parameter for import plug-ins</other>
3329 11 May 07 nicklas 903         <other external_id="runplugin.configure.export">Common parameter for export plug-ins</other>
3329 11 May 07 nicklas 904         <other external_id="runplugin.configure.analysis">Common parameter for analysis plug-ins</other>
3329 11 May 07 nicklas 905       </seeother>
3329 11 May 07 nicklas 906       </helptext>
3329 11 May 07 nicklas 907       
3329 11 May 07 nicklas 908     </sect2>
3329 11 May 07 nicklas 909
3339 15 May 07 nicklas 910     <sect2 id="plugins.configuration.importexport">
3339 15 May 07 nicklas 911       <title>Importing and exporting plug-in configurations</title>
3339 15 May 07 nicklas 912       <para>
3339 15 May 07 nicklas 913         BASE ships with one importer and one exporter that allows
3339 15 May 07 nicklas 914         you to import and export plug-in configurations. This makes
5737 14 Sep 11 nicklas 915         it easy to copy configurations between servers.
3339 15 May 07 nicklas 916       </para>
3339 15 May 07 nicklas 917       
3339 15 May 07 nicklas 918       <para>
3339 15 May 07 nicklas 919         Both the import and the export is started from the plug-in 
3339 15 May 07 nicklas 920         configuration list view: 
3339 15 May 07 nicklas 921         <menuchoice>
3339 15 May 07 nicklas 922           <guimenu>Administrate</guimenu>
5737 14 Sep 11 nicklas 923           <guisubmenu>Plug-ins &amp; extensions</guisubmenu>
5737 14 Sep 11 nicklas 924           <guimenuitem>Plug-in configurations</guimenuitem>
3339 15 May 07 nicklas 925         </menuchoice>
3339 15 May 07 nicklas 926       </para>
3339 15 May 07 nicklas 927       
3339 15 May 07 nicklas 928       <para>
3740 17 Sep 07 martin 929         The importer supports auto detection. Simply upload and select the XML file with the
3740 17 Sep 07 martin 930         configurations. No more parameters are needed. 
3339 15 May 07 nicklas 931       </para>
3339 15 May 07 nicklas 932       
3339 15 May 07 nicklas 933       <para>
3740 17 Sep 07 martin 934         If you don't want to import all
3740 17 Sep 07 martin 935         configurations that exist in the XML-file, there is an option that lets you select
3740 17 Sep 07 martin 936         each configuration individually. When the option to import all configurations is set
3740 17 Sep 07 martin 937         to FALSE in the first step of job-configuration, the following step after pressing
3740 17 Sep 07 martin 938         <guibutton>Next</guibutton>
3740 17 Sep 07 martin 939         will be to select those configurations that should be imported, otherwise this step
3740 17 Sep 07 martin 940         is skipped.
3740 17 Sep 07 martin 941       </para>
3740 17 Sep 07 martin 942
3740 17 Sep 07 martin 943
3740 17 Sep 07 martin 944       <para>
3339 15 May 07 nicklas 945         To use the exporter you must first select the configurations
3686 20 Aug 07 jari 946         that should be exported in the list. Then, enter a path and file name
3339 15 May 07 nicklas 947         if you wish to leave the XML file on the BASE server or leave it
3339 15 May 07 nicklas 948         empty to download it immediately.
3339 15 May 07 nicklas 949       </para>
3339 15 May 07 nicklas 950       
3339 15 May 07 nicklas 951       <note>
3339 15 May 07 nicklas 952         The import and export only supports simple values, such as strings,
3487 13 Jun 07 peter 953         numbers, etc. It does not support configuration values that reference
3374 24 May 07 jari 954         other items. If the plug-in has such values they must be fixed
3374 24 May 07 jari 955         manually after the import.
3339 15 May 07 nicklas 956       </note>
3339 15 May 07 nicklas 957       
3329 11 May 07 nicklas 958     </sect2>
3329 11 May 07 nicklas 959
3329 11 May 07 nicklas 960     <sect2 id="plugins.configuration.testwithfile">
3329 11 May 07 nicklas 961       <title>The <guilabel>Test with file</guilabel> function</title>
3329 11 May 07 nicklas 962       
3339 15 May 07 nicklas 963       <para>
3345 16 May 07 martin 964         The <guilabel>Test with file</guilabel> function is a very useful
3339 15 May 07 nicklas 965         function for specifying import file formats. It is supported by
3339 15 May 07 nicklas 966         many of the import plug-ins that read data from a simple text 
3339 15 May 07 nicklas 967         file. This includes the raw data importer, the reporter importer,
3339 15 May 07 nicklas 968         plate reporter, etc.
3339 15 May 07 nicklas 969       </para>
3339 15 May 07 nicklas 970
3339 15 May 07 nicklas 971       <note>
3339 15 May 07 nicklas 972         The <guilabel>Test with file</guilabel> function can only
3339 15 May 07 nicklas 973         be used with simple (tab- or comma-separated) text files.
3487 13 Jun 07 peter 974         It does not work with XML files or binary files. The text file
3339 15 May 07 nicklas 975         may have headers in the beginning.
3339 15 May 07 nicklas 976       </note>
3339 15 May 07 nicklas 977       
3339 15 May 07 nicklas 978       <para>
3339 15 May 07 nicklas 979         As you can see in figure <xref linkend="plugins.figures.wizard"/>
3339 15 May 07 nicklas 980         there is a <guibutton>Test with file</guibutton> button. This
3339 15 May 07 nicklas 981         will appear in the file format setup step for all plug-ins that
3339 15 May 07 nicklas 982         support the test with file function. For detailed technical 
3339 15 May 07 nicklas 983         information about this see <xref linkend="plugin_developer.import" />
3339 15 May 07 nicklas 984         in <xref linkend="plugin_developer" />. Clicking on the 
3339 15 May 07 nicklas 985         <guibutton>Test with file</guibutton> button opens the following dialog:
3339 15 May 07 nicklas 986       </para>
3339 15 May 07 nicklas 987       
3339 15 May 07 nicklas 988       <figure id="plugins.figures.testwithfile">
3339 15 May 07 nicklas 989         <title>The test with file function</title>
3339 15 May 07 nicklas 990         <screenshot>
3339 15 May 07 nicklas 991           <mediaobject>
3339 15 May 07 nicklas 992             <imageobject><imagedata 
3423 31 May 07 nicklas 993               scalefit="1" width="100%"
3339 15 May 07 nicklas 994               fileref="figures/test_with_file.png" format="PNG"
3339 15 May 07 nicklas 995               /></imageobject>
3339 15 May 07 nicklas 996           </mediaobject>
3339 15 May 07 nicklas 997         </screenshot>
3339 15 May 07 nicklas 998       </figure>
3339 15 May 07 nicklas 999       
3339 15 May 07 nicklas 1000       <helptext external_id="runplugin.testwithfile" 
3339 15 May 07 nicklas 1001         title="Test with file">
3339 15 May 07 nicklas 1002         
3339 15 May 07 nicklas 1003       <para>
3339 15 May 07 nicklas 1004         The window consists of two parts, the upper part where the file 
3345 16 May 07 martin 1005         to parse and the parameters used to parse it are entered, and 
3339 15 May 07 nicklas 1006         the lower part that displays information about the parsing.
3339 15 May 07 nicklas 1007       </para>
3339 15 May 07 nicklas 1008         
3339 15 May 07 nicklas 1009       <variablelist>
3339 15 May 07 nicklas 1010       <varlistentry>
3339 15 May 07 nicklas 1011         <term><guilabel>File to test</guilabel></term>
3339 15 May 07 nicklas 1012         <listitem>
3339 15 May 07 nicklas 1013           <para>
3686 20 Aug 07 jari 1014             The path and file name of the file to use for testing.
3394 28 May 07 martin 1015             Use the &gbBrowse; button to 
3339 15 May 07 nicklas 1016             select a file from the BASE file system or upload
3339 15 May 07 nicklas 1017             a new file. Click on the <guibutton>Parse the file</guibutton>
3339 15 May 07 nicklas 1018             button to start parsing. The lower part will update itself with
3339 15 May 07 nicklas 1019             information about the parsed file. The file must follow a few simple rules:
3339 15 May 07 nicklas 1020             
3339 15 May 07 nicklas 1021             <itemizedlist>
3339 15 May 07 nicklas 1022             <listitem>
3339 15 May 07 nicklas 1023               <para>Data must be organised into columns, with one record per line.</para>
3339 15 May 07 nicklas 1024             </listitem>
3339 15 May 07 nicklas 1025             <listitem>
3339 15 May 07 nicklas 1026               <para>
3339 15 May 07 nicklas 1027                 Each data column must be separated by some special character or 
3345 16 May 07 martin 1028                 character sequence not occurring in the data, for example a tab or a comma. 
3339 15 May 07 nicklas 1029                 Data in fixed-size columns cannot be parsed.
3339 15 May 07 nicklas 1030               </para>
3339 15 May 07 nicklas 1031             </listitem>
3339 15 May 07 nicklas 1032             <listitem>
3339 15 May 07 nicklas 1033               <para>
3345 16 May 07 martin 1034                 Data may optionally be preceded by a data header, for example,
3339 15 May 07 nicklas 1035                 the names of the columns.
3339 15 May 07 nicklas 1036               </para>
3339 15 May 07 nicklas 1037             </listitem>
3339 15 May 07 nicklas 1038             <listitem>
3339 15 May 07 nicklas 1039               <para>
3345 16 May 07 martin 1040                 The data header may optionally be preceded by file headers. 
3339 15 May 07 nicklas 1041                 A file header is something that can be split into a name-value pair.
3339 15 May 07 nicklas 1042               </para>
3339 15 May 07 nicklas 1043             </listitem>
3339 15 May 07 nicklas 1044             <listitem>
3339 15 May 07 nicklas 1045               <para>
3339 15 May 07 nicklas 1046                 The file may contain comments, which are ignored by the parser.
3339 15 May 07 nicklas 1047               </para>
3339 15 May 07 nicklas 1048             </listitem>
3339 15 May 07 nicklas 1049             </itemizedlist>
3339 15 May 07 nicklas 1050           </para>
3339 15 May 07 nicklas 1051         </listitem>
3339 15 May 07 nicklas 1052       </varlistentry>
3339 15 May 07 nicklas 1053       <varlistentry>
3339 15 May 07 nicklas 1054         <term><guilabel>Lines to parse</guilabel></term>
3339 15 May 07 nicklas 1055         <listitem>
3339 15 May 07 nicklas 1056           <para>
4441 03 Sep 08 jari 1057             The number of lines to parse. The default is 100 and
4441 03 Sep 08 jari 1058             rarely needs to be changed. One reason to increase the
4441 03 Sep 08 jari 1059             number is when the data header line is beyond the default
4441 03 Sep 08 jari 1060             value.
3339 15 May 07 nicklas 1061           </para>
3339 15 May 07 nicklas 1062         </listitem>
3339 15 May 07 nicklas 1063       </varlistentry>
3339 15 May 07 nicklas 1064       <varlistentry>
4419 27 Aug 08 nicklas 1065         <term><guilabel>Character set</guilabel></term>
3339 15 May 07 nicklas 1066         <listitem>
3339 15 May 07 nicklas 1067           <para>
4419 27 Aug 08 nicklas 1068             The character set used in the file. The default 
4419 27 Aug 08 nicklas 1069             is ISO-8859-1 (same as Latin-1). This list contains all character sets 
4441 03 Sep 08 jari 1070             supported by the underlying Java run-time and can be quite long.
3339 15 May 07 nicklas 1071           </para>
3339 15 May 07 nicklas 1072         </listitem>
3339 15 May 07 nicklas 1073       </varlistentry>
3339 15 May 07 nicklas 1074       <varlistentry>
3339 15 May 07 nicklas 1075         <term><guilabel>Header regexp</guilabel></term>
3339 15 May 07 nicklas 1076         <listitem>
3339 15 May 07 nicklas 1077           <para>
3339 15 May 07 nicklas 1078             A regular expression matching a header line. A header
3339 15 May 07 nicklas 1079             is a key-value pair with information about the
3339 15 May 07 nicklas 1080             data in the file. The regular expression must contain two capturing groups, 
3339 15 May 07 nicklas 1081             the first should capture the name and the second the value of the header. 
3339 15 May 07 nicklas 1082             For example, the file contains headers like:
3339 15 May 07 nicklas 1083 <screen>
3339 15 May 07 nicklas 1084 "Type=GenePix Results 3"
3339 15 May 07 nicklas 1085 "DateTime=2006/05/16 13:17:59"
3339 15 May 07 nicklas 1086 </screen>
3339 15 May 07 nicklas 1087             To match this we can use the following regular expression: 
3339 15 May 07 nicklas 1088             <userinput>"(.*)=(.*)"</userinput>.
3339 15 May 07 nicklas 1089           </para>
3339 15 May 07 nicklas 1090           
3339 15 May 07 nicklas 1091           <para>
3394 28 May 07 martin 1092             Use the &gbPredefined; button to select from a
3339 15 May 07 nicklas 1093             list of common regular expressions.
3339 15 May 07 nicklas 1094           </para>
3339 15 May 07 nicklas 1095           
3339 15 May 07 nicklas 1096         </listitem>
3339 15 May 07 nicklas 1097       </varlistentry>
3339 15 May 07 nicklas 1098       
3339 15 May 07 nicklas 1099       <varlistentry>
3339 15 May 07 nicklas 1100         <term><guilabel>Data splitter regexp</guilabel></term>
3339 15 May 07 nicklas 1101         <listitem>
3339 15 May 07 nicklas 1102           <para>
3339 15 May 07 nicklas 1103             A regular expression used to split a data line into columns. For
3339 15 May 07 nicklas 1104             example, <userinput>\t</userinput> to split on tabs. Use 
3394 28 May 07 martin 1105             &gbPredefined; button to select from a list of 
3339 15 May 07 nicklas 1106             common regular expressions.
3339 15 May 07 nicklas 1107           </para>
3339 15 May 07 nicklas 1108         </listitem>
3339 15 May 07 nicklas 1109       </varlistentry>
3339 15 May 07 nicklas 1110       
3339 15 May 07 nicklas 1111       <varlistentry>
3339 15 May 07 nicklas 1112         <term><guilabel>Ignore regexp</guilabel></term>
3339 15 May 07 nicklas 1113         <listitem>
3339 15 May 07 nicklas 1114           <para>
3339 15 May 07 nicklas 1115             A regular expression that matches all lines that should be ignored.
3339 15 May 07 nicklas 1116             For example, <userinput>\#.*</userinput> to ignore all lines starting with 
3339 15 May 07 nicklas 1117             a #. Use 
3394 28 May 07 martin 1118             &gbPredefined; button to select from a list of 
3339 15 May 07 nicklas 1119             common regular expressions.
3339 15 May 07 nicklas 1120           </para>
3339 15 May 07 nicklas 1121         </listitem>
3339 15 May 07 nicklas 1122       </varlistentry>
3339 15 May 07 nicklas 1123       
3339 15 May 07 nicklas 1124       <varlistentry>
3339 15 May 07 nicklas 1125         <term><guilabel>Data header regexp</guilabel></term>
3339 15 May 07 nicklas 1126         <listitem>
3339 15 May 07 nicklas 1127           <para>
3339 15 May 07 nicklas 1128             A regular expression that matches the line containing the data header.
3339 15 May 07 nicklas 1129             Usually the data header contains the column names separated with the
3339 15 May 07 nicklas 1130             same separator as the data. For example, the file contains a header
3339 15 May 07 nicklas 1131             like:
3339 15 May 07 nicklas 1132 <screen>
3339 15 May 07 nicklas 1133 "Block"{tab}"Column"{tab}"Row"{tab}"Name"{tab}"ID" ...and so on
3339 15 May 07 nicklas 1134 </screen>
3339 15 May 07 nicklas 1135             To match this we can use the following regular expression: 
3339 15 May 07 nicklas 1136             <userinput>"Block"\t"Column"\t"Row"\t"Name"\t"ID".*</userinput>.
3339 15 May 07 nicklas 1137           </para>
3339 15 May 07 nicklas 1138           
3339 15 May 07 nicklas 1139           <para>
3339 15 May 07 nicklas 1140             The easiest way to set this regular is expression is to leave it empty
3339 15 May 07 nicklas 1141             to start with, click on the <guibutton>Parse the file</guibutton> button.
4441 03 Sep 08 jari 1142             Then, in the <guilabel>File data</guilabel> tab, use the drop-down lists 
3339 15 May 07 nicklas 1143             in the <guilabel>Use as</guilabel> column to select the line containing the
3339 15 May 07 nicklas 1144             data header. BASE will automatically generate a regular expression matching 
3339 15 May 07 nicklas 1145             the line.
3339 15 May 07 nicklas 1146           </para>
3339 15 May 07 nicklas 1147         </listitem>
3339 15 May 07 nicklas 1148       </varlistentry>
3339 15 May 07 nicklas 1149
3339 15 May 07 nicklas 1150       <varlistentry>
3339 15 May 07 nicklas 1151         <term><guilabel>Date footer regexp</guilabel></term>
3339 15 May 07 nicklas 1152         <listitem>
3339 15 May 07 nicklas 1153           <para>
3339 15 May 07 nicklas 1154             A regular expression that matches the first line of non-data after
3339 15 May 07 nicklas 1155             all data lines. In most cases you can leave this empty.
3339 15 May 07 nicklas 1156           </para>
3339 15 May 07 nicklas 1157         </listitem>
3339 15 May 07 nicklas 1158       </varlistentry>
3339 15 May 07 nicklas 1159
3339 15 May 07 nicklas 1160       <varlistentry>
3339 15 May 07 nicklas 1161         <term><guilabel>Min and max data columns</guilabel></term>
3339 15 May 07 nicklas 1162         <listitem>
3339 15 May 07 nicklas 1163           <para>
3339 15 May 07 nicklas 1164             If you specify values a data line is ignored if the number of
3487 13 Jun 07 peter 1165             columns does not fall within the range. If your data file does not have
3339 15 May 07 nicklas 1166             a data header with column names you can use these settings to find the
3339 15 May 07 nicklas 1167             start of data.
3339 15 May 07 nicklas 1168           </para>
3339 15 May 07 nicklas 1169         </listitem>
3339 15 May 07 nicklas 1170       </varlistentry>
3339 15 May 07 nicklas 1171       <varlistentry>
3339 15 May 07 nicklas 1172         <term><guilabel>Remove quotes</guilabel></term>
3339 15 May 07 nicklas 1173         <listitem>
3339 15 May 07 nicklas 1174           <para>
3339 15 May 07 nicklas 1175             If enabled, the parser will remove quotes around data entries.
3339 15 May 07 nicklas 1176           </para>
3339 15 May 07 nicklas 1177         </listitem>
3339 15 May 07 nicklas 1178       </varlistentry>
3339 15 May 07 nicklas 1179   
3339 15 May 07 nicklas 1180       <varlistentry>
3339 15 May 07 nicklas 1181         <term><guilabel>File data</guilabel></term>
3339 15 May 07 nicklas 1182         <listitem>
3339 15 May 07 nicklas 1183           <para>
3339 15 May 07 nicklas 1184             Press the <guilabel>Parse the file</guilabel> button
3339 15 May 07 nicklas 1185             to start parsing the file. This tab will be updated with the data
3339 15 May 07 nicklas 1186             from the file, organised as a table. For each line the following information
3339 15 May 07 nicklas 1187             is displayed:
3339 15 May 07 nicklas 1188             <itemizedlist>
3339 15 May 07 nicklas 1189             <listitem>
3339 15 May 07 nicklas 1190               <para>
3339 15 May 07 nicklas 1191               <emphasis>Line</emphasis>: The line number in the file
3339 15 May 07 nicklas 1192               </para>
3339 15 May 07 nicklas 1193             </listitem>
3339 15 May 07 nicklas 1194
3339 15 May 07 nicklas 1195             <listitem>
3339 15 May 07 nicklas 1196               <para>
3339 15 May 07 nicklas 1197               <emphasis>Columns</emphasis>: The number of columns the line could be
3339 15 May 07 nicklas 1198               split into with the data splitter regular expression.
3339 15 May 07 nicklas 1199               </para>
3339 15 May 07 nicklas 1200             </listitem>
3339 15 May 07 nicklas 1201
3339 15 May 07 nicklas 1202             <listitem>
3339 15 May 07 nicklas 1203               <para>
3339 15 May 07 nicklas 1204               <emphasis>Type</emphasis>: The type of line as detected by the parser.
3339 15 May 07 nicklas 1205               It should be one of the following: <emphasis>Unknown</emphasis>,
3339 15 May 07 nicklas 1206               <emphasis>Header</emphasis>, <emphasis>Data header</emphasis>,
3339 15 May 07 nicklas 1207               <emphasis>Data</emphasis> or <emphasis>Data footer</emphasis>.
3339 15 May 07 nicklas 1208               </para>
3339 15 May 07 nicklas 1209             </listitem>
3339 15 May 07 nicklas 1210             
3339 15 May 07 nicklas 1211             <listitem>
3339 15 May 07 nicklas 1212               <para>
4441 03 Sep 08 jari 1213               <emphasis>Use as</emphasis>: Use the drop-down lists to use a
3339 15 May 07 nicklas 1214               line as either the data header or data footer. BASE will automatically
3339 15 May 07 nicklas 1215               generate a regular expression.
3339 15 May 07 nicklas 1216               </para>
3339 15 May 07 nicklas 1217             </listitem>
3339 15 May 07 nicklas 1218             
3339 15 May 07 nicklas 1219             <listitem>
3339 15 May 07 nicklas 1220               <para>
3339 15 May 07 nicklas 1221               <emphasis>File data</emphasis>: The contents of the file after
3339 15 May 07 nicklas 1222               splitting and, optionally, removal of quotes.
3339 15 May 07 nicklas 1223               </para>
3339 15 May 07 nicklas 1224             </listitem>
3339 15 May 07 nicklas 1225             </itemizedlist>
3339 15 May 07 nicklas 1226             
3339 15 May 07 nicklas 1227           </para>
3339 15 May 07 nicklas 1228         </listitem>
3339 15 May 07 nicklas 1229       </varlistentry>
3339 15 May 07 nicklas 1230       <varlistentry>
3339 15 May 07 nicklas 1231         <term><guilabel>Column mappings</guilabel></term>
3339 15 May 07 nicklas 1232         <listitem>
3339 15 May 07 nicklas 1233           <para>
4441 03 Sep 08 jari 1234             After defining the data header you may need to press
4441 03 Sep 08 jari 1235             the <guilabel>Parse the file</guilabel> button to make
4441 03 Sep 08 jari 1236             this tab visible because this tab is only displayed when
4441 03 Sep 08 jari 1237             data has been found in the file and a data header was
4441 03 Sep 08 jari 1238             recognized. It allows you to easily select the mapping
4441 03 Sep 08 jari 1239             between columns in the file and the properties in the
4441 03 Sep 08 jari 1240             database.
3339 15 May 07 nicklas 1241           </para>
3339 15 May 07 nicklas 1242           <nohelp>
3339 15 May 07 nicklas 1243           <figure id="plugins.figures.testwithfilemappings">
3339 15 May 07 nicklas 1244             <title>Mapping columns from a file</title>
3339 15 May 07 nicklas 1245             <screenshot>
3339 15 May 07 nicklas 1246               <mediaobject>
3339 15 May 07 nicklas 1247                 <imageobject><imagedata 
3943 09 Nov 07 nicklas 1248                   scalefit="1" width="100%"
3339 15 May 07 nicklas 1249                   fileref="figures/test_with_file_mappings.png" format="PNG"
3339 15 May 07 nicklas 1250                   /></imageobject>
3339 15 May 07 nicklas 1251               </mediaobject>
3339 15 May 07 nicklas 1252             </screenshot>
3339 15 May 07 nicklas 1253           </figure>
3339 15 May 07 nicklas 1254           </nohelp>
3339 15 May 07 nicklas 1255           
3339 15 May 07 nicklas 1256           <itemizedlist>
3339 15 May 07 nicklas 1257           <listitem>
3339 15 May 07 nicklas 1258             <para>
3339 15 May 07 nicklas 1259               <emphasis>Mapping style</emphasis>: The type
3339 15 May 07 nicklas 1260               of mapping to use when you pick a column from the 
3339 15 May 07 nicklas 1261               <emphasis>File columns</emphasis> list boxes.
3339 15 May 07 nicklas 1262             </para>
3339 15 May 07 nicklas 1263           </listitem>
3339 15 May 07 nicklas 1264           
3339 15 May 07 nicklas 1265           <listitem>
3339 15 May 07 nicklas 1266             <para>
3339 15 May 07 nicklas 1267               <emphasis>Property</emphasis>: The database property.
3339 15 May 07 nicklas 1268             </para>
3339 15 May 07 nicklas 1269           </listitem>
3339 15 May 07 nicklas 1270
3339 15 May 07 nicklas 1271           <listitem>
3339 15 May 07 nicklas 1272             <para>
3339 15 May 07 nicklas 1273               <emphasis>Mapping expression</emphasis>: An expression that
3339 15 May 07 nicklas 1274               maps the data in the file columns to the property in the 
3339 15 May 07 nicklas 1275               database. There are two types of mappings, simple and expressions.
3339 15 May 07 nicklas 1276               A simple mapping is a string template with placeholders for data
3339 15 May 07 nicklas 1277               from the file. An expression mapping starts with an equal sign and
3339 15 May 07 nicklas 1278               is evaluated dynamically for each line of data.  The simple
3339 15 May 07 nicklas 1279               mapping has better performance and we recommend that you use
3339 15 May 07 nicklas 1280               it unless you have to recalculate any of the numerical values.
3911 06 Nov 07 nicklas 1281               In both cases, if no column matching the placeholder exactly is found 
3911 06 Nov 07 nicklas 1282               the placeholder is interpreted as a regular expression that
3911 06 Nov 07 nicklas 1283               is matched against each column. The first one found is used.
4441 03 Sep 08 jari 1284               A few mapping examples are listed in
4441 03 Sep 08 jari 1285               <xref linkend="plugins.configuration.testwithfile.mappings"
4441 03 Sep 08 jari 1286               />.
3339 15 May 07 nicklas 1287             </para>
4441 03 Sep 08 jari 1288
4441 03 Sep 08 jari 1289             <table frame="all" id="plugins.configuration.testwithfile.mappings">
4441 03 Sep 08 jari 1290               <title>Mapping expression examples</title>
5801 12 Oct 11 nicklas 1291               <tgroup cols="2" align="center">
5801 12 Oct 11 nicklas 1292                 <colspec colname="expression" align="left"/>
5801 12 Oct 11 nicklas 1293                 <colspec colname="explanation" align="left"/>
4441 03 Sep 08 jari 1294                 <thead>
4441 03 Sep 08 jari 1295                   <row>
4441 03 Sep 08 jari 1296                     <entry>
4441 03 Sep 08 jari 1297                       Expression
4441 03 Sep 08 jari 1298                     </entry>
4441 03 Sep 08 jari 1299                     <entry>
4441 03 Sep 08 jari 1300                       Explanation
4441 03 Sep 08 jari 1301                     </entry>
4441 03 Sep 08 jari 1302                   </row>
4441 03 Sep 08 jari 1303                 </thead>
4441 03 Sep 08 jari 1304                 <tbody>
4441 03 Sep 08 jari 1305                   <row>
4441 03 Sep 08 jari 1306                     <entry>
4441 03 Sep 08 jari 1307                       <constant>\Name\</constant>
4441 03 Sep 08 jari 1308                     </entry>
4441 03 Sep 08 jari 1309                     <entry>
4441 03 Sep 08 jari 1310                       Exact match is required.
4441 03 Sep 08 jari 1311                     </entry>
4441 03 Sep 08 jari 1312                   </row>
4441 03 Sep 08 jari 1313                   <row>
4441 03 Sep 08 jari 1314                     <entry>
4441 03 Sep 08 jari 1315                       <constant>\1\</constant>
4441 03 Sep 08 jari 1316                     </entry>
4441 03 Sep 08 jari 1317                     <entry>
4441 03 Sep 08 jari 1318                       Column with index 1 (the second column).
4441 03 Sep 08 jari 1319                     </entry>
4441 03 Sep 08 jari 1320                   </row>
4441 03 Sep 08 jari 1321                   <row>
4441 03 Sep 08 jari 1322                     <entry>
4441 03 Sep 08 jari 1323                       <constant>[\row\, \column\]</constant>
4441 03 Sep 08 jari 1324                     </entry>
4441 03 Sep 08 jari 1325                     <entry>
4441 03 Sep 08 jari 1326                       Combining row and column to a single coordinate.
4441 03 Sep 08 jari 1327                     </entry>
4441 03 Sep 08 jari 1328                   </row>
4441 03 Sep 08 jari 1329                   <row>
4441 03 Sep 08 jari 1330                     <entry>
4441 03 Sep 08 jari 1331                       <constant>=2 * col('radius')</constant>
4441 03 Sep 08 jari 1332                     </entry>
4441 03 Sep 08 jari 1333                     <entry>
4441 03 Sep 08 jari 1334                       Calculate the diameter dynamically.
4441 03 Sep 08 jari 1335                     </entry>
4441 03 Sep 08 jari 1336                   </row>
4441 03 Sep 08 jari 1337                   <row>
4441 03 Sep 08 jari 1338                     <entry>
4441 03 Sep 08 jari 1339                       <constant>\F63(3|5) Median\</constant>
4441 03 Sep 08 jari 1340                     </entry>
4441 03 Sep 08 jari 1341                     <entry>
4441 03 Sep 08 jari 1342                       Use regular expression to match either F633 or
4441 03 Sep 08 jari 1343                       F635.
4441 03 Sep 08 jari 1344                     </entry>
4441 03 Sep 08 jari 1345                   </row>
4441 03 Sep 08 jari 1346                   <row>
4441 03 Sep 08 jari 1347                     <entry>
4441 03 Sep 08 jari 1348                       <constant>constant_string</constant>
4441 03 Sep 08 jari 1349                     </entry>
4441 03 Sep 08 jari 1350                     <entry>
4441 03 Sep 08 jari 1351                       Use <constant>constant_string</constant> as
4441 03 Sep 08 jari 1352                       value for this column for each line.
4441 03 Sep 08 jari 1353                     </entry>
4441 03 Sep 08 jari 1354                   </row>
4441 03 Sep 08 jari 1355                 </tbody>
4441 03 Sep 08 jari 1356               </tgroup>
4441 03 Sep 08 jari 1357             </table>
3339 15 May 07 nicklas 1358             
3339 15 May 07 nicklas 1359             <note>
3339 15 May 07 nicklas 1360               Column numbers are 0-based. We recommend that you use 
3339 15 May 07 nicklas 1361               column names at all times if they are present in the
3339 15 May 07 nicklas 1362               file.
3339 15 May 07 nicklas 1363             </note>
3339 15 May 07 nicklas 1364           </listitem>
3339 15 May 07 nicklas 1365           
3339 15 May 07 nicklas 1366           <listitem>
3339 15 May 07 nicklas 1367             <para>
4419 27 Aug 08 nicklas 1368               <emphasis>Auto generate</emphasis>: Click on this button to
4419 27 Aug 08 nicklas 1369               let BASE try to automatically generate mappings based on 
4419 27 Aug 08 nicklas 1370               fuzzy string matching between the property names and file
4419 27 Aug 08 nicklas 1371               column headers. Each match get a score between 0 and 1
4441 03 Sep 08 jari 1372               where 1 indicates a better match. Use the <emphasis>similarity
4419 27 Aug 08 nicklas 1373               score</emphasis> to limit the automatically generated mappings to
4419 27 Aug 08 nicklas 1374               matches with at least the given score. A value between 0.7 and 0.9
4419 27 Aug 08 nicklas 1375               is usually a good choice.
4419 27 Aug 08 nicklas 1376             </para>
4419 27 Aug 08 nicklas 1377           </listitem>
4419 27 Aug 08 nicklas 1378           
4419 27 Aug 08 nicklas 1379           <listitem>
4419 27 Aug 08 nicklas 1380             <para>
3339 15 May 07 nicklas 1381               <emphasis>File columns</emphasis>: Lists of column found in the file.
3339 15 May 07 nicklas 1382               Select a value from this list to let BASE automatically
3339 15 May 07 nicklas 1383               generate a mapping that picks the selected column.
3339 15 May 07 nicklas 1384             </para>
3339 15 May 07 nicklas 1385           </listitem>
3339 15 May 07 nicklas 1386           </itemizedlist>
3339 15 May 07 nicklas 1387         </listitem>
3339 15 May 07 nicklas 1388       </varlistentry>
3339 15 May 07 nicklas 1389       </variablelist>      
3339 15 May 07 nicklas 1390       
3339 15 May 07 nicklas 1391       </helptext>
3339 15 May 07 nicklas 1392       
3339 15 May 07 nicklas 1393       
3329 11 May 07 nicklas 1394     </sect2>
5178 02 Nov 09 jari 1395
3329 11 May 07 nicklas 1396   </sect1>
3329 11 May 07 nicklas 1397   
3329 11 May 07 nicklas 1398
3374 24 May 07 jari 1399 </chapter>