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

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

Some changes in the chapter of import and export of data in the documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 17.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC
3  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: import_export_data.xml 3200 2007-03-21 15:09:02Z martin $
7 
8  Copyright (C) Authors contributing to this file.
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<chapter id="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 have
34    to be exported before it can be used. These two actions, importing and exporting, are done
35    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="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html">
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>
90
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
98          plugin/file 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>
102
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>
119
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>
139
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...</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>
192
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>
243
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. Click
253      on
254      <guibutton>Export...</guibutton>
255      in the toolbar, which will open a pop-up window where the job can be configured. The
256      first thing in the configuration process is to choose which plugin the job should use
257      and a configuration, for those plugins that require that. More information about the
258      export plugins can be read in each plugin's documentation, except for the standard table
259      exporter that is described further down on this page. The list of export plugins that
260      are included in the current installation of BASE 2 can be found at
261      <ulink
262        url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html#export">
263        http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html#export
264      </ulink>
265    </para>
266    <para>
267      Click on
268      <guibutton>Next</guibutton>
269      to show the configuration of parameters for the job. Common for all export plugins is
270      the file parameter that decide where the export data should be saved. Some plugins
271      support the option of download immediately which let the user to download the exported
272      data to a local file system, by leaving the file parameter empty. For saving the
273      exported data within the file system of BASE, it's recommended to use the
274      <guibutton>Browse...</guibutton>
275      button to get the right path and then complement it with the file's name.
276    </para>
277    <para>
278      Click on
279      <guibutton>Next</guibutton>
280      to proceed to next configuration window.
281    </para>
282    <para>
283      If the file parameter were left empty and immediately download was chosen the new window
284      will have a
285      <guibutton>Download</guibutton>
286      button to specify where the data should be saved on the local computer.
287    </para>
288    <para>
289      But if the file should be saved within the file system of BASE instead, there will be a
290      window where the job should get a name and optionally a description. By then clicking on
291      <guibutton>Finish</guibutton>
292      the configuration process will end and the job will be put in the job queue. A
293      self-refreshing window appears with information about the job's status and execution
294      time. The job isn't dependent on the status window to run and it therefore be closed
295      without interrupting the execution of the job.
296    </para>
297    <tip>
298      <title>View job status</title>
299      <para>
300        A job's status can be viewed at any time by opening it from the job list page,
301        <menuchoice>
302          <guimenuitem>View</guimenuitem>
303          <guimenuitem>Jobs</guimenuitem>
304        </menuchoice>
305        .
306      </para>
307    </tip>
308    <sect2 id="import_export_data.export.table_export">
309      <title>Table export</title>
310      <para>
311        The table exporter is a common export plugin for all list pages in BASE 2 and it
312        makes it possible for the user to export the list to either a XML-file or a
313        tab-separated text file. The table exporter supports all list pages and is started,
314        like the other export plugins, by clicking on
315        <guibutton>Export...</guibutton>
316        in the toolbar.
317      </para>
318      <sect3 id="import_export_data.export.table_export.configuration">
319        <title>Configuration</title>
320        <para>
321          Clicking on
322          <guibutton>Export...</guibutton>
323          will open a pop up window to configure the job in. If there are more plugins,
324          that support the current context, then the table exporter the first thing will
325          be to choose which plugin to use - in this case
326          <guilabel>Table exporter</guilabel>
327          . Confirm the choice and go to next window by clicking on
328          <guibutton>Next</guibutton>
329          .
330        </para>
331        <helptext external_id="simpleexport.options" title="Table-export options">
332          <para>
333            In this window are the options set, which the table exporter should use when exporting the table. See
334            the list below for more information about each option.
335            <variablelist>
336              <title>Export options</title>
337              <varlistentry>
338                <term>
339                  <guilabel>Format</guilabel>
340                </term>
341                <listitem>
342                  <para>
343                    The generated file can be either a tab-separated text file
344                    or a XML file. In the text file will the columns be tab
345                    separated and each row represent a row in the list. The
346                    XML-file option will generate a tag for each item and these
347                    will contain a child tag with property value for each
348                    selected column.
349                  </para>
350                </listitem>
351              </varlistentry>
352              <varlistentry>
353                <term>
354                  <guilabel>Which items?</guilabel>
355                </term>
356                <listitem>
357                  <para>
358                    This option decide which items that should be included in
359                    the exported data.
360                    <itemizedlist>
361                      <listitem>
362                        <para>
363                          Selected items(only available if items have been
364                          selected on the list page). Only selected items
365                          will be exported to the file.
366                        </para>
367                      </listitem>
368                      <listitem>
369                        <para>
370                          Current page. Exports all items viewed on the
371                          current list page.
372                        </para>
373                      </listitem>
374                      <listitem>
375                        <para>
376                          All pages. Items on all pages will be exported
377                          to the file.
378                        </para>
379                      </listitem>
380                    </itemizedlist>
381                  </para>
382                </listitem>
383              </varlistentry>
384              <varlistentry>
385                <term>
386                  <guilabel>Which columns?</guilabel>
387                </term>
388                <listitem>
389                  <para>
390                    Names of those columns that should be included in the export
391                    should be listed in the left list-box. A column name is
392                    moved to the other list-box by first marking it and then
393                    clicking on one of the buttons located between the
394                    list-boxes.
395                  </para>
396                  <para>
397                    The order in which the columns should be exported in can be
398                    changed with the buttons to the left of the list. Simply
399                    mark a name of a column and click on the buttons to move the
400                    name either up or down in the list.
401                  </para>
402                  <tip>
403                    <title>Using presets</title>
404                    <para>
405                      Use the drop down list of presets, located under the
406                      option name, to easily get predefined or own presets of
407                      column settings.
408                    </para>
409                  </tip>
410                </listitem>
411              </varlistentry>
412              <varlistentry>
413                <term>
414                  <guilabel>Save as</guilabel>
415                </term>
416                <listitem>
417                  <para>
418                    The last option is where the file with the exported data
419                    should be saved. Leave the text field empty if the file is
420                    to be downloaded immediately or enter a path within base2's
421                    file system to store the file on the server. Check
422                    <guilabel>Overwrite existing file</guilabel>
423                    if an already existing file with the same name should be
424                    overwritten. Click on
425                    <guibutton>Ok</guibutton>
426                    to proceed when all options have been set for the export.
427                  </para>
428                </listitem>
429              </varlistentry>
430            </variablelist>
431          </para>
432        </helptext>
433        <para>
434          The rest of the configuration process is the same as for all the other export
435          plugins.
436        </para>
437      </sect3>
438    </sect2>
439  </sect1>
440</chapter>
Note: See TracBrowser for help on using the repository browser.