source: trunk/doc/src/docbook/userdoc/import_export_data.xml @ 3242

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

Changing the docbook output files to no longer be organized into folders because of some difficulties to get the relative
path to css-files, figures etc.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 18.2 KB
1<?xml version="1.0" encoding="UTF-8"?>
3  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
6  $Id: import_export_data.xml 3242 2007-04-13 12:56:43Z martin $
8  Copyright (C) Authors contributing to this file.
10  This file is part of BASE - BioArray Software Environment.
11  Available at
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.
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
21  GNU General Public License for more details.
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.
29<chapter id="import_export_data">
30  <!-- <?dbhtml dir="import_export"?> -->
31  <title>Import and export of data</title>
32  <para>
33    The data need first of all to be imported into the database before it can be used by/in the
34    environment. The opposite is if the data should be used outside the environment, it then
35    have to be exported before it can be used. These two actions, importing and exporting, are
36    done through the plugin interface.
37  </para>
38  <para>
39    Different kinds of import and export plugins, depending on the data, are used to get
40    data/information in and out from the BASE 2's database. Some of the plugins can take, some
41    even requires, a configuration to be able to run. If a plugin has configuration support or
42    not, can be found at
43    <menuchoice>
44      <guimenu>Administrate</guimenu>
45      <guimenuitem>Plugins</guimenuitem>
46      <guisubmenu>Definitions</guisubmenu>
47    </menuchoice>
48    . The installation of BASE2 includes a collection of plugins, so called core plugins, and
49    these are, like all other plugins, supervised by the administrator or an user with
50    similar(at least write) permission on plugins. A list with these core plugins can be found
51    on
52    <ulink
53      url="">
54      base2's homepage
55    </ulink>
56    . On this page are also configuration examples that can be downloaded for some of the
57    plugins.
58  </para>
59  <para>
60    If the
61    <guibutton>Import</guibutton>
62    or
63    <guibutton>Export</guibutton>
64    button is available in a page's toolbar the current context and item type is supported by at
65    least one import and export plugins respectively that the logged in user has permission to
66    use.
67  </para>
68  <note>
69    <title>Missing/unavailable button</title>
70    <para>
71      The logged in user does usually not have enough permission on the expected plugin if the
72      import- or export button is unavailable/not visible. Contact the administrator or
73      similar user that has permission to administrate the plugins.
74    </para>
75  </note>
76  <para>
77    Following subsections contains information how to proceed when importing or exporting data
78    in BASE2.
79  </para>
80  <sect1 id="import_export_data.import">
81    <title>Import</title>
82    <para>
83      Click on
84      <guibutton>Import</guibutton>
85      in the toolbar to import data into BASE2's database. This will open a pop-up window
86      where the job, that shall perform the data import, can be configured. More about jobs
87      and what a job is can be found under
88      <xref linkend="jobs" />
89      .
90    </para>
92    <sect2 id="import_export_data.import.plugin_fileformat">
93      <title>Select plugin and file format</title>
94      <helptext external_id="import.selectplugin"
95        title="Select plugin and file format for data import">
96        <para>
97          The first thing to do when configuring a job is to set which import plugin and
98          file format to use alternatively let the interface choose suitable plugin/file
99          format based on the file that shall be imported, more about this in
100          <xref linkend="import_export_data.import.plugin_fileformat.autodetect" />
101          .
102        </para>
104        <sect3 id="import_export_data.import.plugin_fileformat.plugin">
105          <title>Plugin</title>
106          <para>
107            Available import plugins that the logged in user has permission to use and
108            that support the current context are listed in the pop-up window's
109            drop-down-list with plugins. Select the appropriate import plugin for the
110            job from this list. At the bottom of the frame stands a short description
111            about what the selected plugin does. More information about the plugins can
112            be found under the menu choice
113            <menuchoice>
114              <guimenu>Administrate</guimenu>
115              <guimenuitem>Plugins</guimenuitem>
116              <guisubmenu>Definitions</guisubmenu>
117            </menuchoice>
118          </para>
119        </sect3>
121        <sect3 id="import_export_data.import.plugin_fileformat.fileformat">
122          <title>File format</title>
123          <para>
124            The drop down list with file format contains available file formats for the
125            selected plugin. A file format configures a plugin how it should parse the
126            file for importing it's data. Information about each file format can be
127            found under the menu choice
128            <menuchoice>
129              <guimenu>Administrate</guimenu>
130              <guimenuitem>Plugins</guimenuitem>
131              <guisubmenu>Configurations</guisubmenu>
132            </menuchoice>
133            . Select the file format that should be used together with the plugin.
134          </para>
135          <para>
136            Proceed to next window by clicking on
137            <guibutton>Next</guibutton>
138          </para>
139        </sect3>
141        <sect3 id="import_export_data.import.plugin_fileformat.autodetect">
142          <title>Auto detect</title>
143          <para>
144            Auto detect lets the BASE2 plugin-interface to choose plugin and/or file
145            format by validating the data file that shall be imported. This option is
146            set by default in both plugin- and file format drop-down lists when there is
147            at least one plugin in the list that supports auto detection.
148          </para>
149          <note>
150            <title>Support of auto detect</title>
151            <para>
152              Not all plugins support auto detection. The ones that do are marked in
153              the drop down list with a
154              <guilabel>X</guilabel>
155              .
156            </para>
157          </note>
158          <para>
159            Set either both plugins and file formats or only file format to auto detect
160            to use this feature. Click then on
161            <guibutton>Next</guibutton>
162            to go to the next window where the file to import from is selected. Press
163            <guibutton>Browse&hellip;</guibutton>
164            in this window to browse after the import file in the BASE2's file system.
165            If the file doesn't exist in the file system it first has to be uploaded
166            before it's possible to use it, read more about this under
167            <xref linkend="file_system" />
168            .
169          </para>
170          <para>
171            Proceed by clicking on
172            <guibutton>Next</guibutton>
173            .
174          </para>
175          <para>
176            If there is a file format and a plugin compatible to the selected file, the
177            next step will be to configure the job parameters. The file parameter is
178            already set to the file that was selected earlier. Is there on the other
179            hand no compatible file format or plugin that could be found there will be
180            an error message that describes what went wrong.
181          </para>
182          <note>
183            <title>More then one compatible plugin/file format</title>
184            <para>
185              The auto detect will pick the first plugin and file format it finds and
186              it can therefore not be used if there are more then one plugin or file
187              format that can import the selected file.
188            </para>
189          </note>
190        </sect3>
191      </helptext>
192    </sect2>
194    <sect2 id="import_export_data.import.jobparameters">
195      <title>Job parameters</title>
196      <para>
197        This window contains of a top line with the names of the selected plugin and
198        configuration, a list with parameters to the left, area for input fields to the
199        right and buttons to proceed with at the bottom. Which the parameters in the list
200        are depends on the selected plugin and it's configuration. Common parameter for all
201        import plugin is however the
202        <guilabel>File</guilabel>
203        parameter (already set if auto detect is used) which holds the file to import the
204        data from. A click on a parameter in the list will display an input field and a
205        description to the right of the list. Parameters that have a
206        <guilabel>X</guilabel>
207        in front of their names has already a value set and those parameters, which names
208        are marked with a rectangle, are required and need to be set before it's possible to
209        continuing with the job configuration. There will pop up a dialog window if not all
210        required parameters had been set.
211      </para>
212      <para>
213        Continue the job configuration by clicking on
214        <guibutton>Next</guibutton>
215        . In this window should information about the job be filled in, like name and
216        description. Where name is required and need to have valid string as a value. There
217        is also an option if the user want to get a message or not after the job is done.
218        The check-box should be ticked if the owner of the job wants to get a message with a
219        summary of the job's execution.
220      </para>
221      <para>
222        Clicking on
223        <guibutton>Finish</guibutton>
224        when everything is set will end the job configuration and place the job in the BASE
225        2 server's job queue. A self-refreshing window appears with information about the
226        job's status and execution time. How long time it takes before the job starts to run
227        depends on which priority it and the other jobs in the queue have. The job doesn't
228        dependent on the status window to be able to run and therefore can the window be
229        closed without the execution is interrupted.
230      </para>
231      <tip>
232        <title>View job status</title>
233        <para>
234          A job's status can be viewed at any time by opening it from the job list page,
235          <menuchoice>
236            <guimenuitem>View</guimenuitem>
237            <guimenuitem>Jobs</guimenuitem>
238          </menuchoice>
239          .
240        </para>
241      </tip>
242    </sect2>
243  </sect1>
245  <sect1 id="import_export_data.export">
246    <title>Export</title>
247    <para>
248      Before data from BASE 2's database can be used outside the program, it first had to be
249      exported to a file which then can be downloaded to a local path from the BASE file
250      system.
251    </para>
252    <para>
253      A data export is done by a job that runs an export plugin for the current context. An
254      export job is started by clicking on
255      <guibutton>Export&hellip;</guibutton>
256      in the toolbar, which will open a pop-up window where the job can be configured.
257    </para>
258    <helptext external_id="runplugin.selectplugin" title="Select plugin">
259      <para>
260        The first thing in the configuration process is to choose which plugin the job
261        should use and a plugin-configuration for those plugins that require it. More
262        information about the plugins can be found in each plugin's documentation.
263      </para>
264      <variablelist>
265        <title>Set plugin and configuration</title>
266        <varlistentry>
267          <term>
268            <guilabel>Plugin</guilabel>
269          </term>
270          <listitem>
271            <para>
272              Select the plugin that shall do the export. Only plugins that are
273              available for the logged in user and that supports the current item are
274              in the drop down list.
275            </para>
276          </listitem>
277        </varlistentry>
278        <varlistentry>
279          <term>
280            <guilabel>Configuration</guilabel>
281          </term>
282          <listitem>
283            <para>
284              Select the configuration that should be used together with the plugin.
285              Not all plugins supports configuration and this option is only visible
286              if the selected plugin in
287              <guilabel>Plugin</guilabel>
288              has this support and visible configurations are those which can be used
289              with the selected plugin above. More information about configuration
290              support can be found for each plugin under.
291            </para>
292          </listitem>
293        </varlistentry>
294      </variablelist>
295      <para>
296        Click on
297        <guibutton>Next</guibutton>
298        to show the configuration of parameters for the job.
299      </para>
300    </helptext>
301    <para>
302      Common for all export plugins is the file parameter that decide where the export data
303      should be saved. Some plugins support the option of download immediately which let the
304      user to download the exported data to a local file system, by leaving the file parameter
305      empty. For saving the exported data within the file system of BASE, it's recommended to
306      use the
307      <guibutton>Browse&hellip;</guibutton>
308      button to get the right path and then complement it with the file's name.
309    </para>
310    <para>
311      Click on
312      <guibutton>Next</guibutton>
313      to proceed to next configuration window.
314    </para>
315    <para>
316      If the file parameter were left empty and immediately download was chosen the new window
317      will have a
318      <guibutton>Download</guibutton>
319      button to specify where the data should be saved on the local computer.
320    </para>
321    <para>
322      But if the file should be saved within the file system of BASE instead, there will be a
323      window where the job should get a name and optionally a description. By then clicking on
324      <guibutton>Finish</guibutton>
325      the configuration process will end and the job will be put in the job queue. A
326      self-refreshing window appears with information about the job's status and execution
327      time. The job isn't dependent on the status window to run and it therefore be closed
328      without interrupting the execution of the job.
329    </para>
330    <tip>
331      <title>View job status</title>
332      <para>
333        A job's status can be viewed at any time by opening it from the job list page,
334        <menuchoice>
335          <guimenuitem>View</guimenuitem>
336          <guimenuitem>Jobs</guimenuitem>
337        </menuchoice>
338        .
339      </para>
340    </tip>
341    <sect2 id="import_export_data.export.table_export">
342      <title>Table export</title>
343      <para>
344        The table exporter is a common export plugin for all list pages in BASE 2 and it
345        makes it possible for the user to export the list to either a XML-file or a
346        tab-separated text file. The table exporter supports all list pages and is started,
347        like the other export plugins, by clicking on
348        <guibutton>Export&hellip;</guibutton>
349        in the toolbar.
350      </para>
351      <sect3 id="import_export_data.export.table_export.configuration">
352        <title>Configuration</title>
353        <para>
354          Clicking on
355          <guibutton>Export&hellip;</guibutton>
356          will open a pop up window to configure the job in. If there are more plugins,
357          that support the current context, then the table exporter the first thing will
358          be to choose which plugin to use - in this case
359          <guilabel>Table exporter</guilabel>
360          . Confirm the choice and go to next window by clicking on
361          <guibutton>Next</guibutton>
362          .
363        </para>
364        <helptext external_id="simpleexport.options" title="Table-export options">
365          <para>
366            In this window are the options set, which the table exporter should use when
367            exporting the table. See the list below for more information about each
368            option.
369            <variablelist>
370              <title>Export options</title>
371              <varlistentry>
372                <term>
373                  <guilabel>Format</guilabel>
374                </term>
375                <listitem>
376                  <para>
377                    The generated file can be either a tab-separated text file
378                    or a XML file. In the text file will the columns be tab
379                    separated and each row represent a row in the list. The
380                    XML-file option will generate a tag for each item and these
381                    will contain a child tag with property value for each
382                    selected column.
383                  </para>
384                </listitem>
385              </varlistentry>
386              <varlistentry>
387                <term>
388                  <guilabel>Which items?</guilabel>
389                </term>
390                <listitem>
391                  <para>
392                    This option decide which items that should be included in
393                    the exported data.
394                    <itemizedlist>
395                      <listitem>
396                        <para>
397                          Selected items(only available if items have been
398                          selected on the list page). Only selected items
399                          will be exported to the file.
400                        </para>
401                      </listitem>
402                      <listitem>
403                        <para>
404                          Current page. Exports all items viewed on the
405                          current list page.
406                        </para>
407                      </listitem>
408                      <listitem>
409                        <para>
410                          All pages. Items on all pages will be exported
411                          to the file.
412                        </para>
413                      </listitem>
414                    </itemizedlist>
415                  </para>
416                </listitem>
417              </varlistentry>
418              <varlistentry>
419                <term>
420                  <guilabel>Which columns?</guilabel>
421                </term>
422                <listitem>
423                  <para>
424                    Names of those columns that should be included in the export
425                    should be listed in the left list-box. A column name is
426                    moved to the other list-box by first marking it and then
427                    clicking on one of the buttons located between the
428                    list-boxes.
429                  </para>
430                  <para>
431                    The order in which the columns should be exported in can be
432                    changed with the buttons to the left of the list. Simply
433                    mark a name of a column and click on the buttons to move the
434                    name either up or down in the list.
435                  </para>
436                  <tip>
437                    <title>Using presets</title>
438                    <para>
439                      Use the drop down list of presets, located under the
440                      option name, to easily get predefined or own presets of
441                      column settings.
442                    </para>
443                  </tip>
444                </listitem>
445              </varlistentry>
446              <varlistentry>
447                <term>
448                  <guilabel>Save as</guilabel>
449                </term>
450                <listitem>
451                  <para>
452                    The last option is where the file with the exported data
453                    should be saved. Leave the text field empty if the file is
454                    to be downloaded immediately or enter a path within base2's
455                    file system to store the file on the server. Check
456                    <guilabel>Overwrite existing file</guilabel>
457                    if an already existing file with the same name should be
458                    overwritten. Click on
459                    <guibutton>Ok</guibutton>
460                    to proceed when all options have been set for the export.
461                  </para>
462                </listitem>
463              </varlistentry>
464            </variablelist>
465          </para>
466        </helptext>
467        <para>
468          The rest of the configuration process is the same as for all the other export
469          plugins.
470        </para>
471      </sect3>
472    </sect2>
473  </sect1>
Note: See TracBrowser for help on using the repository browser.