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

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

References #528. File management doc.

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