Changeset 3200


Ignore:
Timestamp:
Mar 21, 2007, 4:09:02 PM (15 years ago)
Author:
Martin Svensson
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/userdoc/import_export_data.xml

    r3183 r3200  
    11<?xml version="1.0" encoding="UTF-8"?>
    22<!DOCTYPE chapter PUBLIC
    3     "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
    4     "http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd">
     3  "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
     4  "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
    55<!--
    66  $Id$
     
    3030  <title>Import and export of data</title>
    3131  <para>
    32     To be able to work with data in BASE 2 it first has to be imported into the database before
    33     it can be used by/in the environment. The same is for working outside BASE with data in the
    34     database, it first has to be exported. These two actions, importing and exporting, are done
     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
    3535    through the plugin interface.
    3636  </para>
    3737  <para>
    3838    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. There is a collection of plugins,
    40     core plugins, that comes with the installation of BASE2 and are administrated by the
    41     administrator or a similar user that has at least write permission on plugins. The list with
    42     these core plugins can be found at
     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
    4351    <ulink
    44       url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html#import">
    45       http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html#import
     52      url="http://base.thep.lu.se/chrome/site/doc/admin/plugin_configuration/coreplugins.html">
     53      base2's homepage
    4654    </ulink>
    47     . There are also  configuration examples for some of the core plugins.  The
     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
    4860    <guibutton>Import</guibutton>
    4961    or
    5062    <guibutton>Export</guibutton>
    51     button will be available in a page's toolbar if the current item type is supported by one or
    52     many import and export plugins respectively that the logged in user has permission to use.
    53     <note>
    54       <title>Missing/unavailable button</title>
    55       <para>
    56         The logged in user does usually not have enough permission on the expected plugin if
    57         the import- or export button is unavailable or not visible. Contact the
    58         administrator or similar user that has permission to administrate the plugins.
    59       </para>
    60     </note>
     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.
    6166  </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>
    6275  <para>
    63     Following subsections contains information how to go about when importing or exporting data
     76    Following subsections contains information how to proceed when importing or exporting data
    6477    in BASE2.
    6578  </para>
    66 
    6779  <sect1 id="import_export_data.import">
    6880    <title>Import</title>
     
    7082      Click on
    7183      <guibutton>Import</guibutton>
    72       in the toolbar to import data into BASE2's database. This will open a pop-up window where the
    73       job, that shall perform the data import, is going to be configured. More about jobs and
    74       what a job is can be found under
     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
    7587      <xref linkend="jobs" />
    7688      .
    7789    </para>
     90
    7891    <sect2 id="import_export_data.import.plugin_fileformat">
    7992      <title>Select plugin and file format</title>
    80       <para>
    81         The first thing to do when configuring a job is to set which import plugin and file
    82         format to use alternatively let the interface choose suitable plugin/fileformat,
    83         <xref linkend="import_export_data.import.plugin_fileformat.autodetect" />
    84         , based on the file that shall be imported.
    85       </para>
    86 
    87       <sect3 id="import_export_data.import.plugin_fileformat.autodetect">
    88         <title>Auto detect</title>
     93      <helptext external_id="import.selectplugin"
     94        title="Select plugin and file format for data import">
    8995        <para>
    90           This option is set by default in both plugin- and file format drop down lists
    91           when the pop-up window appear and it lets the BASE2 plugin-interface to choose
    92           plugin and file format by validating the file that contains the data that shall
    93           be imported.
    94         </para>
    95         <note>
    96           <title>About auto detect</title>
    97           <para>
    98             Not all plugins support auto detection. Those which do are marked in the drop
    99             down list with a
    100             <guilabel>X</guilabel>
    101             .
    102           </para>
    103         </note>
    104         <para>
    105           Set either both plugins and file formats or only file format to auto detect.
    106           Click then on
    107           <guibutton>Next</guibutton>
    108           to go to the next window where the file to import from is selected. Press
    109           <guibutton>Browse...</guibutton>
    110           in this window to browse the BASE2 file system after the import file. If the
    111           file isn't in the file system it has to be uploaded first before it's possible
    112           to use it, read more about this under
    113           <xref linkend="file_system" />
     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" />
    114100          .
    115101        </para>
    116102
    117         <para>
    118           Proceed by clicking on
    119           <guibutton>Next</guibutton>
    120           . If a file format and plugin compatible to the selected file could be found,
    121           the next window is where the job parameters should be configured and with the
    122           file parameter already set to the file that was selected earlier. Is there on
    123           the other hand no compatible file format or plugin found there will be an error
    124           message, that describes what went wrong.
    125         </para>
    126         <tip>
    127           <title>Recommendation</title>
    128           <para>
    129             Use the default settings, auto detect, to save clicks and configuration
    130             time.
    131           </para>
    132         </tip>
    133       </sect3>
    134 
    135       <sect3 id="import_export_data.import.plugin_fileformat.plugin">
    136         <title>Plugin</title>
    137         <para>
    138           Available import plugins that the logged in user has permission to use and that
    139           support the
    140           <indexterm>
    141             <primary>current context</primary>
    142           </indexterm>
    143           also, can be found in the pop-up window's drop-down-list with plugins . Select the
    144           appropriate import plugin for the job from this list. A short description about
    145           what the selected plugin does can be found at the bottom of the frame. More
    146           information about the plugin can be found under the menu choice
    147           <menuchoice>
    148             <guimenu>Administrate</guimenu>
    149             <guimenuitem>Plugins</guimenuitem>
    150             <guisubmenu>Definitions</guisubmenu>
    151           </menuchoice>
    152         </para>
    153       </sect3>
    154 
    155       <sect3 id="import_export_data.import.plugin_fileformat.fileformat">
    156         <title>File format</title>
    157         <para>
    158           The drop down list of
    159           <indexterm>
    160             <primary>file format</primary>
    161           </indexterm>
    162           contains available file formats for the selected plugin. A file format configure
    163           a plugin how a import file should be parsed. Information about each file format
    164           can be found under the menu choice
    165           <menuchoice>
    166             <guimenu>Administrate</guimenu>
    167             <guimenuitem>Plugins</guimenuitem>
    168             <guisubmenu>Configurations</guisubmenu>
    169           </menuchoice>
    170         </para>
    171         <para>
    172           Proceed to next window by clicking on
    173           <guibutton>Next</guibutton>
    174         </para>
    175       </sect3>
     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>
    176191    </sect2>
    177192
     
    179194      <title>Job parameters</title>
    180195      <para>
    181         This window contains of one top line with the names of the selected plugin and
     196        This window contains of a top line with the names of the selected plugin and
    182197        configuration, a list with parameters to the left, area for input fields to the
    183198        right and buttons to proceed with at the bottom. Which the parameters in the list
     
    186201        <guilabel>File</guilabel>
    187202        parameter (already set if auto detect is used) which holds the file to import the
    188         data from. A click on a parameter in the list to will display an input field and a
     203        data from. A click on a parameter in the list will display an input field and a
    189204        description to the right of the list. Parameters that have a
    190205        <guilabel>X</guilabel>
    191         in front of their names has already a value set and those parameter, which names are
    192         marked with a rectangle, are required and need to be set before continuing with the
    193         job configuration. There will be an error message if not all required parameters had
    194         been set.
     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.
    195210      </para>
    196211      <para>
     
    198213        <guibutton>Next</guibutton>
    199214        . In this window should information about the job be filled in, like name and
    200         description. Where name is required and need to have value. There is also an option
    201         if the user want to get a message or not after the job is done. A ticked check-box
    202         here will send a message to the owner, after the job finished, with information
    203         about how the job execution went.
     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.
    204219      </para>
    205220      <para>
     
    208223        when everything is set will end the job configuration and place the job in the BASE
    209224        2 server's job queue. A self-refreshing window appears with information about the
    210         job's status and execution time. The job isn't dependent on the status window to run
    211         and therefore can it be closed without interrupting the execution.
     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.
    212229      </para>
    213230      <tip>
     
    229246    <para>
    230247      Before data from BASE 2's database can be used outside the program, it first had to be
    231       exported to a file which then can be downloaded to a local path from the BASE
    232       file system.
     248      exported to a file which then can be downloaded to a local path from the BASE file
     249      system.
    233250    </para>
    234251    <para>
     
    236253      on
    237254      <guibutton>Export...</guibutton>
    238       in the toolbar, this will open a pop-up window where the job can be configured. The first
    239       thing in the configuration process is to choose what plugin the job should use and a
    240       configuration, for those plugins that require that. More information about the export
    241       plugins can be read in each plugin's documentation, except for the standard table
     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
    242259      exporter that is described further down on this page. The list of export plugins that
    243260      are included in the current installation of BASE 2 can be found at
     
    304321          Clicking on
    305322          <guibutton>Export...</guibutton>
    306           will open a pop up window to configure the job in. If there are more plugins
    307           then the table exporter that support the current context, the first thing to do
    308           then is to choose which plugin to use - in this case
     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
    309326          <guilabel>Table exporter</guilabel>
    310327          . Confirm the choice and go to next window by clicking on
     
    312329          .
    313330        </para>
    314         <para>
    315           In this window should the options to use in table exporter be set. See the list
    316           below for more information about each option.
    317           <variablelist>
    318             <title>Export options</title>
    319             <varlistentry>
    320               <term>
    321                 <guilabel>Format</guilabel>
    322               </term>
    323               <listitem>
    324                 <para>
    325                   The generated file can be either a tab-separated text file or a
    326                   XML file. In the text file will the columns be tab separated and
    327                   each row represent a row in the list. The XML-file option will
    328                   generate a tag for each item and these will contain a child tag
    329                   with property value for each selected column.
    330                 </para>
    331               </listitem>
    332             </varlistentry>
    333             <varlistentry>
    334               <term>
    335                 <guilabel>Which items?</guilabel>
    336               </term>
    337               <listitem>
    338                 <para>
    339                   This option decide which items that should be included in the
    340                   exported data.
    341                   <itemizedlist>
    342                     <listitem>
    343                       <para>
    344                         Selected items(only available if items have been
    345                         selected on the list page). Only selected items will
    346                         be exported to the file.
    347                       </para>
    348                     </listitem>
    349                     <listitem>
    350                       <para>
    351                         Current page. Exports all items viewed on the
    352                         current list page.
    353                       </para>
    354                     </listitem>
    355                     <listitem>
    356                       <para>
    357                         All pages. Items on all pages will be exported to
    358                         the file.
    359                       </para>
    360                     </listitem>
    361                   </itemizedlist>
    362                 </para>
    363               </listitem>
    364             </varlistentry>
    365             <varlistentry>
    366               <term>
    367                 <guilabel>Which columns?</guilabel>
    368               </term>
    369               <listitem>
    370                 <para>
    371                   Names of those columns that should be included in the export
    372                   should be listed in the left list-box. A column name is moved to
    373                   the other list-box by first marking it and then clicking on one
    374                   of the buttons located between the list-boxes.
    375                 </para>
    376                 <para>
    377                   The order in which the columns should be exported in can be
    378                   changed with the buttons to the left of the list. Simply mark a
    379                   name of a column and click on the buttons to move the name
    380                   either up or down in the list.
    381                 </para>
    382                 <tip>
    383                   <title>Using presets</title>
     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>
    384342                  <para>
    385                     Use the drop down list of presets, located under the option
    386                     name, to easily get predefined or own presets of column
    387                     settings.
     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.
    388349                  </para>
    389                 </tip>
    390               </listitem>
    391             </varlistentry>
    392             <varlistentry>
    393               <term>
    394                 <guilabel>Save as</guilabel>
    395               </term>
    396               <listitem>
    397                 <para>
    398                   The last option is where the file with the exported data should
    399                   be saved. Leave the text field empty if the file is to be
    400                   downloaded immediately or enter a path within base2's file system
    401                   to store the file on the server. Check
    402                   <guilabel>Overwrite existing file</guilabel>
    403                   if an already existing file with the same name should be
    404                   overwritten. Click on
    405                   <guibutton>Ok</guibutton>
    406                   to proceed when all options have been set for the export.
    407                 </para>
    408               </listitem>
    409             </varlistentry>
    410           </variablelist>
    411         </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>
    412433        <para>
    413434          The rest of the configuration process is the same as for all the other export
    414           plugins
     435          plugins.
    415436        </para>
    416437      </sect3>
Note: See TracChangeset for help on using the changeset viewer.