doc/src/docbook/user/import_data.xml

Code
Comments
Other
Rev Date Author Line
3157 05 Mar 07 martin 1 <?xml version="1.0" encoding="UTF-8"?>
3159 05 Mar 07 martin 2 <!DOCTYPE chapter PUBLIC 
3200 21 Mar 07 martin 3   "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
3314 09 May 07 nicklas 4   "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd" 
3314 09 May 07 nicklas 5 [
3314 09 May 07 nicklas 6 <!ENTITY runplugin.configure.common 
3314 09 May 07 nicklas 7   "The top of the window displays the names of the selected plug-in and
3314 09 May 07 nicklas 8   configuration, a list with parameters to the left, an area for input fields to the
3314 09 May 07 nicklas 9   right and buttons to proceed with at the bottom. 
3314 09 May 07 nicklas 10   Click on a parameter in the parameter list to show the form fields
3314 09 May 07 nicklas 11   for entering values for the parameter to the right. Parameters
3314 09 May 07 nicklas 12   with an <guilabel>X</guilabel> in front of their names already have a
3314 09 May 07 nicklas 13   value. Parameters marked with a blue rectangle are required and must
3314 09 May 07 nicklas 14   be given a value before it is possible to proceed."
3314 09 May 07 nicklas 15 >
3314 09 May 07 nicklas 16 ]>
3157 05 Mar 07 martin 17 <!--
3177 08 Mar 07 martin 18   $Id$
3165 06 Mar 07 martin 19   
3675 16 Aug 07 jari 20   Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
4889 06 Apr 09 nicklas 21   Copyright (C) 2008 Jari Häkkinen
3165 06 Mar 07 martin 22   
3157 05 Mar 07 martin 23   This file is part of BASE - BioArray Software Environment.
3157 05 Mar 07 martin 24   Available at http://base.thep.lu.se/
3165 06 Mar 07 martin 25   
3157 05 Mar 07 martin 26   BASE is free software; you can redistribute it and/or
3157 05 Mar 07 martin 27   modify it under the terms of the GNU General Public License
4477 05 Sep 08 jari 28   as published by the Free Software Foundation; either version 3
3157 05 Mar 07 martin 29   of the License, or (at your option) any later version.
3165 06 Mar 07 martin 30   
3157 05 Mar 07 martin 31   BASE is distributed in the hope that it will be useful,
3157 05 Mar 07 martin 32   but WITHOUT ANY WARRANTY; without even the implied warranty of
3157 05 Mar 07 martin 33   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
3157 05 Mar 07 martin 34   GNU General Public License for more details.
3165 06 Mar 07 martin 35   
3157 05 Mar 07 martin 36   You should have received a copy of the GNU General Public License
4509 11 Sep 08 jari 37   along with BASE. If not, see <http://www.gnu.org/licenses/>.
3157 05 Mar 07 martin 38 -->
4432 01 Sep 08 jari 39 <chapter id="import_data" chunked="0">
4432 01 Sep 08 jari 40   <title>Import of data</title>
3165 06 Mar 07 martin 41   <para>
3314 09 May 07 nicklas 42     In some places the only way to get data into BASE is to import it
5798 11 Oct 11 nicklas 43     from a file. This typically includes <emphasis>raw data</emphasis>, 
5798 11 Oct 11 nicklas 44     <emphasis>array design features</emphasis>, <emphasis>reporters</emphasis>
5798 11 Oct 11 nicklas 45     and other things, which would be inconvenient
4444 03 Sep 08 jari 46     to enter by hand due to the large number of data items. There is
4444 03 Sep 08 jari 47     also convenience batch importers for importing other items such as
5798 11 Oct 11 nicklas 48     <emphasis>biosources</emphasis>, <emphasis>samples</emphasis>, and 
5798 11 Oct 11 nicklas 49     <emphasis>annotations</emphasis>. The batch importers are
4444 03 Sep 08 jari 50     described later in this chapter after the general import
4444 03 Sep 08 jari 51     description.
3165 06 Mar 07 martin 52   </para>
3165 06 Mar 07 martin 53   <para>
4432 01 Sep 08 jari 54     Normally, a plug-in handles one type of items and may require a
5798 11 Oct 11 nicklas 55     configuration. For example, most import plug-ins need some
4444 03 Sep 08 jari 56     information about how to find headers and data lines in
5784 05 Oct 11 nicklas 57     files. BASE ships with a number of import plug-ins as a part of
4432 01 Sep 08 jari 58     the core plug-ins package, cf. <xref linkend="coreplugins.import"
4444 03 Sep 08 jari 59     />. The core plug-in section links to configuration examples for
4444 03 Sep 08 jari 60     some of the plugins. Go to
3200 21 Mar 07 martin 61     <menuchoice>
3200 21 Mar 07 martin 62       <guimenu>Administrate</guimenu>
5784 05 Oct 11 nicklas 63       <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
5784 05 Oct 11 nicklas 64       <guisubmenu>Plug-in definitions</guisubmenu>
3200 21 Mar 07 martin 65     </menuchoice>
4432 01 Sep 08 jari 66     to check which plug-ins are installed on your BASE server. When
4432 01 Sep 08 jari 67     BASE finds a plug-in that supports import of a certain type of
4432 01 Sep 08 jari 68     item an &gbImport; button is displayed in the toolbar on either
4432 01 Sep 08 jari 69     the list view or the single-item view.
3200 21 Mar 07 martin 70   </para>
4432 01 Sep 08 jari 71     <note>
5784 05 Oct 11 nicklas 72     <title>No "Import" button?</title>
3200 21 Mar 07 martin 73     <para>
4432 01 Sep 08 jari 74       If the import button is missing from a page were you would expect
3314 09 May 07 nicklas 75       to find them this usually means that:
3200 21 Mar 07 martin 76     </para>
3314 09 May 07 nicklas 77     <itemizedlist>
3314 09 May 07 nicklas 78       <listitem>
3314 09 May 07 nicklas 79         <simpara>
3487 13 Jun 07 peter 80           The logged in user does not have permission to use the plug-in.
3314 09 May 07 nicklas 81         </simpara>
3314 09 May 07 nicklas 82       </listitem>
3314 09 May 07 nicklas 83       <listitem>
3314 09 May 07 nicklas 84         <simpara>
3314 09 May 07 nicklas 85           The plug-in requires a configuration, but no one has been
3487 13 Jun 07 peter 86           created or the logged in user does not have permission to 
3314 09 May 07 nicklas 87           use any of the existing configurations.
3314 09 May 07 nicklas 88         </simpara>
3314 09 May 07 nicklas 89       </listitem>
3314 09 May 07 nicklas 90     </itemizedlist>
3314 09 May 07 nicklas 91     <para>
3314 09 May 07 nicklas 92       Contact the server administrator or a similar user that has permission to 
3314 09 May 07 nicklas 93       administrate the plug-ins.
3314 09 May 07 nicklas 94     </para>
3200 21 Mar 07 martin 95   </note>
3314 09 May 07 nicklas 96
4444 03 Sep 08 jari 97     <sect1 id="import_data.import">
4444 03 Sep 08 jari 98       <title>General import procedure</title>
4444 03 Sep 08 jari 99
3163 06 Mar 07 martin 100     <para>
3314 09 May 07 nicklas 101       Starting a data import is done by a wizard-like interface. There
3314 09 May 07 nicklas 102       are a number of step you have to go through:
3163 06 Mar 07 martin 103     </para>
3314 09 May 07 nicklas 104     
3314 09 May 07 nicklas 105     <orderedlist>
3314 09 May 07 nicklas 106       <listitem>
3314 09 May 07 nicklas 107         <simpara>
5798 11 Oct 11 nicklas 108           Select a plug-in and file format to use, or use the
5798 11 Oct 11 nicklas 109           <emphasis>auto detect</emphasis> option.
3314 09 May 07 nicklas 110         </simpara>
3314 09 May 07 nicklas 111       </listitem>
3314 09 May 07 nicklas 112       <listitem>
3314 09 May 07 nicklas 113         <simpara>
4444 03 Sep 08 jari 114           If you selected the auto detection function, you must select
3314 09 May 07 nicklas 115           a file to use.
3314 09 May 07 nicklas 116         </simpara>
3314 09 May 07 nicklas 117       </listitem>
3314 09 May 07 nicklas 118       <listitem>
3314 09 May 07 nicklas 119         <simpara>
3314 09 May 07 nicklas 120           Specify plug-in parameters.
3314 09 May 07 nicklas 121         </simpara>
3314 09 May 07 nicklas 122       </listitem>
3314 09 May 07 nicklas 123       <listitem>
3314 09 May 07 nicklas 124         <simpara>
3314 09 May 07 nicklas 125           Add the import job to the job queue.
3314 09 May 07 nicklas 126         </simpara>
3314 09 May 07 nicklas 127       </listitem>
3314 09 May 07 nicklas 128       <listitem>
3314 09 May 07 nicklas 129         <simpara>
3314 09 May 07 nicklas 130           Wait for the job to finish.
3314 09 May 07 nicklas 131         </simpara>
3314 09 May 07 nicklas 132       </listitem>
3314 09 May 07 nicklas 133     </orderedlist>
3200 21 Mar 07 martin 134
4444 03 Sep 08 jari 135     <sect2 id="import_export_data.import.plugin_fileformat">
3314 09 May 07 nicklas 136       <title>Select plug-in and file format</title>
3314 09 May 07 nicklas 137       <para>
3394 28 May 07 martin 138         Click on the &gbImport; button
3314 09 May 07 nicklas 139         in the toolbar to start the import wizard. The first step is to
3314 09 May 07 nicklas 140         select which plug-in and, if supported, which 
3314 09 May 07 nicklas 141         file format to use. There is also an <guilabel>auto detect</guilabel>
3314 09 May 07 nicklas 142         option that lets you select a file and have BASE try to find a suitable
3314 09 May 07 nicklas 143         plug-in/file format to use. 
3314 09 May 07 nicklas 144       </para>
3314 09 May 07 nicklas 145   
3314 09 May 07 nicklas 146       <figure id="import_export_data.figures.select_import_plugin">
3314 09 May 07 nicklas 147         <title>Select plug-in and file format</title>
3314 09 May 07 nicklas 148         <screenshot>
3314 09 May 07 nicklas 149           <mediaobject>
3314 09 May 07 nicklas 150             <imageobject><imagedata fileref="figures/select_import_plugin.png" format="PNG" /></imageobject>
3314 09 May 07 nicklas 151           </mediaobject>
3314 09 May 07 nicklas 152         </screenshot>
3314 09 May 07 nicklas 153       </figure>
3314 09 May 07 nicklas 154     
3314 09 May 07 nicklas 155
3200 21 Mar 07 martin 156       <helptext external_id="import.selectplugin"
3314 09 May 07 nicklas 157         title="Select plug-in and file format for data import">
3314 09 May 07 nicklas 158
3314 09 May 07 nicklas 159         <variablelist>
3314 09 May 07 nicklas 160           <varlistentry>
5372 24 Jun 10 nicklas 161             <term><guilabel>Plugin + file format</guilabel></term>
3314 09 May 07 nicklas 162             <listitem>
3314 09 May 07 nicklas 163               <para>
5372 24 Jun 10 nicklas 164                 This is a combined list of plug-ins and their 
5372 24 Jun 10 nicklas 165                 respective file format configurations. The list only 
5372 24 Jun 10 nicklas 166                 includes combinations that
3314 09 May 07 nicklas 167                 the logged in user has permission to use. If you select
5798 11 Oct 11 nicklas 168                 an entry a short description about the plug-in and configuration
5372 24 Jun 10 nicklas 169                 is displayed
3314 09 May 07 nicklas 170                 below the lists. More information about the plug-ins can
5372 24 Jun 10 nicklas 171                 be found under the menu choices
3314 09 May 07 nicklas 172                 <menuchoice>
3314 09 May 07 nicklas 173                   <guimenu>Administrate</guimenu>
5784 05 Oct 11 nicklas 174                   <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
5784 05 Oct 11 nicklas 175                   <guisubmenu>Plug-in definitions</guisubmenu>
3314 09 May 07 nicklas 176                 </menuchoice>
5372 24 Jun 10 nicklas 177                 and 
3314 09 May 07 nicklas 178                 <menuchoice>
3314 09 May 07 nicklas 179                   <guimenu>Administrate</guimenu>
5784 05 Oct 11 nicklas 180                   <guimenuitem>Plug-ins &amp; extensions</guimenuitem>
5784 05 Oct 11 nicklas 181                   <guisubmenu>Plug-in configuration</guisubmenu>
5784 05 Oct 11 nicklas 182                 </menuchoice>
3314 09 May 07 nicklas 183               </para>
3314 09 May 07 nicklas 184               <note>
3314 09 May 07 nicklas 185                 <title>File format vs. Configuration</title>
3314 09 May 07 nicklas 186                 <simpara>
3314 09 May 07 nicklas 187                 A file format is the same thing as a plug-in configuration.
3314 09 May 07 nicklas 188                 It may be confusing that the interface sometimes use
3314 09 May 07 nicklas 189                 <emphasis>file format</emphasis> and sometimes use 
3314 09 May 07 nicklas 190                 <emphasis>configuration</emphasis>, but for now, we'll have
3314 09 May 07 nicklas 191                 to live with it.
3314 09 May 07 nicklas 192                 </simpara>
3314 09 May 07 nicklas 193               </note>
3314 09 May 07 nicklas 194             </listitem>
3314 09 May 07 nicklas 195           </varlistentry>
3314 09 May 07 nicklas 196         </variablelist>
3314 09 May 07 nicklas 197
3163 06 Mar 07 martin 198         <para>
3314 09 May 07 nicklas 199           Proceed to the next step by clicking on the
3394 28 May 07 martin 200           &gbNext; button.
3177 08 Mar 07 martin 201         </para>
3200 21 Mar 07 martin 202
3314 09 May 07 nicklas 203         <seeother>
3314 09 May 07 nicklas 204           <other external_id="import.autodetect">The auto detect function</other>
3314 09 May 07 nicklas 205         </seeother>
3314 09 May 07 nicklas 206       </helptext>
3165 06 Mar 07 martin 207
3314 09 May 07 nicklas 208       <sect3 id="import_export_data.import.plugin_fileformat.autodetect">
3314 09 May 07 nicklas 209         <title>The auto detect function</title>
3314 09 May 07 nicklas 210         
3314 09 May 07 nicklas 211         <helptext
3314 09 May 07 nicklas 212           external_id="import.autodetect"
3314 09 May 07 nicklas 213           title="The auto detect function">
3314 09 May 07 nicklas 214         
3314 09 May 07 nicklas 215         <para>
3314 09 May 07 nicklas 216           The auto detect function lets you select a file and have
3314 09 May 07 nicklas 217           BASE try to find a suitable plug-in and file format. This option is
5372 24 Jun 10 nicklas 218           selected by default in the combined plug-in and file format list when there is
3314 09 May 07 nicklas 219           at least one plug-in that supports auto detection.
3314 09 May 07 nicklas 220         </para>
3314 09 May 07 nicklas 221         <note>
3314 09 May 07 nicklas 222           <title>Support of auto detect</title>
3177 08 Mar 07 martin 223           <para>
3314 09 May 07 nicklas 224             Not all plug-ins support auto detection. The ones that do are marked in
3314 09 May 07 nicklas 225             the list with <guilabel>×</guilabel>.
3177 08 Mar 07 martin 226           </para>
3314 09 May 07 nicklas 227         </note>
3314 09 May 07 nicklas 228         
3314 09 May 07 nicklas 229         <para>
5372 24 Jun 10 nicklas 230           Select the <guilabel>auto detect (all)</guilabel> option to search for a file format
5372 24 Jun 10 nicklas 231           in all plug-ins that supports the feature, or select the <guilabel>auto detect (plugin)</guilabel>
5372 24 Jun 10 nicklas 232           option to only search the file formats for a specific plug-in.
5372 24 Jun 10 nicklas 233           Continue to the next step by clicking on the &gbNext; button.
3314 09 May 07 nicklas 234         </para>
3314 09 May 07 nicklas 235         
3314 09 May 07 nicklas 236         <seeother>
3314 09 May 07 nicklas 237           <other external_id="import.selectplugin">Select plug-in and file format for data import</other>
3314 09 May 07 nicklas 238           <other external_id="import.autodetect.selectfile">Select file for auto detection</other>
3314 09 May 07 nicklas 239         </seeother>
3314 09 May 07 nicklas 240       
3314 09 May 07 nicklas 241         </helptext>
3314 09 May 07 nicklas 242         
3314 09 May 07 nicklas 243         <para>
3314 09 May 07 nicklas 244           You must now select a file to import from.
3314 09 May 07 nicklas 245         </para>
3314 09 May 07 nicklas 246         
3314 09 May 07 nicklas 247         <figure id="import_export_data.figures.select_autodetect_file">
3314 09 May 07 nicklas 248           <title>Select file for auto detection</title>
3314 09 May 07 nicklas 249           <screenshot>
3314 09 May 07 nicklas 250             <mediaobject>
3314 09 May 07 nicklas 251               <imageobject><imagedata fileref="figures/select_autodetect_file.png" format="PNG" /></imageobject>
3314 09 May 07 nicklas 252             </mediaobject>
3314 09 May 07 nicklas 253           </screenshot>
3314 09 May 07 nicklas 254         </figure>
3314 09 May 07 nicklas 255         
3314 09 May 07 nicklas 256         <helptext external_id="import.autodetect.selectfile" 
3314 09 May 07 nicklas 257           title="Select file for auto detection">
3314 09 May 07 nicklas 258   
3314 09 May 07 nicklas 259           <variablelist>
3314 09 May 07 nicklas 260             <varlistentry>
5372 24 Jun 10 nicklas 261               <term><guilabel>Plugin</guilabel></term>
5372 24 Jun 10 nicklas 262               <listitem>
5372 24 Jun 10 nicklas 263                 <para>
5798 11 Oct 11 nicklas 264                   Displays the selected plug-in or <guilabel>all</guilabel> if the 
5372 24 Jun 10 nicklas 265                   auto-detection is used on all supporting plug-ins.
5372 24 Jun 10 nicklas 266                 </para>
5372 24 Jun 10 nicklas 267               </listitem>
5372 24 Jun 10 nicklas 268             </varlistentry>
5372 24 Jun 10 nicklas 269             <varlistentry>
3314 09 May 07 nicklas 270               <term><guilabel>File</guilabel></term>
3314 09 May 07 nicklas 271               <listitem>
3314 09 May 07 nicklas 272                 <para>
4444 03 Sep 08 jari 273                   Enter the path and file name for the
3314 09 May 07 nicklas 274                   file you want to use. Use the <guibutton>Browse&hellip;</guibutton>
3314 09 May 07 nicklas 275                   button to browse after the file in BASE's file system. 
3487 13 Jun 07 peter 276                   If the file does not exist in the file system you have the option
3314 09 May 07 nicklas 277                   to upload it. 
3314 09 May 07 nicklas 278                   <nohelp>Read more about this in <xref linkend="file_system" />.</nohelp>
3314 09 May 07 nicklas 279                 </para>
3314 09 May 07 nicklas 280               </listitem>
3314 09 May 07 nicklas 281             </varlistentry>
3314 09 May 07 nicklas 282             <varlistentry>
5372 24 Jun 10 nicklas 283               <term><guilabel>Character set</guilabel></term>
5372 24 Jun 10 nicklas 284               <listitem>
5372 24 Jun 10 nicklas 285                 <para>
5372 24 Jun 10 nicklas 286                   The character set used in text files. If the selected file has been configured
5372 24 Jun 10 nicklas 287                   with a character set the correct option is automatically selected. In all 
5372 24 Jun 10 nicklas 288                   cases, you have the option to override the default selection. Most files,
5798 11 Oct 11 nicklas 289                   typically use either the UTF-8 or ISO-8859-1 character set.
5372 24 Jun 10 nicklas 290                 </para>
5372 24 Jun 10 nicklas 291               </listitem>
5372 24 Jun 10 nicklas 292             </varlistentry>
5372 24 Jun 10 nicklas 293             <varlistentry>
3314 09 May 07 nicklas 294               <term><guilabel>Recently used</guilabel></term>
3314 09 May 07 nicklas 295               <listitem>
3314 09 May 07 nicklas 296                 <para>
3314 09 May 07 nicklas 297                   A list of files you have recently used
3314 09 May 07 nicklas 298                   for auto detection.
3314 09 May 07 nicklas 299                 </para>
3314 09 May 07 nicklas 300               </listitem>
3314 09 May 07 nicklas 301             </varlistentry>
3314 09 May 07 nicklas 302           </variablelist>
3314 09 May 07 nicklas 303           
3200 21 Mar 07 martin 304           <para>
3394 28 May 07 martin 305             Click on the &gbNext; button
5784 05 Oct 11 nicklas 306             to start the auto detection. There are three possible outcomes:
3200 21 Mar 07 martin 307           </para>
3165 06 Mar 07 martin 308
5784 05 Oct 11 nicklas 309           <itemizedlist>
5784 05 Oct 11 nicklas 310             <listitem>
5784 05 Oct 11 nicklas 311               <para>
5784 05 Oct 11 nicklas 312               Exactly one matching plug-in and file format is found. The next step is
5784 05 Oct 11 nicklas 313               to configure any additional parameters needed
5784 05 Oct 11 nicklas 314               by the plug-in. This is the same step as if you had selected
5784 05 Oct 11 nicklas 315               the same plug-in and file format in the first step.
5784 05 Oct 11 nicklas 316               </para>
5784 05 Oct 11 nicklas 317             </listitem>
5784 05 Oct 11 nicklas 318             <listitem>
5784 05 Oct 11 nicklas 319               <para>
5784 05 Oct 11 nicklas 320               If no matching plug-in and file format is found an error message
5784 05 Oct 11 nicklas 321               is displayed. If logged in with enough permissions to do so there
5784 05 Oct 11 nicklas 322               is an option to create a new file format/configuration.
5784 05 Oct 11 nicklas 323               </para>
5784 05 Oct 11 nicklas 324             </listitem>
5784 05 Oct 11 nicklas 325             <listitem>
5784 05 Oct 11 nicklas 326               <para>
5784 05 Oct 11 nicklas 327               If multiple matching plug-ins and file formats are found 
3314 09 May 07 nicklas 328               you will be taken back to the first step. This time
3314 09 May 07 nicklas 329               the lists will only include the matching plug-ins/file formats
3314 09 May 07 nicklas 330               and the auto detect option is not present.
5784 05 Oct 11 nicklas 331               </para>
5784 05 Oct 11 nicklas 332             </listitem>
5784 05 Oct 11 nicklas 333           </itemizedlist>
3314 09 May 07 nicklas 334
3314 09 May 07 nicklas 335           <seeother>
3314 09 May 07 nicklas 336             <other external_id="import.selectplugin">Select plug-in and file format for data import</other>
3314 09 May 07 nicklas 337             <other external_id="import.autodetect">The auto detect function</other>
3314 09 May 07 nicklas 338           </seeother>
3314 09 May 07 nicklas 339           
3314 09 May 07 nicklas 340         </helptext>
3314 09 May 07 nicklas 341         
3314 09 May 07 nicklas 342       </sect3>
3314 09 May 07 nicklas 343
4444 03 Sep 08 jari 344     </sect2>
3314 09 May 07 nicklas 345
4444 03 Sep 08 jari 346     <sect2 id="import_export_data.import.pluginparameters">
3314 09 May 07 nicklas 347       <title>Specify plug-in parameters</title>
3314 09 May 07 nicklas 348       <para>
3314 09 May 07 nicklas 349         When you have selected a plug-in and file format or used
3314 09 May 07 nicklas 350         the auto detect function to find one, a form where you
3314 09 May 07 nicklas 351         you can enter additional parameters for the plug-in is displayed.
3314 09 May 07 nicklas 352       </para>
3314 09 May 07 nicklas 353       
5798 11 Oct 11 nicklas 354       <figure id="import_export_data.figures.configure_plugin">
3314 09 May 07 nicklas 355         <title>Specify plug-in parameters</title>
3314 09 May 07 nicklas 356         <screenshot>
3314 09 May 07 nicklas 357           <mediaobject>
3943 09 Nov 07 nicklas 358             <imageobject>
3943 09 Nov 07 nicklas 359               <imagedata 
3943 09 Nov 07 nicklas 360                 scalefit="1" width="100%"
3943 09 Nov 07 nicklas 361                 fileref="figures/plugin_parameters.png" format="PNG" />
3943 09 Nov 07 nicklas 362             </imageobject>
3314 09 May 07 nicklas 363           </mediaobject>
3314 09 May 07 nicklas 364         </screenshot>
3314 09 May 07 nicklas 365       </figure>
3314 09 May 07 nicklas 366       
3314 09 May 07 nicklas 367       <helptext external_id="runplugin.configure.import" 
3314 09 May 07 nicklas 368         title="Specify plug-in parameters">
3314 09 May 07 nicklas 369       <para>
3314 09 May 07 nicklas 370         &runplugin.configure.common;
3314 09 May 07 nicklas 371       </para>
3314 09 May 07 nicklas 372       
3314 09 May 07 nicklas 373       <para>
3314 09 May 07 nicklas 374         The parameter list is very different from plug-in to plug-in.
3314 09 May 07 nicklas 375         Common parameters for import plug-ins are:
3314 09 May 07 nicklas 376       </para>
3314 09 May 07 nicklas 377       
3314 09 May 07 nicklas 378       <variablelist>
3314 09 May 07 nicklas 379         <varlistentry>
3314 09 May 07 nicklas 380           <term><guilabel>File</guilabel></term>
3314 09 May 07 nicklas 381           <listitem>
3200 21 Mar 07 martin 382             <para>
3314 09 May 07 nicklas 383             The file to import data from. A value is already set if
3314 09 May 07 nicklas 384             you used the auto detect function.
3200 21 Mar 07 martin 385             </para>
3314 09 May 07 nicklas 386           </listitem>
3314 09 May 07 nicklas 387         </varlistentry>
3314 09 May 07 nicklas 388         
3314 09 May 07 nicklas 389         <varlistentry>
5798 11 Oct 11 nicklas 390           <term><guilabel>File parser regular expressions</guilabel></term>
5798 11 Oct 11 nicklas 391           <listitem>
5798 11 Oct 11 nicklas 392             <para>
5798 11 Oct 11 nicklas 393             Various regular expressions that are used when parsing the file
5798 11 Oct 11 nicklas 394             to ensure that the data is found. In most cases, all values
5798 11 Oct 11 nicklas 395             are taken from the matched configuration and can be left as is.
5798 11 Oct 11 nicklas 396             </para>
5798 11 Oct 11 nicklas 397           </listitem>
5798 11 Oct 11 nicklas 398         </varlistentry>
5798 11 Oct 11 nicklas 399         
5798 11 Oct 11 nicklas 400         <varlistentry>
3314 09 May 07 nicklas 401           <term><guilabel>Error handling</guilabel></term>
3314 09 May 07 nicklas 402           <listitem>
3314 09 May 07 nicklas 403             <para>
3314 09 May 07 nicklas 404               A section which contains different options how to
3314 09 May 07 nicklas 405               handle errors when parsing the file. Normally you can
5784 05 Oct 11 nicklas 406               select if the import should fail as a whole or if
5784 05 Oct 11 nicklas 407               only the line with the error should be skipped.
3314 09 May 07 nicklas 408             </para>
3314 09 May 07 nicklas 409           </listitem>
3314 09 May 07 nicklas 410         </varlistentry>
3314 09 May 07 nicklas 411       </variablelist>
3314 09 May 07 nicklas 412       
3314 09 May 07 nicklas 413       <para>
3314 09 May 07 nicklas 414         Continue to the next step by clicking the 
3394 28 May 07 martin 415         &gbNext; button.
3314 09 May 07 nicklas 416       </para>
3329 11 May 07 nicklas 417       
3329 11 May 07 nicklas 418       <seeother>
3329 11 May 07 nicklas 419         <other external_id="runplugin.configure">The plug-in configuration wizard</other>
3329 11 May 07 nicklas 420       </seeother>    
3200 21 Mar 07 martin 421       </helptext>
3314 09 May 07 nicklas 422
4444 03 Sep 08 jari 423     </sect2>
3314 09 May 07 nicklas 424     
4444 03 Sep 08 jari 425     <sect2 id="import_export_data.import.jobqueue">
3314 09 May 07 nicklas 426       <title>Add the import job to the job queue</title>
3177 08 Mar 07 martin 427
5798 11 Oct 11 nicklas 428       <figure id="import_export_data.figures.finish_job">
5798 11 Oct 11 nicklas 429         <title>Job name and options</title>
5798 11 Oct 11 nicklas 430         <screenshot>
5798 11 Oct 11 nicklas 431           <mediaobject>
5798 11 Oct 11 nicklas 432             <imageobject>
5798 11 Oct 11 nicklas 433               <imagedata 
5798 11 Oct 11 nicklas 434                 fileref="figures/finish_job.png" format="PNG" />
5798 11 Oct 11 nicklas 435             </imageobject>
5798 11 Oct 11 nicklas 436           </mediaobject>
5798 11 Oct 11 nicklas 437         </screenshot>
5798 11 Oct 11 nicklas 438       </figure>
5798 11 Oct 11 nicklas 439       
5798 11 Oct 11 nicklas 440       <helptext external_id="runplugin.finshjob" 
5798 11 Oct 11 nicklas 441         title="Set job name and options">
3177 08 Mar 07 martin 442       <para>
3314 09 May 07 nicklas 443         In this window should information about the job be filled in, like name and
3200 21 Mar 07 martin 444         description. Where name is required and need to have valid string as a value. There
3481 13 Jun 07 martin 445         are also two check boxes in this page.
3481 13 Jun 07 martin 446         <variablelist>
3481 13 Jun 07 martin 447           <varlistentry>
3481 13 Jun 07 martin 448             <term>
5798 11 Oct 11 nicklas 449               <guilabel>Name</guilabel>
5798 11 Oct 11 nicklas 450             </term>
5798 11 Oct 11 nicklas 451             <listitem>
5798 11 Oct 11 nicklas 452               <para>
5798 11 Oct 11 nicklas 453                 Most plug-ins should suggest a name for the job, but you can change it if
5798 11 Oct 11 nicklas 454                 you want to.
5798 11 Oct 11 nicklas 455               </para>
5798 11 Oct 11 nicklas 456             </listitem>
5798 11 Oct 11 nicklas 457           </varlistentry>
5798 11 Oct 11 nicklas 458           <varlistentry>
5798 11 Oct 11 nicklas 459             <term>
5798 11 Oct 11 nicklas 460               <guilabel>Use job agent</guilabel>
5798 11 Oct 11 nicklas 461             </term>
5798 11 Oct 11 nicklas 462             <listitem>
5798 11 Oct 11 nicklas 463               <para>
5798 11 Oct 11 nicklas 464                 This option is only available if the BASE system has been configured with
5798 11 Oct 11 nicklas 465                 job agents and the logged in user has <constant>SELECT_JOBAGENT</constant>
5798 11 Oct 11 nicklas 466                 permission. Select the <guilabel>automatic</guilabel> option to let
5798 11 Oct 11 nicklas 467                 BASE automatically select a job agent or select a specific option
5798 11 Oct 11 nicklas 468                 to force the use of that particular job agent.
5798 11 Oct 11 nicklas 469               </para>
5798 11 Oct 11 nicklas 470             </listitem>
5798 11 Oct 11 nicklas 471           </varlistentry>
5798 11 Oct 11 nicklas 472           <varlistentry>
5798 11 Oct 11 nicklas 473             <term>
3481 13 Jun 07 martin 474               <guilabel>Send message</guilabel>
3481 13 Jun 07 martin 475             </term>
3481 13 Jun 07 martin 476             <listitem>
3481 13 Jun 07 martin 477               <para>
3481 13 Jun 07 martin 478                 Tick this check box if the job should send you a message when it is
3481 13 Jun 07 martin 479                 finished, otherwise untick it
3481 13 Jun 07 martin 480               </para>
3481 13 Jun 07 martin 481             </listitem>
3481 13 Jun 07 martin 482           </varlistentry>
3481 13 Jun 07 martin 483           <varlistentry>
3481 13 Jun 07 martin 484             <term>
3481 13 Jun 07 martin 485               <guilabel>Remove job</guilabel>
3481 13 Jun 07 martin 486             </term>
3481 13 Jun 07 martin 487             <listitem>
3481 13 Jun 07 martin 488               <para>
3481 13 Jun 07 martin 489                 If this check box is ticked, the job will be marked as removed when
3481 13 Jun 07 martin 490                 it is finished, on condition that it was finished successfully. This
3481 13 Jun 07 martin 491                 is only available for import- and export- plugins.
3481 13 Jun 07 martin 492               </para>
3481 13 Jun 07 martin 493             </listitem>
3481 13 Jun 07 martin 494           </varlistentry>
3481 13 Jun 07 martin 495         </variablelist>
3183 12 Mar 07 martin 496       </para>
3183 12 Mar 07 martin 497       <para>
3183 12 Mar 07 martin 498         Clicking on
3394 28 May 07 martin 499         &gbFinish;
3314 09 May 07 nicklas 500         when everything is set will end the job configuration and place the job in the job queue. 
3314 09 May 07 nicklas 501         A self-refreshing window appears with information about the
3200 21 Mar 07 martin 502         job's status and execution time. How long time it takes before the job starts to run
3487 13 Jun 07 peter 503         depends on which priority it and the other jobs in the queue have. The job does not
3314 09 May 07 nicklas 504         depend on the status window to be able to run and the window can be
4444 03 Sep 08 jari 505         closed without interrupting the execution.
3183 12 Mar 07 martin 506       </para>
3183 12 Mar 07 martin 507       <tip>
3183 12 Mar 07 martin 508         <title>View job status</title>
3183 12 Mar 07 martin 509         <para>
3183 12 Mar 07 martin 510           A job's status can be viewed at any time by opening it from the job list page,
3183 12 Mar 07 martin 511           <menuchoice>
3183 12 Mar 07 martin 512             <guimenuitem>View</guimenuitem>
3183 12 Mar 07 martin 513             <guimenuitem>Jobs</guimenuitem>
3314 09 May 07 nicklas 514           </menuchoice>.
3183 12 Mar 07 martin 515         </para>
3183 12 Mar 07 martin 516       </tip>
5798 11 Oct 11 nicklas 517       </helptext>
4444 03 Sep 08 jari 518     </sect2>
4444 03 Sep 08 jari 519
4432 01 Sep 08 jari 520     </sect1>
3165 06 Mar 07 martin 521
4444 03 Sep 08 jari 522     <sect1 id="import_data.batch">
4444 03 Sep 08 jari 523       <title>Batch import of data</title>
4444 03 Sep 08 jari 524
4444 03 Sep 08 jari 525       <para>
4444 03 Sep 08 jari 526         There are in general several possibilities to import data into
4444 03 Sep 08 jari 527         BASE. Bulk data such as reporter information and raw data
4444 03 Sep 08 jari 528         imports are handled by plug-ins created for these tasks. For
4444 03 Sep 08 jari 529         item types that are imported in more moderate quantities a
4444 03 Sep 08 jari 530         suite of batch item importers available
4444 03 Sep 08 jari 531         (<xref linkend="coreplugins.import.batch" />). These importers
4444 03 Sep 08 jari 532         allows the user to create new items in BASE and define item
4444 03 Sep 08 jari 533         properties and associations between items using tab-separated
4444 03 Sep 08 jari 534         (or equivalent) files.
4444 03 Sep 08 jari 535       </para>
4444 03 Sep 08 jari 536
4444 03 Sep 08 jari 537       <para>
4444 03 Sep 08 jari 538         The batch importers are available for most users and they may
4444 03 Sep 08 jari 539         have been pre-configured but there is no requirement to
4444 03 Sep 08 jari 540         configure the batch importer plug-ins. Here we assume that no
4444 03 Sep 08 jari 541         plug-in configuration exists for the batch
4444 03 Sep 08 jari 542         importers. Pre-configuration of the importers is really only
4444 03 Sep 08 jari 543         needed for facilities that perform the same imports regularly
4444 03 Sep 08 jari 544         whereas for occasional use the provided wizard is
4444 03 Sep 08 jari 545         sufficient. Configuring the importers follows the route
4444 03 Sep 08 jari 546         described in <xref linkend="plugins.configuration" />.
4444 03 Sep 08 jari 547       </para>
4444 03 Sep 08 jari 548
4444 03 Sep 08 jari 549       <para>
4444 03 Sep 08 jari 550         The batch importers either creates new items or updates
4444 03 Sep 08 jari 551         already existing items. In either mode the plugin can set
4444 03 Sep 08 jari 552         values for
4444 03 Sep 08 jari 553         <itemizedlist>
4444 03 Sep 08 jari 554           <listitem>
4444 03 Sep 08 jari 555             <para>
4444 03 Sep 08 jari 556               Simple properties, <emphasis>eg.</emphasis>, string
4444 03 Sep 08 jari 557               values, numeric values, dates, etc.
4444 03 Sep 08 jari 558             </para>
4444 03 Sep 08 jari 559           </listitem>
4444 03 Sep 08 jari 560           <listitem>
4444 03 Sep 08 jari 561             <para>
4444 03 Sep 08 jari 562               Single-item references, <emphasis>eg.</emphasis>,
4444 03 Sep 08 jari 563               protocol, label, software, owner, etc.
4444 03 Sep 08 jari 564             </para>
4444 03 Sep 08 jari 565           </listitem>
4444 03 Sep 08 jari 566           <listitem>
4444 03 Sep 08 jari 567             <para>
4444 03 Sep 08 jari 568               Multi-item references are references to several other
5784 05 Oct 11 nicklas 569               items of the same type. The extracts of a
5784 05 Oct 11 nicklas 570               physical bioassay or pooled samples are two examples of
5784 05 Oct 11 nicklas 571               items that refer to several other items; a physical bioassay
5784 05 Oct 11 nicklas 572               may contain several extracts and a sample may be
4444 03 Sep 08 jari 573               a pool of several samples. In some cases a multi-item
4444 03 Sep 08 jari 574               reference is bundled with simple
4444 03 Sep 08 jari 575               values, <emphasis>eg.</emphasis>, used quantity of a
5784 05 Oct 11 nicklas 576               source biomaterial, the position an extract is
4444 03 Sep 08 jari 577               used on, etc. Multi-item references are never removed by
4444 03 Sep 08 jari 578               the importer, only added or updated. Removing an item
4444 03 Sep 08 jari 579               from a multi-item reference is a manual procedure to be
4444 03 Sep 08 jari 580               done using the web interface.
4444 03 Sep 08 jari 581             </para>
4444 03 Sep 08 jari 582           </listitem>
4444 03 Sep 08 jari 583         </itemizedlist>
4444 03 Sep 08 jari 584         The batch importers do not set values for annotations since
5784 05 Oct 11 nicklas 585         this is handled by the annotation importer
4444 03 Sep 08 jari 586         plug-in (<xref linkend="annotations.massimport" />). However,
4444 03 Sep 08 jari 587         the annotation importer and batch item importers have similar
4444 03 Sep 08 jari 588         behaviour and functionality to minimize the learning cost for
4444 03 Sep 08 jari 589         users.
4444 03 Sep 08 jari 590       </para>
4444 03 Sep 08 jari 591
4444 03 Sep 08 jari 592       <para>
5784 05 Oct 11 nicklas 593         The importer only works with one type of items at each use and can be
4444 03 Sep 08 jari 594         used in a <emphasis>dry-run</emphasis> mode where everything
4444 03 Sep 08 jari 595         is performed as if a real import is taking place, but the work
4444 03 Sep 08 jari 596         (transaction) is not committed to the database. The result of
4444 03 Sep 08 jari 597         the test can be stored to a log file and the user can examine
4444 03 Sep 08 jari 598         the output to see how an actual import would perform. Summary
4444 03 Sep 08 jari 599         results such as the number of items imported and the number of
4444 03 Sep 08 jari 600         failed items are reported after the import is finished, and in
4444 03 Sep 08 jari 601         the case of non-recoverable failure the reason is reported.
4444 03 Sep 08 jari 602       </para>
4444 03 Sep 08 jari 603
4444 03 Sep 08 jari 604       <sect2 id="import_data.batch.fileformat">
4444 03 Sep 08 jari 605         <title>File format</title>
4444 03 Sep 08 jari 606
4444 03 Sep 08 jari 607         <para>
4444 03 Sep 08 jari 608           For proper and efficient use of the batch importers users
4444 03 Sep 08 jari 609           need to understand how the files to be imported should be
5784 05 Oct 11 nicklas 610           formatted. The input file must be organised into columns separated by a
4444 03 Sep 08 jari 611           specified character such as a tab or comma character. The
4444 03 Sep 08 jari 612           data header line contains the column headers which defines
4444 03 Sep 08 jari 613           the contents of each column and defines the beginning of
4444 03 Sep 08 jari 614           item data in the file. The item data block continues until
4444 03 Sep 08 jari 615           the end of the file or to an optional data footer line
4444 03 Sep 08 jari 616           defining the end of the data block.
4444 03 Sep 08 jari 617         </para>
4444 03 Sep 08 jari 618
4444 03 Sep 08 jari 619         <para>
4444 03 Sep 08 jari 620           When reading data for an item the plug-in must use some
4444 03 Sep 08 jari 621           information for identifying items. Depending on item type
4444 03 Sep 08 jari 622           there are two or three options to select the item identifier
4444 03 Sep 08 jari 623           <itemizedlist>
4444 03 Sep 08 jari 624             <listitem>
4444 03 Sep 08 jari 625               <para>
4444 03 Sep 08 jari 626                 Using the internal <property>id</property>. This is
4444 03 Sep 08 jari 627                 always unique for a specific BASE server.
4444 03 Sep 08 jari 628               </para>
4444 03 Sep 08 jari 629             </listitem>
4444 03 Sep 08 jari 630             <listitem>
4444 03 Sep 08 jari 631               <para>
4444 03 Sep 08 jari 632                 Using the <property>name</property>. This may or may
4444 03 Sep 08 jari 633                 not be unique.
4444 03 Sep 08 jari 634               </para>
4444 03 Sep 08 jari 635             </listitem>
4444 03 Sep 08 jari 636             <listitem>
4444 03 Sep 08 jari 637               <para>
4444 03 Sep 08 jari 638                 Some items have
4444 03 Sep 08 jari 639                 an <property>externalId</property>. This may or may
4444 03 Sep 08 jari 640                 not be unique.
4444 03 Sep 08 jari 641               </para>
4444 03 Sep 08 jari 642             </listitem>
4444 03 Sep 08 jari 643             <listitem>
4444 03 Sep 08 jari 644               <para>
4444 03 Sep 08 jari 645                 Array slides may have a <property>barcode</property>
4444 03 Sep 08 jari 646                 which is similar to
4444 03 Sep 08 jari 647                 the <property>externalId</property>.
4444 03 Sep 08 jari 648               </para>
4444 03 Sep 08 jari 649             </listitem>
7620 04 Mar 19 nicklas 650             <listitem>
7620 04 Mar 19 nicklas 651               <para>
7620 04 Mar 19 nicklas 652                 An <property>annotation type</property> that has been flagged
7620 04 Mar 19 nicklas 653                 as <property>identifier</property>. See <xref linkend="annotations.types" />.
7620 04 Mar 19 nicklas 654               </para>
7620 04 Mar 19 nicklas 655             </listitem>
4444 03 Sep 08 jari 656           </itemizedlist>
4444 03 Sep 08 jari 657           It is important that the identifier selected
4444 03 Sep 08 jari 658           is <emphasis>unique</emphasis> in the file used, or if the
4444 03 Sep 08 jari 659           file is used to update items already existing in BASE the
4444 03 Sep 08 jari 660           identifier should also be unique in BASE for the user
4444 03 Sep 08 jari 661           performing the update. The plug-in will check uniqueness
4444 03 Sep 08 jari 662           when default parameters are used but the user may change the
4444 03 Sep 08 jari 663           default behaviour.
4444 03 Sep 08 jari 664         </para>
4444 03 Sep 08 jari 665
4444 03 Sep 08 jari 666         <para>
4444 03 Sep 08 jari 667           Data for a single item may be split into multiple lines. The
4444 03 Sep 08 jari 668           first line contains simple properties and single-item
4444 03 Sep 08 jari 669           references, and the first multi-item reference. If there are
4444 03 Sep 08 jari 670           more multi-item references they should be on the following
4444 03 Sep 08 jari 671           lines with empty values in all other columns, except for the
4444 03 Sep 08 jari 672           column holding the item identifier. The item identifier must
4444 03 Sep 08 jari 673           have the same value on all lines associated with the
4444 03 Sep 08 jari 674           item. Lines containing other data than multi-item references
4444 03 Sep 08 jari 675           will be ignored or may be considered as an error depending
4444 03 Sep 08 jari 676           on plug-in parameter settings. The reason for treating
4444 03 Sep 08 jari 677           copied data entries as an error is to catch situations where
4444 03 Sep 08 jari 678           two items is given the same item identifier by accident.
4444 03 Sep 08 jari 679         </para>
4444 03 Sep 08 jari 680
4444 03 Sep 08 jari 681       </sect2>
4444 03 Sep 08 jari 682
4444 03 Sep 08 jari 683       <sect2 id="import_data.batch.running">
4444 03 Sep 08 jari 684         <title>Running the item batch importer</title>
4444 03 Sep 08 jari 685
4444 03 Sep 08 jari 686         <para>
4444 03 Sep 08 jari 687           This section discuss specific parameters and features of the
4444 03 Sep 08 jari 688           batch importers. The general use of the batch importers
4444 03 Sep 08 jari 689           follow the description outlined in
4444 03 Sep 08 jari 690           <xref linkend="import_data.import" /> and the setting of
4444 03 Sep 08 jari 691           column mapping parameters is assisted with
4444 03 Sep 08 jari 692           the <guilabel>Test with file</guilabel> function described
4444 03 Sep 08 jari 693           in <xref linkend="plugins.configuration.testwithfile"
4444 03 Sep 08 jari 694           />. The column headers are mapped to item properties at each
4444 03 Sep 08 jari 695           use of the plug-in but, as pointed out above, they can also
4444 03 Sep 08 jari 696           be predefined by saving settings as a plug-in
4444 03 Sep 08 jari 697           configuration. The configuration also includes separator
4444 03 Sep 08 jari 698           character and other information that is needed to parse
4444 03 Sep 08 jari 699           files. The ability to save configurations depends on user
4444 03 Sep 08 jari 700           credential and is by default only granted to administrators.
4444 03 Sep 08 jari 701         </para>
4444 03 Sep 08 jari 702
4444 03 Sep 08 jari 703         <para>
4444 03 Sep 08 jari 704           The plug-in parameter follows the standard BASE plug-in
4444 03 Sep 08 jari 705           layout and shows help information for selected
4444 03 Sep 08 jari 706           parameters. The list below comments on some of the
4444 03 Sep 08 jari 707           parameters available.
5784 05 Oct 11 nicklas 708         </para>
5784 05 Oct 11 nicklas 709         
4444 03 Sep 08 jari 710           <variablelist>
4444 03 Sep 08 jari 711             <varlistentry>
4444 03 Sep 08 jari 712               <term>
4444 03 Sep 08 jari 713                 <guilabel>Mode</guilabel>
4444 03 Sep 08 jari 714               </term>
4444 03 Sep 08 jari 715               <listitem>
4444 03 Sep 08 jari 716                 <para>
4444 03 Sep 08 jari 717                   Select the mode of the plug-in. The plug-in can
4444 03 Sep 08 jari 718                   create new items and/or update items already
4444 03 Sep 08 jari 719                   existing in BASE. This setting is available to allow
4444 03 Sep 08 jari 720                   the user to make a conscious choice of how to treat
4444 03 Sep 08 jari 721                   missing or already existing items. For example, if
4444 03 Sep 08 jari 722                   the user selects to only update items already
4444 03 Sep 08 jari 723                   existing the plug-in will complain if an item in the
4444 03 Sep 08 jari 724                   file does not exist in BASE (using default error
4444 03 Sep 08 jari 725                   condition treatment). This adds an extra layer of
4444 03 Sep 08 jari 726                   security and diagnostics for the user during import.
4444 03 Sep 08 jari 727                 </para>
7620 04 Mar 19 nicklas 728                 
7620 04 Mar 19 nicklas 729                 <note>
7620 04 Mar 19 nicklas 730                   <title>Running from an item list</title>
7620 04 Mar 19 nicklas 731                   <para>
7620 04 Mar 19 nicklas 732                     If the importer is started from the <guilabel>Members</guilabel> tab
7620 04 Mar 19 nicklas 733                     of an item list the <property>create</property> mode is not available
7620 04 Mar 19 nicklas 734                     and the the <property>update</property> mode will only update items that 
7620 04 Mar 19 nicklas 735                     are members of the list. In addition, there are two other modes:
7620 04 Mar 19 nicklas 736                     <property>add-members</property> and <property>remove-members</property>
7620 04 Mar 19 nicklas 737                     that can be used to add or remove members from the item list.
7620 04 Mar 19 nicklas 738                   </para>
7620 04 Mar 19 nicklas 739                 </note>
7620 04 Mar 19 nicklas 740                 
4444 03 Sep 08 jari 741               </listitem>
4444 03 Sep 08 jari 742             </varlistentry>
4444 03 Sep 08 jari 743             <varlistentry>
4444 03 Sep 08 jari 744               <term>
5784 05 Oct 11 nicklas 745                 <guilabel>Data directory</guilabel>
5784 05 Oct 11 nicklas 746               </term>
5784 05 Oct 11 nicklas 747               <listitem>
5784 05 Oct 11 nicklas 748                 <para>
5784 05 Oct 11 nicklas 749                   This option is only available for items that has support for
5784 05 Oct 11 nicklas 750                   attaching files (eg. array design, derived bioassay, etc.).
5784 05 Oct 11 nicklas 751                   This setting is used to resolve file references that doesn't
5784 05 Oct 11 nicklas 752                   include a complete absolute path.
5784 05 Oct 11 nicklas 753                 </para>
5784 05 Oct 11 nicklas 754               </listitem>
5784 05 Oct 11 nicklas 755             </varlistentry>
5784 05 Oct 11 nicklas 756             <varlistentry>
5784 05 Oct 11 nicklas 757               <term>
4444 03 Sep 08 jari 758                 <guilabel>Identification method</guilabel>
4444 03 Sep 08 jari 759               </term>
4444 03 Sep 08 jari 760               <listitem>
4444 03 Sep 08 jari 761                 <para>
4444 03 Sep 08 jari 762                   This parameter defines the method to use to find
4444 03 Sep 08 jari 763                   already existing items. The parameter can only be
4444 03 Sep 08 jari 764                   set to a set of item properties listed in the
4444 03 Sep 08 jari 765                   plug-in parameter dialog. The property selected by
7620 04 Mar 19 nicklas 766                   the user must be mapped to a column in the file. 
7620 04 Mar 19 nicklas 767                   For example, if <property>Name</property> selected
7620 04 Mar 19 nicklas 768                   as identification method, a column mapping must be 
7620 04 Mar 19 nicklas 769                   set for <guilabel>Name</guilabel>. If an annotation
7620 04 Mar 19 nicklas 770                   type method is selected (they are prefixed with <guilabel>[A]</guilabel>)
7620 04 Mar 19 nicklas 771                   a column mapping must be set for the <guilabel>Annotation ID</guilabel>
7620 04 Mar 19 nicklas 772                   parameter.
4444 03 Sep 08 jari 773                 </para>
4444 03 Sep 08 jari 774               </listitem>
4444 03 Sep 08 jari 775             </varlistentry>
4444 03 Sep 08 jari 776             <varlistentry>
4444 03 Sep 08 jari 777               <term>
5784 05 Oct 11 nicklas 778                 <guilabel>Item subtypes</guilabel>
5784 05 Oct 11 nicklas 779               </term>
5784 05 Oct 11 nicklas 780               <listitem>
5784 05 Oct 11 nicklas 781                 <para>
5784 05 Oct 11 nicklas 782                   Only look for existing items among the selected subtypes. If no subtype
5784 05 Oct 11 nicklas 783                   is selected all items are searched. If exactly one subtype is selected
5784 05 Oct 11 nicklas 784                   new items are automatically created with this subtype (unless it is overridden
5784 05 Oct 11 nicklas 785                   by specific subtype values in the import file). 
5784 05 Oct 11 nicklas 786                 </para>
5784 05 Oct 11 nicklas 787               </listitem>
5784 05 Oct 11 nicklas 788             </varlistentry>
5784 05 Oct 11 nicklas 789             <varlistentry>
5784 05 Oct 11 nicklas 790               <term>
4444 03 Sep 08 jari 791                 <guilabel>Owned by me</guilabel>, <guilabel>Shared to
4444 03 Sep 08 jari 792                 me</guilabel>, <guilabel>In current
4444 03 Sep 08 jari 793                 project</guilabel>, and <guilabel>Owned by
4444 03 Sep 08 jari 794                 others</guilabel>
4444 03 Sep 08 jari 795               </term>
4444 03 Sep 08 jari 796               <listitem>
4444 03 Sep 08 jari 797                 <para>
4444 03 Sep 08 jari 798                   Defines the set of items the plug-in should look in
4444 03 Sep 08 jari 799                   when it checks whether an item already exists. The
4444 03 Sep 08 jari 800                   options are the same that are available in list
4444 03 Sep 08 jari 801                   views and the actual set of parameters depends in
4444 03 Sep 08 jari 802                   user credentials.
4444 03 Sep 08 jari 803                 </para>
4444 03 Sep 08 jari 804               </listitem>
4444 03 Sep 08 jari 805             </varlistentry>
4444 03 Sep 08 jari 806             <varlistentry>
4444 03 Sep 08 jari 807               <term>
4444 03 Sep 08 jari 808                 <guilabel>Column mapping expressions</guilabel>
4444 03 Sep 08 jari 809               </term>
4444 03 Sep 08 jari 810               <listitem>
4444 03 Sep 08 jari 811                 <para>
4444 03 Sep 08 jari 812                   Use the <guilabel>Test with file</guilabel> function
4444 03 Sep 08 jari 813                   described in
4444 03 Sep 08 jari 814                   <xref linkend="plugins.configuration.testwithfile"
4444 03 Sep 08 jari 815                   /> to set the column mapping parameters.
4444 03 Sep 08 jari 816                 </para>
4444 03 Sep 08 jari 817                 <para>
5784 05 Oct 11 nicklas 818                   When working with biomaterial items, the 
5784 05 Oct 11 nicklas 819                   <guilabel>Parent type</guilabel> property is used to
5784 05 Oct 11 nicklas 820                   tell the plug-in how to find parent items. This only
5784 05 Oct 11 nicklas 821                   has to be set if the parent item is of the same type
5784 05 Oct 11 nicklas 822                   as the biomaterial being imported since the default
5784 05 Oct 11 nicklas 823                   is to look for the nearest parent type in the predefined hierarchy.
5784 05 Oct 11 nicklas 824                   In ascending order the BASE ordering
4444 03 Sep 08 jari 825                   of <emphasis>parent - child - grandchild -
4444 03 Sep 08 jari 826                   ...</emphasis> item relation is <emphasis>biosource
5784 05 Oct 11 nicklas 827                   - sample - extract</emphasis>.
4444 03 Sep 08 jari 828                 </para>
4444 03 Sep 08 jari 829                 <para>
5784 05 Oct 11 nicklas 830                   The values accepted for <guilabel>Parent type</guilabel>
5784 05 Oct 11 nicklas 831                   are <constant>BIOSOURCE</constant>,
5784 05 Oct 11 nicklas 832                   <constant>SAMPLE</constant> or <constant>EXTRACT</constant>.
5784 05 Oct 11 nicklas 833                   Sometimes all items in a file to be imported have the same parent
5784 05 Oct 11 nicklas 834                   type but there is no column with this information. This can
4444 03 Sep 08 jari 835                   be resolved by setting
5784 05 Oct 11 nicklas 836                   the <guilabel>Parent type</guilabel> mapping to a
5784 05 Oct 11 nicklas 837                   constant string (eg. no backslash '\' character).
4444 03 Sep 08 jari 838                 </para>
5899 06 Dec 11 nicklas 839                 
5899 06 Dec 11 nicklas 840                 <tip>
5899 06 Dec 11 nicklas 841                   <title>Project default items</title>
5899 06 Dec 11 nicklas 842                   <para>
5899 06 Dec 11 nicklas 843                     When creating new items some properties (eg. protocol, software,
5899 06 Dec 11 nicklas 844                     hardware, etc.) are assigned default values from the currently
5899 06 Dec 11 nicklas 845                     active project if no mapping has been specified for that property.
5899 06 Dec 11 nicklas 846                     It is also possible to access project default values when a 
5899 06 Dec 11 nicklas 847                     a mapping is used. Use <code>=default()</code> as a mapping expression
5899 06 Dec 11 nicklas 848                     to set the property to the project default value or
5899 06 Dec 11 nicklas 849                     <code>=default(col('foo'))</code> to use the value from column
5899 06 Dec 11 nicklas 850                     <code>foo</code> if it is not empty and the project default otherwise.
5899 06 Dec 11 nicklas 851                     Do not forget to enable the <code>Complex column mappings</code>
5899 06 Dec 11 nicklas 852                     option.
5899 06 Dec 11 nicklas 853                   </para>
5899 06 Dec 11 nicklas 854                 </tip>
4444 03 Sep 08 jari 855               </listitem>
4444 03 Sep 08 jari 856             </varlistentry>
5784 05 Oct 11 nicklas 857             <varlistentry>
5784 05 Oct 11 nicklas 858               <term>
5784 05 Oct 11 nicklas 859                 <guilabel>Permissions</guilabel>
5784 05 Oct 11 nicklas 860               </term>
5784 05 Oct 11 nicklas 861               <listitem>
5784 05 Oct 11 nicklas 862                 <para>
5784 05 Oct 11 nicklas 863                   This is a column mapping that can be used to update the permissions
5784 05 Oct 11 nicklas 864                   set on items. Normally, new items are only shared to the active project
5784 05 Oct 11 nicklas 865                   (if any). By naming a permission template, new items are shared using 
5784 05 Oct 11 nicklas 866                   the permissions from that template instead. Permissions on already existing 
5784 05 Oct 11 nicklas 867                   items are merged with the permission from the template.
5784 05 Oct 11 nicklas 868                 </para>
5784 05 Oct 11 nicklas 869               </listitem>
5784 05 Oct 11 nicklas 870             </varlistentry>
4444 03 Sep 08 jari 871           </variablelist>
5784 05 Oct 11 nicklas 872           
5784 05 Oct 11 nicklas 873           <para>
4444 03 Sep 08 jari 874           After setting the parameters,
4444 03 Sep 08 jari 875           select <guilabel>Next</guilabel>. Another parameter dialog
4444 03 Sep 08 jari 876           will appear where error handling options can be set among
4444 03 Sep 08 jari 877           with 
5784 05 Oct 11 nicklas 878           </para>
5784 05 Oct 11 nicklas 879           
4444 03 Sep 08 jari 880           <variablelist>
4444 03 Sep 08 jari 881             <varlistentry>
4444 03 Sep 08 jari 882               <term>
4444 03 Sep 08 jari 883                 <guilabel>Log file</guilabel>
4444 03 Sep 08 jari 884               </term>
4444 03 Sep 08 jari 885               <listitem>
4444 03 Sep 08 jari 886                 <para>
4444 03 Sep 08 jari 887                   Setting this parameter will turn on logging. The
4444 03 Sep 08 jari 888                   plug-in will give detailed information about how the
4444 03 Sep 08 jari 889                   file is parsed. This is useful for resolving file
4444 03 Sep 08 jari 890                   parsing issues.
4444 03 Sep 08 jari 891                 </para>
4444 03 Sep 08 jari 892               </listitem>
4444 03 Sep 08 jari 893             </varlistentry>
4444 03 Sep 08 jari 894             <varlistentry>
4444 03 Sep 08 jari 895               <term>
4444 03 Sep 08 jari 896                 <guilabel>Dry run</guilabel>
4444 03 Sep 08 jari 897               </term>
4444 03 Sep 08 jari 898               <listitem>
4444 03 Sep 08 jari 899                 <para>
4444 03 Sep 08 jari 900                   Enable or disable test run of the plug-in. If
4444 03 Sep 08 jari 901                   enabled the plug-in will parse and simulate an
4444 03 Sep 08 jari 902                   import. When enabling this option you should set
4444 03 Sep 08 jari 903                   the <guilabel>Log file</guilabel> also. The dry run
4444 03 Sep 08 jari 904                   mode allows testing of large imports and updates by
4444 03 Sep 08 jari 905                   creating a log file that can be examined for
4444 03 Sep 08 jari 906                   inconsistencies before actually performing the action
4444 03 Sep 08 jari 907                   without a safety net.
4444 03 Sep 08 jari 908                 </para>
4444 03 Sep 08 jari 909               </listitem>
4444 03 Sep 08 jari 910             </varlistentry>
4444 03 Sep 08 jari 911           </variablelist>
4444 03 Sep 08 jari 912
5784 05 Oct 11 nicklas 913
4444 03 Sep 08 jari 914         <para>
4444 03 Sep 08 jari 915           During file parsing the plug-in will look for items
4444 03 Sep 08 jari 916           referenced on each line. There are three outcomes of this
4444 03 Sep 08 jari 917           item search
5784 05 Oct 11 nicklas 918         </para>
5784 05 Oct 11 nicklas 919         
4444 03 Sep 08 jari 920           <itemizedlist>
4444 03 Sep 08 jari 921             <listitem>
4444 03 Sep 08 jari 922               <para>
4444 03 Sep 08 jari 923                 No item is found. Depending on parameter settings this
4444 03 Sep 08 jari 924                 may abort the plug-in, the plug-in may ignore the
4444 03 Sep 08 jari 925                 line, or a new item is created.
4444 03 Sep 08 jari 926               </para>
4444 03 Sep 08 jari 927             </listitem>
4444 03 Sep 08 jari 928             <listitem>
4444 03 Sep 08 jari 929               <para>
4444 03 Sep 08 jari 930                 One item is found. This is the item that is going to
4444 03 Sep 08 jari 931                 be updated.
4444 03 Sep 08 jari 932               </para>
4444 03 Sep 08 jari 933             </listitem>
4444 03 Sep 08 jari 934             <listitem>
4444 03 Sep 08 jari 935               <para>
4444 03 Sep 08 jari 936                 More than one item is found. Depending on parameter
4444 03 Sep 08 jari 937                 settings this may abort the plug-in or the plug-in may
5784 05 Oct 11 nicklas 938                 ignore the line.
4444 03 Sep 08 jari 939               </para>
4444 03 Sep 08 jari 940             </listitem>
4444 03 Sep 08 jari 941           </itemizedlist>
4444 03 Sep 08 jari 942
4444 03 Sep 08 jari 943       </sect2>
4444 03 Sep 08 jari 944
4444 03 Sep 08 jari 945       <sect2 id="import_data.batch.comments">
4444 03 Sep 08 jari 946         <title>Comments on the item batch importers</title>
4444 03 Sep 08 jari 947
4444 03 Sep 08 jari 948         <para>
4444 03 Sep 08 jari 949           The item batch importers are not designed to change or
4444 03 Sep 08 jari 950           create annotations. There is another plug-in for this, see
4444 03 Sep 08 jari 951           <xref linkend="annotations.massimport" /> for an
4444 03 Sep 08 jari 952           introduction to the annotation importer.
4444 03 Sep 08 jari 953         </para>
4444 03 Sep 08 jari 954
4444 03 Sep 08 jari 955         <para>
4444 03 Sep 08 jari 956           There is no need to map all columns when running the
4444 03 Sep 08 jari 957           importer. When new items are created usually the only
4444 03 Sep 08 jari 958           mandatory entry is <property>Name</property>, and when
4444 03 Sep 08 jari 959           running the plug-in in update mode only the column defining
4444 03 Sep 08 jari 960           the item identification property needs to be defined. This
4444 03 Sep 08 jari 961           can be utilized when only one or a few properties needs to
4444 03 Sep 08 jari 962           be updated; map only columns that should be changed and the
4444 03 Sep 08 jari 963           plug-in will ignore the other properties and leave them as
4444 03 Sep 08 jari 964           they are already stored in BASE. This also means that if one
4444 03 Sep 08 jari 965           property should be deleted then that property must be mapped
4444 03 Sep 08 jari 966           and the value must be empty in the file. Note, multi-item
4444 03 Sep 08 jari 967           reference cannot be deleted with the batch importer, and
4444 03 Sep 08 jari 968           deletion of multi-item references must be done using the web
4444 03 Sep 08 jari 969           interface.
4444 03 Sep 08 jari 970         </para>
4444 03 Sep 08 jari 971
4444 03 Sep 08 jari 972         <para>
4444 03 Sep 08 jari 973           When parent and other relations are created using the
4444 03 Sep 08 jari 974           plug-in the referenced items are properly linked and
4444 03 Sep 08 jari 975           updated. This means that when a quantity that decreases a
4444 03 Sep 08 jari 976           referenced item is used, the referenced item is updated
4444 03 Sep 08 jari 977           accordingly. In consequence, if the relation is removed in a
4444 03 Sep 08 jari 978           later update - maybe wrong parent was referenced - the
4444 03 Sep 08 jari 979           referenced item is restored and any decrease of quantities
4444 03 Sep 08 jari 980           are also reset.
4444 03 Sep 08 jari 981         </para>
4444 03 Sep 08 jari 982
4444 03 Sep 08 jari 983         <para>
4444 03 Sep 08 jari 984           A common mistake is to forget to make sure that some of the
4444 03 Sep 08 jari 985           referenced items already exists in BASE, or at least are
4444 03 Sep 08 jari 986           accessible for the user performing the import. Items such as
4444 03 Sep 08 jari 987           protocols and labels must be added before referencing
4444 03 Sep 08 jari 988           them. This is of course also true for other items but during
4444 03 Sep 08 jari 989           batch import one usually follows the natural order of first
4444 03 Sep 08 jari 990           importing biosources, samples, extracts, and so on. In this
4444 03 Sep 08 jari 991           way the parents are always present and may be referenced
4444 03 Sep 08 jari 992           without any issues.
4444 03 Sep 08 jari 993         </para>
4444 03 Sep 08 jari 994
4444 03 Sep 08 jari 995       </sect2>
4444 03 Sep 08 jari 996
4444 03 Sep 08 jari 997     </sect1>
4444 03 Sep 08 jari 998
3675 16 Aug 07 jari 999 </chapter>

Generated on Sat Oct  7 02:27:31 2023 (UTC) by svndigest 0.11.2pre (dev build 1672)