Changeset 3339 for trunk/doc/src/docbook/admindoc/plugin_installation.xml
- Timestamp:
- May 15, 2007, 1:13:14 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/admindoc/plugin_installation.xml
r3329 r3339 103 103 104 104 <helptext external_id="plugindefinition.edit" 105 title=" Edit plugin">105 title="Plug-in properties"> 106 106 107 107 <variablelist> … … 232 232 233 233 <seeother> 234 <other external_id="plugindefinition.edit.permissions">Plugin permissions</other> 234 <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other> 235 <other external_id="plugindefinition.jobagents">Job agents</other> 235 236 </seeother> 236 237 … … 240 241 <sect2 id="plugins.installation.base1"> 241 242 <title>BASE 1 plug-ins</title> 242 <para>TODO</para> 243 <para> 244 BASE 1 plug-ins are supported by BASE 2 through the use of 245 the <emphasis>BASE 1 plug-in executer</emphasis> plug-in. This 246 is itself a plug-in and BASE 1 plug-ins are added as configurations 247 to this plug-in. See <xref linkend="plugins.configuration" />. To 248 install a BASE 1 plug-in to BASE 2 follow these instructions: 249 </para> 250 251 <orderedlist> 252 <listitem> 253 <para> 254 Install the BASE 1 plug-in executable and any 255 other files needed by it on the BASE server. Check the documentation 256 for the plug-in for information about what is needed. 257 </para> 258 </listitem> 259 260 <listitem> 261 <para> 262 Upload the <filename>*.base</filename> file for the BASE 1 plug-in 263 to BASE 2. If you can't the file, you can let BASE 1 create one for you. 264 In your BASE 1 installation go to 265 <menuchoice> 266 <guimenu>Analyze data</guimenu> 267 <guimenuitem>Plug-ins</guimenuitem> 268 </menuchoice> 269 and use the <guilabel>Export</guilabel> function. This will create a 270 configuration file for your BASE 1 plug-in that you can upload to BASE 2. 271 </para> 272 </listitem> 273 274 <listitem> 275 <para> 276 Create a new plug-in configuration in BASE 2 using, for example, 277 the <guibutton>New configuration</guibutton> button 278 in single-item view for the <emphasis>BASE 1 plug-in executer</emphasis> 279 plug-in. 280 </para> 281 </listitem> 282 283 <listitem> 284 <para> 285 Start the configuration wizard and select the <filename>*.base</filename> 286 file describing the BASE 1 plug-in and enter the path and 287 filename to the location of the executable. 288 </para> 289 </listitem> 290 291 <listitem> 292 <para> 293 To check that the new plug-in works correctly, you need 294 to have an experiment with some data. Go to the single-item 295 view for a bioassayset and click on the <guibutton>Run analysis</guibutton> 296 button. Select the <emphasis>Base1PluginExecutor</emphasis> 297 plug-in. The list of configurations should include the newly 298 installed plug-in. Select it and click on <guibutton>Next</guibutton>. 299 </para> 300 </listitem> 301 302 <listitem> 303 <para> 304 This will enter regular plug-in execution wizard and you 305 will have to enter paraters needed by the plug-in. 306 </para> 307 </listitem> 308 309 </orderedlist> 310 311 243 312 </sect2> 244 313 … … 355 424 356 425 <seeother> 357 <other external_id="plugindefinition.edit">Plugin properties</other> 426 <other external_id="plugindefinition.edit">Plug-in properties</other> 427 <other external_id="plugindefinition.jobagents">Job agents</other> 358 428 <other external_id="role.edit.permissions">Role permissions</other> 359 429 </seeother> … … 367 437 <title>Job agents</title> 368 438 <para> 369 TODO - see also <xref linkend="installation_upgrade.jobagents" />. 439 Job agents are used for executing plug-ins on external servers. This is a good 440 way to free up the web server so that it can concentrate on serving web pages. 441 Job agents are optional and must be installed separately. See 442 <xref linkend="installation_upgrade.jobagents" /> for more information about this. 443 The standard BASE installation doesn't include any job agents. 444 The rest of this section assumes that you have installed at least one job agent. 370 445 </para> 371 446 372 447 <para> 448 A job agent will not execute a plug-in unless the admin has configured 449 told the job agent to do so. This can be done either from the plug-in 450 side or from the job agent side. To register a plug-in with one or more 451 job agents from the plug-in side go to the edit view the plug-in and 452 select the <guilabel>Job agents</guilabel> tab. To do the same from 453 the job agent side go to the edit view of the job agent and select 454 the <guilabel>Plugins</guilabel> tab. The two dialogs are very similar. 455 Here is the plug-in side of the registration, the job agent side is described 456 in <xref linkend="installation_upgrade.jobagents" />. 457 </para> 458 459 <figure id="plugins.figures.jobagents"> 460 <title>Select job agents for a plug-in</title> 461 <screenshot> 462 <mediaobject> 463 <imageobject><imagedata 464 fileref="figures/plugin_jobagents.png" format="PNG" 465 /></imageobject> 466 </mediaobject> 467 </screenshot> 468 </figure> 469 470 <helptext external_id="plugindefinition.jobagents" 471 title="Job agents"> 472 473 <para> 474 Use this tab to specify which job agents the plug-in is 475 installed and allowed to be executed on. 476 </para> 477 478 <variablelist> 479 <varlistentry> 480 <term><guilabel>Run this plugin on</guilabel></term> 481 <listitem> 482 <para> 483 A list with the job agents where the plug-in is installed and 484 allowed to be executed. Select a plug-in in this list to display 485 more configuration options for the plug-in. 486 </para> 487 </listitem> 488 </varlistentry> 489 <varlistentry> 490 <term><guilabel>Add job agents</guilabel></term> 491 <listitem> 492 <para> 493 Use this button to open a popup window for selecting 494 job agents. 495 </para> 496 </listitem> 497 </varlistentry> 498 <varlistentry> 499 <term><guilabel>Remove</guilabel></term> 500 <listitem> 501 <para> 502 Remove the selected plug-in from the list. 503 </para> 504 </listitem> 505 </varlistentry> 506 </variablelist> 507 508 <para> 509 The following properties are only displayed when a 510 job agent has been selected in the list. Each job agent may have it's 511 own settings of these properties. If you leave the values unspecified 512 the job agent will use the default values specified on the 513 <guilabel>Plugin</guilabel> tab. 514 </para> 515 516 <variablelist> 517 <varlistentry> 518 <term><guilabel>Jar path</guilabel></term> 519 <listitem> 520 <para> 521 The path on the external server to the JAR file containing the 522 plug-in code. If not specified the same path as on the web server 523 is used. 524 </para> 525 </listitem> 526 </varlistentry> 527 <varlistentry> 528 <term><guilabel>Max memory</guilabel></term> 529 <listitem> 530 <para> 531 The maximum amount of memory the plug-in is allowed to use. 532 Add around 40MB for the Java runtime environment and BASE. 533 If not specified Java will choose it's default value which is 64MB. 534 </para> 535 </listitem> 536 </varlistentry> 537 <varlistentry> 538 <term><guilabel>Trusted</guilabel></term> 539 <listitem> 540 <para> 541 If the plug-in should be executed in a protected or 542 unprotected environment. Currently, BASE only supports 543 running plug-ins in an unprotected environment. 544 </para> 545 </listitem> 546 </varlistentry> 547 <varlistentry> 548 <term><guilabel>Priority boost</guilabel></term> 549 <listitem> 550 <para> 551 Used to give a plug-in higher priority in the queue. 552 Values between 0 and 10 are allowed. A higher value will 553 give the plug-in higher priority. The priority boost is useful 554 if we, for example, want to use one server mainly for importing 555 data. By giving all import plugins a priority boost they will 556 be executed before all other jobs, which will have to wait 557 until there are no more waiting imports. 558 </para> 559 </listitem> 560 </varlistentry> 561 </variablelist> 562 563 <seeother> 564 <other external_id="plugindefinition.edit">Plug-in properties</other> 565 <other external_id="plugindefinition.edit.permissions">Plug-in permissions</other> 566 </seeother> 567 </helptext> 373 568 </sect1> 374 375 569 376 570 <sect1 id="plugins.configuration"> … … 591 785 </sect2> 592 786 593 <sect2 id="plugins.configuration.core"> 594 <title>Core plug-in configurations</title> 787 <sect2 id="plugins.configuration.importexport"> 788 <title>Importing and exporting plug-in configurations</title> 789 <para> 790 BASE ships with one importer and one exporter that allows 791 you to import and export plug-in configurations. This makes 792 it easy to copy configurations between servers. The BASE website 793 also has a <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html" 794 >page where you can download additional configurations</ulink> 795 not included in the main distribution. 796 </para> 797 798 <para> 799 Both the import and the export is started from the plug-in 800 configuration list view: 801 <menuchoice> 802 <guimenu>Administrate</guimenu> 803 <guisubmenu>Plugins</guisubmenu> 804 <guimenuitem>Configurations</guimenuitem> 805 </menuchoice> 806 </para> 807 808 <para> 809 The importer supports auto detection. Simply upload and select the 810 XML file with the configurations. No more parameters are needed. 811 </para> 812 813 <para> 814 To use the exporter you must first select the configurations 815 that should be exported in the list. Then, enter a path and filename 816 if you wish to leave the XML file on the BASE server or leave it 817 empty to download it immediately. 818 </para> 819 820 <note> 821 The import and export only supports simple values, such as strings, 822 numbers, etc. It doesn't support configuration values that reference 823 other items. If the plug-in has such values they must be fixed by 824 hand after the import. 825 </note> 826 595 827 </sect2> 596 828 597 598 829 <sect2 id="plugins.configuration.testwithfile"> 599 830 <title>The <guilabel>Test with file</guilabel> function</title> 831 832 <para> 833 The <guilabel>Test with file</guilabel> function is avery useful 834 function for specifying import file formats. It is supported by 835 many of the import plug-ins that read data from a simple text 836 file. This includes the raw data importer, the reporter importer, 837 plate reporter, etc. 838 </para> 839 840 <note> 841 The <guilabel>Test with file</guilabel> function can only 842 be used with simple (tab- or comma-separated) text files. 843 It doesn't work with XML files or binary files. The text file 844 may have headers in the beginning. 845 </note> 846 847 <para> 848 As you can see in figure <xref linkend="plugins.figures.wizard"/> 849 there is a <guibutton>Test with file</guibutton> button. This 850 will appear in the file format setup step for all plug-ins that 851 support the test with file function. For detailed technical 852 information about this see <xref linkend="plugin_developer.import" /> 853 in <xref linkend="plugin_developer" />. Clicking on the 854 <guibutton>Test with file</guibutton> button opens the following dialog: 855 </para> 856 857 <figure id="plugins.figures.testwithfile"> 858 <title>The test with file function</title> 859 <screenshot> 860 <mediaobject> 861 <imageobject><imagedata 862 fileref="figures/test_with_file.png" format="PNG" 863 /></imageobject> 864 </mediaobject> 865 </screenshot> 866 </figure> 867 868 <helptext external_id="runplugin.testwithfile" 869 title="Test with file"> 870 871 <para> 872 The window consists of two parts, the upper part where the file 873 to parse and the parmeters used to parse it are entered, and 874 the lower part that displays information about the parsing. 875 </para> 876 877 <variablelist> 878 <varlistentry> 879 <term><guilabel>File to test</guilabel></term> 880 <listitem> 881 <para> 882 The path and filename of the file to use for testing. 883 Use the <guibutton>Browse</guibutton> button to 884 select a file from the BASE file system or upload 885 a new file. Click on the <guibutton>Parse the file</guibutton> 886 button to start parsing. The lower part will update itself with 887 information about the parsed file. The file must follow a few simple rules: 888 889 <itemizedlist> 890 <listitem> 891 <para>Data must be organised into columns, with one record per line.</para> 892 </listitem> 893 <listitem> 894 <para> 895 Each data column must be separated by some special character or 896 character sequence not occuring in the data, for example a tab or a comma. 897 Data in fixed-size columns cannot be parsed. 898 </para> 899 </listitem> 900 <listitem> 901 <para> 902 Data may optionally be preceeded by a data header, for example, 903 the names of the columns. 904 </para> 905 </listitem> 906 <listitem> 907 <para> 908 The data header may optionally be preceeded by file headers. 909 A file header is something that can be split into a name-value pair. 910 </para> 911 </listitem> 912 <listitem> 913 <para> 914 The file may contain comments, which are ignored by the parser. 915 </para> 916 </listitem> 917 </itemizedlist> 918 </para> 919 </listitem> 920 </varlistentry> 921 <varlistentry> 922 <term><guilabel>Lines to parse</guilabel></term> 923 <listitem> 924 <para> 925 The number of lines to parse. The default is 100. 926 </para> 927 </listitem> 928 </varlistentry> 929 <varlistentry> 930 <term><guilabel>Encoding</guilabel></term> 931 <listitem> 932 <para> 933 The character encoding of the file. The default 934 is ISO-8859-1 (same as Latin-1). This list contains all encodings 935 supported by the underlying Java runtime and can be quite long. 936 </para> 937 </listitem> 938 </varlistentry> 939 <varlistentry> 940 <term><guilabel>Header regexp</guilabel></term> 941 <listitem> 942 <para> 943 A regular expression matching a header line. A header 944 is a key-value pair with information about the 945 data in the file. The regular expression must contain two capturing groups, 946 the first should capture the name and the second the value of the header. 947 For example, the file contains headers like: 948 <screen> 949 "Type=GenePix Results 3" 950 "DateTime=2006/05/16 13:17:59" 951 </screen> 952 To match this we can use the following regular expression: 953 <userinput>"(.*)=(.*)"</userinput>. 954 </para> 955 956 <para> 957 Use the <guibutton>Predefined</guibutton> button to select from a 958 list of common regular expressions. 959 </para> 960 961 </listitem> 962 </varlistentry> 963 964 <varlistentry> 965 <term><guilabel>Data splitter regexp</guilabel></term> 966 <listitem> 967 <para> 968 A regular expression used to split a data line into columns. For 969 example, <userinput>\t</userinput> to split on tabs. Use 970 <guibutton>Predefined</guibutton> button to select from a list of 971 common regular expressions. 972 </para> 973 </listitem> 974 </varlistentry> 975 976 <varlistentry> 977 <term><guilabel>Ignore regexp</guilabel></term> 978 <listitem> 979 <para> 980 A regular expression that matches all lines that should be ignored. 981 For example, <userinput>\#.*</userinput> to ignore all lines starting with 982 a #. Use 983 <guibutton>Predefined</guibutton> button to select from a list of 984 common regular expressions. 985 </para> 986 </listitem> 987 </varlistentry> 988 989 <varlistentry> 990 <term><guilabel>Data header regexp</guilabel></term> 991 <listitem> 992 <para> 993 A regular expression that matches the line containing the data header. 994 Usually the data header contains the column names separated with the 995 same separator as the data. For example, the file contains a header 996 like: 997 <screen> 998 "Block"{tab}"Column"{tab}"Row"{tab}"Name"{tab}"ID" ...and so on 999 </screen> 1000 To match this we can use the following regular expression: 1001 <userinput>"Block"\t"Column"\t"Row"\t"Name"\t"ID".*</userinput>. 1002 </para> 1003 1004 <para> 1005 The easiest way to set this regular is expression is to leave it empty 1006 to start with, click on the <guibutton>Parse the file</guibutton> button. 1007 Then, in the <guilabel>File data</guilabel> tab, use the dropdown lists 1008 in the <guilabel>Use as</guilabel> column to select the line containing the 1009 data header. BASE will automatically generate a regular expression matching 1010 the line. 1011 </para> 1012 </listitem> 1013 </varlistentry> 1014 1015 <varlistentry> 1016 <term><guilabel>Date footer regexp</guilabel></term> 1017 <listitem> 1018 <para> 1019 A regular expression that matches the first line of non-data after 1020 all data lines. In most cases you can leave this empty. 1021 </para> 1022 </listitem> 1023 </varlistentry> 1024 1025 <varlistentry> 1026 <term><guilabel>Min and max data columns</guilabel></term> 1027 <listitem> 1028 <para> 1029 If you specify values a data line is ignored if the number of 1030 columns doesn't fall within the range. If your data file doesn't have 1031 a data header with column names you can use these settings to find the 1032 start of data. 1033 </para> 1034 </listitem> 1035 </varlistentry> 1036 <varlistentry> 1037 <term><guilabel>Remove quotes</guilabel></term> 1038 <listitem> 1039 <para> 1040 If enabled, the parser will remove quotes around data entries. 1041 </para> 1042 </listitem> 1043 </varlistentry> 1044 1045 <varlistentry> 1046 <term><guilabel>File data</guilabel></term> 1047 <listitem> 1048 <para> 1049 Press the <guilabel>Parse the file</guilabel> button 1050 to start parsing the file. This tab will be updated with the data 1051 from the file, organised as a table. For each line the following information 1052 is displayed: 1053 <itemizedlist> 1054 <listitem> 1055 <para> 1056 <emphasis>Line</emphasis>: The line number in the file 1057 </para> 1058 </listitem> 1059 1060 <listitem> 1061 <para> 1062 <emphasis>Columns</emphasis>: The number of columns the line could be 1063 split into with the data splitter regular expression. 1064 </para> 1065 </listitem> 1066 1067 <listitem> 1068 <para> 1069 <emphasis>Type</emphasis>: The type of line as detected by the parser. 1070 It should be one of the following: <emphasis>Unknown</emphasis>, 1071 <emphasis>Header</emphasis>, <emphasis>Data header</emphasis>, 1072 <emphasis>Data</emphasis> or <emphasis>Data footer</emphasis>. 1073 </para> 1074 </listitem> 1075 1076 <listitem> 1077 <para> 1078 <emphasis>Use as</emphasis>: Use the dropdown lists to use a 1079 line as either the data header or data footer. BASE will automatically 1080 generate a regular expression. 1081 </para> 1082 </listitem> 1083 1084 <listitem> 1085 <para> 1086 <emphasis>File data</emphasis>: The contents of the file after 1087 splitting and, optionally, removal of quotes. 1088 </para> 1089 </listitem> 1090 </itemizedlist> 1091 1092 </para> 1093 </listitem> 1094 </varlistentry> 1095 <varlistentry> 1096 <term><guilabel>Column mappings</guilabel></term> 1097 <listitem> 1098 <para> 1099 This tab is only displayed if data has been found in the file and a 1100 data header is present. It allows you to easily select the mapping 1101 between columns in the file and the properties in the database. 1102 </para> 1103 <nohelp> 1104 <figure id="plugins.figures.testwithfilemappings"> 1105 <title>Mapping columns from a file</title> 1106 <screenshot> 1107 <mediaobject> 1108 <imageobject><imagedata 1109 fileref="figures/test_with_file_mappings.png" format="PNG" 1110 /></imageobject> 1111 </mediaobject> 1112 </screenshot> 1113 </figure> 1114 </nohelp> 1115 1116 <itemizedlist> 1117 <listitem> 1118 <para> 1119 <emphasis>Mapping style</emphasis>: The type 1120 of mapping to use when you pick a column from the 1121 <emphasis>File columns</emphasis> list boxes. 1122 </para> 1123 </listitem> 1124 1125 <listitem> 1126 <para> 1127 <emphasis>Property</emphasis>: The database property. 1128 </para> 1129 </listitem> 1130 1131 <listitem> 1132 <para> 1133 <emphasis>Mapping expression</emphasis>: An expression that 1134 maps the data in the file columns to the property in the 1135 database. There are two types of mappings, simple and expressions. 1136 A simple mapping is a string template with placeholders for data 1137 from the file. An expression mapping starts with an equal sign and 1138 is evaluated dynamically for each line of data. The simple 1139 mapping has better performance and we recommend that you use 1140 it unless you have to recalculate any of the numerical values. 1141 Here are a few mapping examples: 1142 </para> 1143 1144 <informalexample> 1145 <literallayout>\Name\ 1146 \1\ 1147 [\row\, \column\] 1148 =2 * col('radius') 1149 </literallayout> 1150 </informalexample> 1151 1152 <note> 1153 Column numbers are 0-based. We recommend that you use 1154 column names at all times if they are present in the 1155 file. 1156 </note> 1157 </listitem> 1158 1159 <listitem> 1160 <para> 1161 <emphasis>File columns</emphasis>: Lists of column found in the file. 1162 Select a value from this list to let BASE automatically 1163 generate a mapping that picks the selected column. 1164 </para> 1165 </listitem> 1166 </itemizedlist> 1167 </listitem> 1168 </varlistentry> 1169 </variablelist> 1170 1171 </helptext> 1172 600 1173 601 1174 </sect2>
Note: See TracChangeset
for help on using the changeset viewer.
