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

Last change on this file since 3339 was 3339, checked in by Nicklas Nordborg, 16 years ago

References #548: Write "Installing plug-ins" section

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