Context Navigation

plugin_installation.xml @ 3911

Visit:

Last change on this file since 3911 was 3911, checked in by Nicklas Nordborg, 15 years ago

Fixes #811: Wildcard or regular expressions in raw data column mappings

To be consistent with exact name matching the first column found is always returned

Property svn:eol-style set to native
Property svn:keywords set to Id

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

Note: See TracBrowser for help on using the repository browser.

Context Navigation

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

Download in other formats: