source: trunk/doc/src/docbook/userdoc/jobs.xml @ 4889

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: jobs.xml 4889 2009-04-06 12:52:39Z nicklas $
  
  Copyright (C) 2007 Jari Häkkinen, Peter Johansson, Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="jobs">
  <?dbhtml dir="jobs"?>
  <title>Jobs</title>
  <para>Job is a configured task performed by a plug-in.</para>
  <para>
    Creating/configuring a job is made from a context, which is supported by the plug-in you want
    to use. If no particularly context is needed, the job configuration is started from the
    plug-in's single item view.
  </para>
  <para>
    Some jobs can be configured to execute immediately (for a few plug-ins it is mandatory that
    the job runs immediately), but normally jobs are placed in the job queue after they have
    been configured. The jobs will then be picked out for execution depending on their priority
    and estimated execution time.
  </para>


  <sect1 id="jobs.properties">
    <title>Properties</title>
    Click on
    <menuchoice>
      <guimenu>View</guimenu>
      <guimenuitem>Jobs</guimenuitem>
    </menuchoice>
    to list your jobs.
    <para>
      Details of a single job is displayed in a pop-up window. This window opens either if you
      click on a job's name from the list page of jobs or when a job configuration is
      finished. The window contain two tabs, one with information about the job and another
      with the parameters for the plug-in used in the job.
    </para>
    <helptext external_id="job.view.parameters" title="Job parameters">
      <para>
        The values listed on the <guilabel>Parameters</guilabel> tab depends on 
        what the plug-in needs from the user. If a specific plug-in configuration was
        use, those parameters are also listed here.
      </para>
    </helptext>
    <helptext external_id="job.view.properties" title="Job properties">
      <para>
        The properties are set either when configuring the job or by the system. No
        parameters can be edit after a job is created.
        <variablelist>
          <varlistentry>
            <term>
              <guilabel>Name</guilabel>
            </term>
            <listitem>
              <para>
                The name of the job is set in the last step of a job configuration.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <optional>
                <guilabel>Description</guilabel>
              </optional>
            </term>
            <listitem>
              <para>
                A description of the job. Like the name-property it can be set in
                the job configuration.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Type</guilabel>
            </term>
            <listitem>
              <para>
                The type of job, which is depending on the plug-in that is used. It
                can be one of these five:
                <itemizedlist>
                  <listitem>Export</listitem>
                  <listitem>Import</listitem>
                  <listitem>Analysis</listitem>
                  <listitem>Intensity</listitem>
                  <listitem>Other</listitem>
                </itemizedlist>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Priority</guilabel>
            </term>
            <listitem>
              <para>Priority the job has in the job queue.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Status</guilabel>
            </term>
            <listitem>
              <para>
                Shows the status of the job. A job can have one of following status.
                <itemizedlist>
                  <listitem>
                    <para>
                      <emphasis>Not configured</emphasis>
                      - The plug-in has not been configured properly and is not
                      placed in the job queue.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Waiting</emphasis>
                      - Job is waiting in the job queue.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Executing</emphasis>
                      - Job is being executed.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Done</emphasis>
                      - Indicates that the job is finished.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Error</emphasis>
                      - The job was aborted cause of some error.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Preparing</emphasis>
                      - Doing some preparing tasks befor executing the job.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <emphasis>Aborting</emphasis>
                      - Job has received an abort signal and tries to abort the
                      work.
                    </para>
                  </listitem>
                </itemizedlist>
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Status message</guilabel>
            </term>
            <listitem>
              <para>
                A message, given by the plug-in, with more information about the
                status.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Percent complete</guilabel>
            </term>
            <listitem>
              <para>
                Progress of the job. How detailed this is depends on how often the
                plug-in reports it's progress.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Created</guilabel>
            </term>
            <listitem>
              <para>
                Date and time when the job was created and registerd in the database.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Started</guilabel>
            </term>
            <listitem>
              <para>
                Date and time when execution of the job started.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Ended</guilabel>
            </term>
            <listitem>
              <para>
                Date and time when the job stopped running. Either cause of it was
                finished, aborted or interrupted by an error.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Running time</guilabel>
            </term>
            <listitem>
              <para>Time the job has been running.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Server</guilabel>
            </term>
            <listitem>
              <para>Name of the server, where the job was performed.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Job agent</guilabel>
            </term>
            <listitem>
              <para>
                The job agent the job is/was running on. It is also
                possible to set this value before a job is executed. If that
                has been done only the selected job agent will accept the job.
                This options is normally only given to powers users and
                needs the <emphasis>Select job agent</emphasis> permission.
                See <xref linkend="user_administration.roles.edit" />. 
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>User/Owner</guilabel>
            </term>
            <listitem>
              <para>The user who created/configured the job.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Experiment</guilabel>
            </term>
            <listitem>
              <para>Name of the experiment which the job was configured within.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Plugin</guilabel>
            </term>
            <listitem>
              <para>The plug-in to use in the job.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>
              <guilabel>Configuration</guilabel>
            </term>
            <listitem>
              <para>Name of the plug-in configuration that is used.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
      
      <para>
        Depending on the status of the job, there may also be one or
        more buttons on the form.
      </para>
      
      <variablelist>
      <varlistentry>
        <term><guibutton>Refresh</guibutton></term>
        <listitem>
          <para>
          Update the page with the information. This button is available as long
          as the job has not finished. This button is only for the impatient since
          the page will automatically refresh every ten seconds anyway.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guibutton>Abort</guibutton></term>
        <listitem>
          <para>
          Aborts a job that is running or hasn't started yet. Jobs that hasn't
          started can always be aborted. Jobs that are already eecuting can only
          be aborted if the plug-in supports it. The button will not be visible if
          the plug-in doesn't supports being aborted.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guibutton>Restart</guibutton></term>
        <listitem>
          <para>
          Retry a failed job. Sometimes the reason that a job failed can be fixed. For
          example, by changing the permissions on items the job needs to access. Use
          this button to place the job in the job queue again. It is not possible to
          change job parameters with one exception, if the job uses a plug-in configuration
          and the configuration has been changed it is possible to select if
          the old or new configuration values should be used. 
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><guibutton>Close</guibutton></term>
        <listitem>
          <para>
          Close the window.
          </para>
        </listitem>
      </varlistentry>
      
      </variablelist>
      
    </helptext>
  </sect1>
</chapter>