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

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

Fixes #548

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