source: trunk/doc/src/docbook/admindoc/plugin_installation.xml @ 3765

Last change on this file since 3765 was 3765, checked in by Martin Svensson, 14 years ago

References #364, Correct inconsistent variable/property 'plugin.dir' becomes 'plugins.dir'

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