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

Last change on this file since 3753 was 3753, checked in by Martin Svensson, 15 years ago

References #364, documentation

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