<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- $Id: stats.xml,v 1.2 2007/07/18 12:36:16 ea Exp $ -->
<chapter id="statistic-module">
<title>Stats module</title>

<para>
Stats and reports are essential for companies.
On the basis of stats, information can be evaluated and rated,
and eventually informed decisions can be made.
</para>

<para>
A stats module should meet a multitude of requirements:
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        Various OTRS modules are to be evaluated,
        </para>
    </listitem>
    <listitem>
        <para>
        the user permission settings of the respective installation should be
        considered,
        </para>
    </listitem>
    <listitem>
        <para>
        it should be able to generate complex statistics,
        </para>
    </listitem>
    <listitem>
        <para>
        configuration of stats should be easy and quick,
        </para>
    </listitem>
    <listitem>
        <para>
        performance should be high,
        </para>
    </listitem>
    <listitem>
        <para>
        and a number of output variants should be supported.
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
The stats module tries to meet all these requirements. The core
feature is a GUI which allows to configure stats with the click
of a mouse.
</para>

<para>
Statistical elements, i.e. files which supplement the functionalities of the
stats module for specific requirements, can be integrated to model complex
stats.
</para>

<para>
All requirements concerning the evaluation of personal data have been
considered. It is, for instance, not possible to directly evaluate
the activities of individual agents in the standard configuration.
</para>

<para>
All things considered, the stats module enables OTRS users a quick
and easy evaluation of the activities on their system.
</para>

<sect1 id="stats-usage" >
<title>Handling of the module by the agent</title>

<para>
As soon as the stats module has been installed and configured
successfully by the OTRS admin, the navigation
bar of every agent with read and/or write rights displays
the additional module link "Stats".
</para>

<para>
<screenshot>
<screeninfo>The stats module</screeninfo>
<graphic fileref="screenshots/stats-icon.png" scale="40" srccredit="stats-icon - Screenshot" />
</screenshot>
</para>

<para>
After the link has been activated, various action links for the stats
module are shown in the navigation bar.
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        "Overview"
        </para>

        <para>
        is also shown automatically if the module link "Stats"
        is chosen
        </para>
    </listitem>
    <listitem>
        <para>
        "New"
        </para>

        <para>
        rw rights required
        </para>
    </listitem>
    <listitem>
        <para>
        "Import"
        </para>

        <para>
        rw rights required
        </para>
    </listitem>
    <listitem>
        <para>
        "Preferences"
        </para>

        <para>
        OTRS user interface for personal settings
        </para>
    </listitem>
</itemizedlist>
</para>

<sect2 id="stats-overview" >
<title>Overview</title>

<para>
A list of all pre-configured stats the agent can use.
</para>

<para>
The easiest way to access the overview is to select the "Stat"
link and then the action link "Overview" in the navigation bar. The
stats overview is called up automatically when the module
link "Stats" in the navigation bar is chosen.
</para>

<para>
<screenshot>
<screeninfo>Overview with standard stats</screeninfo>
<graphic fileref="screenshots/stats-overview.png" scale="40" srccredit="stats-overview - Screenshot" />
</screenshot>
</para>

<para>
The following information is provided about the stats listed
in the overview:
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        "Stat#"
        </para>

        <para>
        the unique stat number
        </para>
    </listitem>
    <listitem>
        <para>
        "Title"
        </para>

        <para>
        the stat title
        </para>
    </listitem>
    <listitem>
        <para>
        "Object"
        </para>

        <para>
        Object used for generating the stat. In the case of a static stat
        no object is displayed as no dynamic object is used for the
        generation.
        </para>
    </listitem>
    <listitem>
        <para>
        "Description"
        </para>

        <para>
        Excerpt of the description
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
A results display can be found above the list. It provides
information about the number of accessible stats. If the
overview covers more than one page, the agent can browse
through the different pages.
</para>

<para>
The agents can sort the stats according to their needs
with the blue "up" and "down" icons in the headline.
</para>

<para>
To generate a stat the right one is chosen by clicking the
link with the stat number which leads to the "View" user interface.
</para>

<para>
A few sample stats are imported when the stats module
is used for the first time.
</para>

</sect2>

<sect2 id="stats-viewing-generating">
<title>Generate and view stats</title>

<para>
The view user interface is supposed to provide the agent with an
overview of the stat's pre-configuration.
</para>

<para>
The agents can perform configurations within the range of the
pre-configuration. The originator of a stat configuration can determine
the degree to which the stat generation can be influenced. The most extreme
examples of this would be agents who cannot effect any changes or can
change all attributes, respectively.
</para>

<para>
<screenshot id="stats-view-screenshot" >
<screeninfo>Stat view</screeninfo>
<graphic fileref="screenshots/stats-view.png" scale="40" srccredit="stats-view - Screenshot" />
</screenshot>
</para>

<para>
The page shows the following:
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        the menu links
        </para>

        <para>
        <itemizedlist>
            <listitem>
                <para>
                "Back"
                </para>

                <para>
                Link back to the starting point
                </para>
            </listitem>
            <listitem>
                <para>
                "Edit"
                </para>

                <para>
                Link to the edit user interface of the stat
                (rw rights required)
                </para>
            </listitem>
            <listitem>
                <para>
                "Delete"
                </para>

                <para>
                Delete a stat (rw rights required)
                </para>
            </listitem>
            <listitem>
                <para>
                "Export Config"
                </para>

                <para>
                Export a stat configuration via file download
                (rw rights required)
                </para>

                <para>
                Usage: export and import functions allow for the convenient
                creation and testing of stats on test systems and subsequent
                easy integration into the production system.
                </para>
            </listitem>
        </itemizedlist>
        </para>
    </listitem>
    <listitem>
        <para>
        Meta data (grey block on the right)
        </para>

        <para>
        Provides information about the stat originators. Information
        is provided about who created the stat and when as well
        as who last changed it.
        </para>
    </listitem>
    <listitem>
        <para>
        The stat data itself
        </para>

        <para>
        can be found in the central block of the user interface.
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
In the following, details to the stat input are provided as this input
contains the core information.
</para>

<para>
General information is provided first.
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        "Stat#"
        </para>

        <para>
        The stat number
        </para>
    </listitem>
    <listitem>
        <para>
        "Title"
        </para>

        <para>
        The stat title
        </para>
    </listitem>
    <listitem>
        <para>
        "Object"
        </para>

        <para>
        Object used for generating the stat
        </para>
    </listitem>
    <listitem>
        <para>
        "Description"
        </para>

        <para>
        The description provides more detailed information
        about the intention of the
        stat.
        </para>
    </listitem>
    <listitem>
        <para>
        "Format"
        </para>

        <para>
        Stat output format. Depending on the configuration, following output
        formats can be chosen:
        </para>

        <para>
        <itemizedlist>
            <listitem>
            <para>
            "CSV" -&gt; stat download in csv format
            </para>
        </listitem>
        <listitem>
            <para>
            "Print" -&gt; printable html or pdf table
            </para>
        </listitem>
        <listitem>
            <para>
            Graph-lines
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-bars"
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-hbars"
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-points"
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-lines-points"
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-area"
            </para>
        </listitem>
        <listitem>
            <para>
            "Graph-pie"
            </para>
        </listitem>
    </itemizedlist>
    </para>
    </listitem>
    <listitem>
        <para>
        "Graphsize"
        </para>

        <para>
        size which the graphic / chart may have
        </para>

        <para>
        <itemizedlist>
            <listitem>
                <para>
                indicated in pixels
                </para>
                <para>
                this option is only given when the stat pre-configuration
                allows for a chart.
                </para>
            </listitem>
            <listitem>
                <para>
                All generally usable graphic sizes are configured by the
                OTRS admin in the SysConfig. The agent can then pre-select all
                relevant formats while configuring the stats.
                </para>
            </listitem>
        </itemizedlist>
        </para>
    </listitem>
    <listitem>
        <para>
        "Sum rows"
        </para>

        <para>
        Indicates whether the stat is amended by a column whose cells
        state the sums of the respective rows.
        </para>
    </listitem>
    <listitem>
        <para>
        "Sum columns"
        </para>

        <para>
        Indicates whether the stat is amended by a
        row whose cells state the sum of the
        respective columns
        </para>
    </listitem>
    <listitem>
        <para>
        "Cache"
        </para>

        <para>
        Indicates whether the generated stats are
        cached in the file system.
        </para>
    </listitem>
    <listitem>
        <para>
        "Valid"
        </para>

        <para>
        The "valid" element is set "invalid" if a pre-configured statistic
        is still being created or must not be used temoprarily for certain
        reasons. Also the "Start" button in the bottom right of the
        block is then no longer displayed. The stat can no longer
        be generated.
        </para>
    </listitem>
    <listitem>
        <para>
        "Exchange axis"
        </para>

        <para>
        Using this function, the agent can exchange the x
        and y axes (only when activated by the OTRS
        administrator).
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
The general information is followed by information about the stat
itself. There are two different stat views:
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        Static stat view
        </para>

        <para>
        Complex stats cannot be generated dynamically. Static stat generators
        can be integrated into the stat module for that reason. They were
        developed specifically for the particular evaluation.
        The various job definitions result in different views.
        </para>

        <para>
        <screenshot>
        <screeninfo>Static stat view</screeninfo>
        <graphic fileref="screenshots/stats-view-static.png" scale="40" srccredit="stats-view-static - Screenshot" />
        </screenshot>
        </para>
    </listitem>
    <listitem>
        <para>
        Dynamic stats can be displayed in two different ways:
        </para>

        <para>
        <itemizedlist>
            <listitem>
                <para>
                Unchangeable settings
                </para>

                <para>
                In this case, the originator of the stat has not allowed
                for alterations on the part of the agent who wants to
                generate a stat.
                </para>
            </listitem>
            <listitem>
                <para>
                changeable settings
                </para>

                <para>
                The pre-configuration of such stats can be changed by the
                agent.
                </para>
            </listitem>
        </itemizedlist>
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
<screenshot>
<screeninfo>Display of a changeable dynamic stat</screeninfo>
<graphic fileref="screenshots/stats-view-configurable.png" scale="40" srccredit="stats-view-configurable - Screenshot" />
</screenshot>
</para>

<para>
Pressing the "start" button at the bottom right end of the block is the
last simple step to generate a stat. There are two possible reasons if
the "start" button is not displayed:
</para>

<para>
<orderedlist numeration="arabic" >
    <listitem>
        <para>
        The stat was set invalid and thus deactivated
        </para>
    </listitem>
    <listitem>
        <para>
        The stat was not configured neatly and is therefore not yet
        executable. In this case, the necessary information can be found
        in the OTRS notification section (below the navigation bar).
        </para>
    </listitem>
</orderedlist>
</para>

<para>
If the settings on the view page are incorrect, the page is shown again
after the "start" button was pushed and information about which input
was incorrect is provided in the notification section.
</para>
</sect2>

<sect2 id="stats-modify-new">
<title>Edit - New</title>

<para>
Agents can call up the edit user interface of the stat module in two
different ways:
</para>

<para>
<orderedlist numeration="arabic">
<listitem>
    <para>
    via the "edit" menu link in the stat view to edit an existing stat
    configuration.
    </para>
</listitem>
<listitem>
    <para>
    via the "new" link in the navigation bar.
    </para>
</listitem>
</orderedlist>
</para>

<para>
These links are only visible to agents with write rights for this module.
</para>

<para>
The stats are edited with a wizard in four steps:
</para>

<para>
<orderedlist numeration="arabic">
<listitem>
    <para>
    General information about the stat
    </para>
</listitem>
<listitem>
    <para>
    Definition of the element for the x axis
    </para>
</listitem>
<listitem>
    <para>
    Definition of the value series
    </para>
</listitem>
<listitem>
    <para>
    Definition of the restrictions
    </para>
</listitem>
</orderedlist>
</para>

<para>
Points 2-4 are only needed for the generation of dynamic stats. For a
static stat only the entering of general information in point 1 is required.
</para>

<para>
Information about how to handle the page is provided below the
input forms on all input user interfaces of the stats module.
</para>

<para>
If incorrect data is entered nevertheless, the previously processed user
interface is displayed again and amended by information about the
incorrect input.
This information can be found in the OTRS notification section. The next
input use interface is only displayed after the form has been filled out
correctly.
</para>

<para>
<orderedlist numeration="arabic" >
<listitem>
    <para>
    "Common specification"
    </para>

    <para>
    The first page of the wizard is the input user interface "Common
    specification". A great number of common specifications and settings
    can be edited on this page.
    </para>

    <para>
    <screenshot>
    <screeninfo>Common specifications of the stat</screeninfo>
    <graphic fileref="screenshots/stats-edit-general.png" scale="40" srccredit="stats-edit-general - Screenshot" />
    </screenshot>
    </para>

    <para>
    <itemizedlist>
        <listitem>
            <para>
            "Title"
            </para>

            <para>
            Should reflect the stat's purpose in a concise manner.
            </para>
        </listitem>
        <listitem>
            <para>
            "Description"
            </para>

            <para>
            More detailed information about the job definition, type of
            configuration parameters etc.
            </para>
        </listitem>
        <listitem>
            <para>
            "Dynamic object"
            </para>

            <para>
            If the OTRS installation provides various dynamic
            objects, one of them can be selected at this step.
            The objects meet the requirements of the particular
            modules.
            </para>
        </listitem>
        <listitem>
            <para>
            "Static file"
            </para>

            <para>
            A static file can be selected at this point. Usually this
            selection is not shown as only static files which
            are not yet assigned to any stats are displayed! If
            "Static file" is displayed, however, it is important to
            tick the option field and select a generation mode
            (dynamic with a dynamic object or static with a file).
            If a static file is selected, the input user interfaces 2-4
            are not shown as the static file contains all configurations
            required.
            </para>
        </listitem>
        <listitem>
            <para>
            "Permission settings"
            </para>

            <para>
            The permission settings facilitate a restriction of the groups (and
            therefore agents) who can later view and generate the
            preconfigured stats. Thus the various stats can be allocated to the
            different departments and work groups needing them. It is possible
            to allocate one stat to various groups.
            </para>

            <para>
            Example 1: the "stats" group was selected. The stat is
            viewable for all users having at least ro rights for the "stats"
            group. As the base requirement for accessing the
            view mode of the stat module in the default configuration is to
            have ro rights in the
            "stats" group, all users with permission to create statistics can view it in this
            configuration.
            </para>

            <para>
            Example 2: a group named "sales" was selected. All users with ro
            rights for the "sales" group can
            see the stat in the view mode and generate it. However, the stat will not be shown to other users
            with permission to generate stats.
            </para>
        </listitem>
        <listitem>
            <para>
            "Format" -  output format of the stat
            </para>

            <para>
            Depending on the configuration, the following output formats
            can be chosen:
            </para>

            <para>
            <itemizedlist>
                <listitem>
                <para>
                "CSV" -&gt; stat output in csv format
                </para>
            </listitem>
            <listitem>
                <para>
                "Print" -&gt; printable html or pdf table
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-lines"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-bars"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-hbars"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-points"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-lines-points"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-area"
                </para>
            </listitem>
            <listitem>
                <para>
                "graph-pie"
                </para>
            </listitem>
        </itemizedlist>
        </para>

        <para>
        More than one format can be selected.
        </para>
    </listitem>
    <listitem>
        <para>
        "Graphsize"
        </para>

        <para>
        Select which size the charts can have.
        </para>

        <para>
        <itemizedlist>
            <listitem>
                <para>
                indicated in pixels
                </para>
            </listitem>
            <listitem>
                <para>
                this selection is only necessary if a graphical output format
                has been chosen under "Format".
                </para>
            </listitem>
            <listitem>
                <para>
                all graphic sizes that can generally be used are
                defined by the OTRS admin in SysConfig. When
                configuring the stat, the agent can pre-select all
                relevant formats.
                </para>
            </listitem>
        </itemizedlist>
        </para>
    </listitem>
    <listitem>
        <para>
        "Sum rows"
        </para>

        <para>
        If "yes" is chosen in the pulldown menu, the stat is amended by a
        column whose cells display the sum of the respective row.
        </para>
    </listitem>
    <listitem>
        <para>
        "Sum columns"
        </para>

        <para>
        Indicates whether the stat is amended by a row whose
        cells contain the sum of the respective column.
        </para>
    </listitem>
    <listitem>
        <para>
        "Cache"
        </para>

        <para>
        The generated stats are cached in the file system if "yes" is selected
        in the pulldown menu. This saves computing power and time if
        the stat is called up again.
        </para>

        <para>
        This function should only be used if the stat's content is no longer
        changing. Thorough checking is required before the caching
        function is used.
        </para>

        <para>
        Caching is automatically prevented in the following situations:
        </para>

        <para>
        <itemizedlist>
            <listitem>
                <para>
                if the stat contains no time designation values (new data is
                added continuously)
                </para>
            </listitem>
            <listitem>
                <para>
                if a time designation value points to the future
                </para>
            </listitem>
        </itemizedlist>
        </para>

        <para>
        If a cached stat is edited, all cached data is deleted.
        </para>
    </listitem>
    <listitem>
        <para>
        "Valid"
        </para>

        <para>
        The "valid" element is set "invalid" if a pre-configured stat is
        still being created or must not be used temoprarily for certain
        reasons. Also the "Start" button in the bottom right of the
        block is no longer displayed. It is impossible to generate the
        stat.
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
By clicking the "Next" button the next user interface of the wizard is
called up.
</para>
</listitem>
<listitem>
    <para>
    "xaxis"
    </para>

    <para>
    The "Common statements" section is followed by the "xaxis" form.
    </para>

    <para>
    <screenshot>
    <screeninfo>Definition of the element for the x axis.</screeninfo>
    <graphic fileref="screenshots/stats-edit-xaxis.png" scale="40" srccredit="stats-edit-xaxis - Screenshot" />
    </screenshot>
    </para>

    <para>
    Configuration of the element used for the depiction of the x axis or,
    if tables are used, of the column name chosen for the stat.
    </para>

    <para>
    First of all, an element is selected using the option field. Then two or more
    attributes of the element must be selected. If no attributes are selected, all
    attributes are used including those added after the configuration of the stat.
    </para>

    <para>
    If the "Fixed" setting is disabled, the agent generating the stat can change the
    attributes of the respective element in the "View" user interface.
    </para>

    <para>
    Time elements are different as time period and scale have to be stated.
    </para>

    <para>
    Type and number of elements result from the used dynamic object
    and vary depending on it.
    </para>

    <para>
    If all input is correct, the "next" button leads to the "Value series"
    form. It is also possible to go back to editing the "common statements"
    section again.
    </para>
</listitem>
<listitem>
    <para>
    "Value series"
    </para>

    <para>
    In the third step of the stat pre-configuration the value series are
    defined. They will lateron form the individual graphs of a diagramm
    or the various series (tabular view).
    </para>

    <para>
    <screenshot>
    <screeninfo>Definition of the value series</screeninfo>
    <graphic fileref="screenshots/stats-edit-valueseries.png" scale="40" srccredit="stats-edit-valueseries - Screenshot" />
    </screenshot>
    </para>

    <para>
    If an element is selected, each chosen attribute corresponds to a
    value series.
    </para>

    <para>
    <example id="stats-value-series-1">
    <title>Definition of a value series - one element</title>

    <para>
    Element Queue:
    </para>

    <para>
    <itemizedlist>
        <listitem>
            <para>
            Value series 1 = Raw
            </para>
        </listitem>
        <listitem>
            <para>
            Value series 2 = Junk
            </para>
        </listitem>
        <listitem>
            <para>
            ....
            </para>
        </listitem>
    </itemizedlist>
    </para>
    </example>
    </para>

    <para>
    If two elements are selected, each selected attribute of the first element
    is combined with an attribute of the second element to form a value series.
    </para>

    <para>
    <example id="stats-value-series-2" >
    <title>Definition of a value series - two elements </title>

    <para>
    Element 1 queue and element 2 status:
    </para>

    <para>
    <itemizedlist>
        <listitem>
            <para>
            Value chain 1 = Raw - open
            </para>
        </listitem>
        <listitem>
            <para>
            Value series 2 = Raw - successfully closed
            </para>
        </listitem>
        <listitem>
            <para>
            Value series 3 = Junk - open
            </para>
        </listitem>
        <listitem>
            <para>
            Value series 4 = Junk - successfully closed
            </para>
        </listitem>
    </itemizedlist>
    </para>
    </example>
    </para>

    <para>
    Selection of three or more elements does not make sense and is therefore
    prevented by an error message.
    </para>

    <para>
    Additionally the same conditions apply to the selection of the attributes
    and the "Fixed" checkbox as to the "Xaxis" selection.
    </para>

    <para>
    <itemizedlist>
        <listitem>
            <para>
            If no attributes of the element are selected, all attributes are used
            including those added after the configuration of the stat.
            </para>
        </listitem>
        <listitem>
            <para>
            If the "Fixed" setting is disabled, the agent generating the
            stat can change the attributes of the respective element.
            </para>
        </listitem>
    </itemizedlist>
    </para>
</listitem>
<listitem>
    <para>
    "Restrictions"
    </para>

    <para>
    The fourth and last step of the pre-configuration is the definition
    of restrictions. These restrictions facilitate to limit the results
    and are comparable to entering data into a search window.
    </para>

    <para>
    <screenshot>
    <screeninfo>Definition of restrictions</screeninfo>
    <graphic fileref="screenshots/stats-edit-restrictions.png" scale="40" srccredit="stats-edit-restrictions - Screenshot" />
    </screenshot>
    </para>

    <para>
    In quite a few cases, no restrictions at all must be set up.
    </para>

    <para>
    After all restrictions are set, the pre-configuration of the stat is finished with
    the "Finish" button and the "View" user interface is called up.
    </para>
</listitem>
</orderedlist>
</para>
</sect2>

<sect2 id="stats-import">
<title>Import</title>

<para>
The import user interface can be accessed by chosing "Import" in the
navigation bar (rw rights required).
</para>

<para>
<screenshot>
<screeninfo>The import user interface</screeninfo>
<graphic fileref="screenshots/stats-import.png" scale="40" srccredit="stats-import - Screenshot" />
</screenshot>
</para>

<para>
Facilitates the import of stats and is, combined with the export function
of the module, a very handy functionality. Stats can be created
and tested conveniently on test systems and be imported into the production
system afterwards.
</para>

<para>
The import is effected by an easy file upload. The "view" user
interface of the imported stat is opened automatically afterwards.
</para>
</sect2>

</sect1>

<sect1 id="stats-managing-the-module">
<title>Administration of the stat module by the OTRS administrator</title>

<para>
This paragraph provides information about the tasks and possibilities
of the OTRS administrator dealing with the stat module.
</para>

<sect2 id="stats-permissions" >
<title>Permission settings, groups and queues</title>

<para>
No new queues and/or groups are created when the stat module is
installed.
</para>

<para>
The default configuration of the module registration gives all agents with
"stats" group permissions access to the stats module.
</para>

<para>
Access according to permission settings:
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        "rw" -&gt; permission to configurate stats
        </para>
    </listitem>
    <listitem>
        <para>
        "ro" -&gt; permission to generate pre-configured stats
        </para>
    </listitem>
</itemizedlist>
</para>

<para>
The OTRS administrator decides whether agents with the permission to
generate pre-configured stats are allocated ro rights in the "stats" group or
whether their respective groups are added in the module registration in SysConfig.
</para>
</sect2>

<sect2 id="stats-sysconfig" >
<title>SysConfig</title>

<para>
SysConfig groups

<link linkend="Framework:Core::Stats" >
Framework:Core::Stats
</link>

,

<link linkend="Framework:Core::Stats::Graph" >
Framework:Core::Stats::Graph
</link>and

<link linkend="Framework:Frontend::Agent::Stats" >
Framework:Frontend::Agent::Stats
</link>

contain all configuration parameters for the basic set-up of the stats module.
Moreover, the configuration parameter

<link linkend="Framework:Frontend::Agent::ModuleRegistration:Frontend::Module_AgentStats" >
$Self-&gt;{'Frontend::Module'}-&gt;{'AgentStats'}
</link>

controls the arrangement and registration of the modules and icons within the
stats module.
</para>
</sect2>

</sect1>

<sect1 id="stats-managing-the-stats-module-by-the-sysadmin" >
<title>Administration of the stats module by the system administrator</title>

<para>
Generally no system administrator is needed for the operation, configuration
and maintenance. However, a little background information for the system
administrator is given at this point.
</para>

<note>
<para>
File paths refer to subdirectories of the OTRS home
directory (in most cases<filename>/opt/otrs</filename>.
</para>
</note>

<sect2 id="stats-db-table" >
<title>Data base table</title>

<para>
All stat configurations are implemented and administrated in XML.
Therefore all stats configurations are stored in the database table
"xml_storage". Other modules whose content is presented in xml
format use this table as well.
</para>

</sect2>

<sect2 id="stats-filelist" >
<title>List of all files</title>

<para>
The following files are necessary for the stats module to work accurately.
</para>

<para>
<itemizedlist>
    <listitem>
        <para>
        <filename>Kernel/System/Stats.pm</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Modules/AgentStats.pm</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/System/CSV.pm</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsOverview.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsDelete.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsEditSpecification.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsEditRestrictions.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsEditXaxis.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsEditValueSeries.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsImport.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsPrint.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/Output/HTML/Standard/AgentStatsView.dtl</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>Kernel/System/Stats/Dynamic/Ticket.pm</filename>
        </para>
    </listitem>
    <listitem>
        <para>
        <filename>bin/mkStats.pl</filename>
        </para>
    </listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="stats-caching" >
<title>Caching</title>

<para>
Whether the results of a stat are to be cached or not can be defined in
the pre-configuration. Cached stat results are stored as files in the
<filename>var/tmp</filename>directory of the OTRS
installation (in most cases<filename>/opt/otrs/var/tmp</filename>).
</para>

<para>
Cached stats can be recognized by the "Stats" prefix.
</para>

<para>
If the data is lost, no major damage is caused.The next time the
stat is called up the stats module will not find the file any more
and thus will generate a new stat  which will probably take
a little longer.
</para>
</sect2>

<sect2 id="stats-mkstats" >
<title>mkStats.pl</title>

<para>
This file is saved in the <filename>bin/</filename>directory.
It facilitates the generation of stats in the command line.
</para>

<para>
The following command line call is exemplary:
</para>

<para>
<programlisting>
bin> perl mkStats.pl -n 10004 -o /output/dir
</programlisting>
</para>

<para>
A stat from the stat configuration "Stat# 10004" is generated and saved
as csv in the <filename>/output/dir</filename>directory.
</para>

<para>
The generated stat can also be sent as an e-mail.
More information can be called up with the following call
</para>

<para>
<programlisting>
bin> perl mkStats.pl --help
</programlisting>
</para>

</sect2>

<sect2 id="stats-cron" >
<title>Automated stat generation - Cron</title>

<para>
It obviously does not really make sense to generate stats manually in
the command line as the stat module has a convenient graphical user
interface. However, generating stats manually does make sense when
combined with a Cronjob.
</para>

<para>
Imagine the following scenario: On every first of the month
the heads of department want to receive a stat for the past
month. By combining a cronjob and command line call the
stats can be sent to them automatically by e-mail.
</para>

</sect2>

<sect2 id="stats-static" >
<title>Static stats</title>

<para>
The stats module facilitates the generation of static stats. For every
static stat a file exists in which the stat content is precisely defined.
</para>

<para>
This way, very complex stats can be generated. The disadvantage
is that they are not particularly flexible.
</para>

<para>
The files are saved in the following directory
<filename>Kernel/System/Stats/Static/</filename>.
</para>
</sect2>

<sect2 id="stats-using-old-stats" >
<title>Using old static stats</title>

<para>
Standard OTRS versions 1.3 and 2.0 already facilitated the generation of stats.
Various stats for OTRS versions 1.3 and 2.0 which have been specially
developed  to meet customers' requirements can be used in more recent versions too.
</para>

<para>The files must merely be moved from the
<filename>Kernel/System/Stats/</filename> path to
<filename>Kernel/System/Stats/Static/</filename>. Additionally
the package name of the respective script must be amended by
"::Static".
</para>

<para>
The following example shows how the first path is amended.
</para>

<para>
<programlisting>
    package Kernel::System::Stats::AccountedTime;
</programlisting>
</para>

<para>
<programlisting>
    package Kernel::System::Stats::Static::AccountedTime;
</programlisting>
</para>
</sect2>

<sect2 id="stats-default-stats" >
<title>Default stats</title>

<para>"It is not always necessary to reinvent the wheel..."
</para>

<para>
The stats module provides various default stats. Stats which are
interesting for all OTRS users will in future be added to the default stats
of the stats module package. Default stats are saved in the stats module
xml format in the<filename>scripts/test/sample/</filename> directory.
</para>

</sect2>

</sect1>

</chapter>