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

Last change on this file since 3866 was 3866, checked in by Nicklas Nordborg, 14 years ago

References #364: Support for automatic install of non-core plugins

Fixed some issues in the documentation.

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