Stats

Stats#

NAME#

Kernel::System::Stats - stats lib

DESCRIPTION#

All stats functions.

Explanation for the time zone parameter#

The time zone parameter is available, if the statistic is a dynamic statistic. The selected periods in the frontend are time zone neutral and for the search parameters, the selection will be converted to the OTRS time zone, because the times are stored within this time zone in the database.

This means e.g. if an absolute period of time from 2015-08-01 00:00:00 to 2015-09-10 23:59:59 and a time zone with an offset of +6 hours has been selected, the period will be converted from the +6 time zone to the OTRS time zone for the search parameter, so that the right time will be used for searching the database. Given that the OTRS time zone is set to UTC, this would result in a period of 2015-07-31 18:00:00 to 2015-09-10 17:59:59 UTC.

For a relative time period, e. g. the last 10 full days, and a time zone with an offset of +10 hours, a DateTime object with the +10 time zone will be created for the current time. For the period end date, this date will be taken and extended to the end of the day. Then, 10 full days will be subtracted from this. This is the start of the period, which will be extended to 00:00:00. Start and end date will be converted to the time zone of OTRS to search the database.

Example for relative time period ‘last 10 full days’ with selected time zone offset +10 hours, current date/time within this time zone 2015-09-10 16:00:00, OTRS time zone is UTC: End date: 2015-09-10 16:00:00 -> extended to 2015-09-10 23:59:59 -> 2015-09-10 13:59:59 OTRS time zone (UTC) Start date: 2015-09-10 16:00:00 - 10 days -> 2015-08-31 16:00:00 -> extended to 00:00:00: 2015-09-01 00:00:00 -> 2015-08-31 14:00:00 OTRS time zone (UTC)

PUBLIC INTERFACE#

new()#

Don’t use the constructor directly, use the ObjectManager instead:

my $StatsObject = $Kernel::OM->Get('Kernel::System::Stats');

StatsAdd()#

add new empty stats

my $StatID = $StatsObject->StatsAdd(
    UserID => $UserID,
);

StatsGet()#

get a hash ref of the stats you need

my $HashRef = $StatsObject->StatsGet(
    StatID             => '123',
    NoObjectAttributes => 1,       # optional
);

StatsUpdate()#

update a stat

$StatsObject->StatsUpdate(
    StatID => '123',
    Hash   => \%Hash,
    UserID => $UserID,
);

StatsDelete()#

delete a stats

$StatsObject->StatsDelete( StatID => '123' );

StatsListGet()#

fetches all statistics that the current user may see

my $StatsRef = $StatsObject->StatsListGet(
    AccessRw => 1,          # Optional, indicates that user may see all statistics
    UserID   => $UserID,
);

Returns

{
    6 => {
        Title => "Title of stat",
        # ...
    }
}

GetStatsList()#

lists all stats id’s

my $ArrayRef = $StatsObject->GetStatsList(
    AccessRw  => 1,                             # optional, indicates that user may see all statistics
    OrderBy   => 'ID' || 'Title' || 'Object',   # optional
    Direction => 'ASC' || 'DESC',               # optional
    UserID    => $UserID,
);

SumBuild()#

build sum in x or/and y axis

$StatArray = $StatsObject->SumBuild(
    Array  => \@Result,
    SumRow => 1,
    SumCol => 0,
);

GetStatsObjectAttributes()#

Get all attributes from the object in dependence of the use

my %ObjectAttributes = $StatsObject->GetStatsObjectAttributes(
    ObjectModule => 'Ticket',
    Use          => 'UseAsXvalue' || 'UseAsValueSeries' || 'UseAsRestriction',
);

GetStaticFiles()#

Get all static files

my $FileHash = $StatsObject->GetStaticFiles(
    OnlyUnusedFiles => 1 || 0,  # optional default 0
    UserID          => $UserID,
);

GetDynamicFiles()#

Get all static objects

my $FileHash = $StatsObject->GetDynamicFiles();

GetObjectName()#

Get the name of a dynamic object

my $ObjectName = $StatsObject->GetObjectName(
    ObjectModule => 'Kernel::System::Stats::Dynamic::TicketList',
);

GetObjectBehaviours()#

get behaviours that a statistic supports

my $Behaviours = $StatsObject->GetObjectBehaviours(
    ObjectModule => 'Kernel::System::Stats::Dynamic::TicketList',
);

returns

{
    ProvidesDashboardWidget => 1,
    # ...
}

ObjectFileCheck()#

AT THE MOMENT NOT USED

check readable object file

my $ObjectFileCheck = $StatsObject->ObjectFileCheck(
    Type => 'static',
    Name => 'NewTickets',
);

ObjectModuleCheck()#

Check the object module.

my $ObjectModuleCheck = $StatsObject->ObjectModuleCheck(
    StatType                     => 'static',
    ObjectModule                 => 'Kernel::System::Stats::Static::StateAction',
    CheckAlreadyUsedStaticObject => 1,                                             # optional
);

Returns true on success and false on error.

Export()#

get content from stats for export

my $ExportFile = $StatsObject->Export(
    StatID           => '123',
    ExportStatNumber => 1 || 0,     # optional, only useful move statistics from the test system to the productive system
);

Import()#

import a stats from xml file

my $StatID = $StatsObject->Import(
    UserID  => $UserID,
    Content => $UploadStuff{Content},
);

GetParams()#

get all edit params from stats for view

my $Params = $StatsObject->GetParams( StatID => '123' );

StatsRun()#

run a statistic.

my $StatArray = $StatsObject->StatsRun(
    StatID     => '123',
    GetParam   => \%GetParam,
    Preview    => 1,            # optional, return fake data for preview (only for dynamic stats)
    UserID     => $UserID,
);

StatsResultCacheCompute()#

computes stats results and adds them to the cache. This can be used to precompute stats data e. g. for dashboard widgets in a cron job.

my $StatArray = $StatsObject->StatsResultCacheCompute(
    StatID       => '123',
    UserID       => $UserID,            # target UserID
    UserGetParam => \%UserGetParam,     # user settings of non-fixed fields
);

StatsResultCacheGet()#

gets cached statistic results. Will never run the statistic. This can be used to fetch cached stats data e. g. for stats widgets in the dashboard.

my $StatArray = $StatsObject->StatsResultCacheGet(
    StatID       => '123',
    UserID       => $UserID,        # target UserID
    UserGetParam => \%GetParam,
);

StringAndTimestamp2Filename()#

builds a filename with a string and a timestamp. (space will be replaced with _ and - e.g. Title-of-File_2006-12-31_11-59)

my $Filename = $StatsObject->StringAndTimestamp2Filename(
    String   => 'Title',
    TimeZone => 'Europe/Berlin',    # optional
);

StatNumber2StatID()#

insert the stat number get the stat id

my $StatID = $StatsObject->StatNumber2StatID(
    StatNumber => 11212,
);

StatsInstall()#

installs stats

my $Result = $StatsObject->StatsInstall(
    FilePrefix => 'FAQ',    # (optional)
    UserID     => $UserID,
);

StatsUninstall()#

uninstalls stats

my $Result = $StatsObject->StatsUninstall(
    FilePrefix => 'FAQ',    # (optional)
    UserID     => $UserID,
);

StatsCleanUp()#

removed stats with not existing backend file

my $Result = $StatsObject->StatsCleanUp(
    UserID          => 1,

    ObjectNames     => [ 'Ticket', 'TicketList' ],
    # or
    CheckAllObjects => 1,
);

_GenerateStaticStats()#

take the stat configuration and get the stat table

my @StatArray = $StatsObject->_GenerateStaticStats(
    ObjectModule => $Stat->{ObjectModule},
    GetParam     => $Param{GetParam},
    Title        => $Stat->{Title},
    StatID       => $Stat->{StatID},
    Cache        => $Stat->{Cache},
    UserID       => $UserID,
);

_GenerateDynamicStats()#

take the stat configuration and get the stat table

my @StatArray = $StatsObject->_GenerateDynamicStats(
    ObjectModule     => 'Kernel::System::Stats::Dynamic::Ticket',
    Object           => 'Ticket',
    UseAsXvalue      => \UseAsXvalueElements,
    UseAsValueSeries => \UseAsValueSeriesElements,
    UseAsRestriction => \UseAsRestrictionElements,
    Title            => 'TicketStat',
    StatID           => 123,
    TimeZone         => 'Europe/Berlin',    # optional,
    Cache            => 1,                  # optional,
    Preview          => 1,                  # optional, generate fake data
    UserID           => $UserID,
);

_ColumnAndRowTranslation()#

Translate the column and row name if needed.

$StatsObject->_ColumnAndRowTranslation(
    StatArrayRef => $StatArrayRef,
    StatRef      => $StatRef,
    ExchangeAxis => 1 | 0,
);

_CreateStaticResultCacheFilename()#

create a filename out of the GetParam information and the stat id

my $Filename = $StatsObject->_CreateStaticResultCacheFilename(
    GetParam => {
        Year  => 2008,
        Month => 3,
        Day   => 5
    },
    StatID   => $Param{StatID},
);

_SetResultCache()#

cache the stats result with a given cache key (Filename).

$StatsObject->_SetResultCache(
    Filename => 'Stats' . $Param{StatID} . '-' . $MD5Key . '.cache',
    Result   => $Param{Data},
);

_GetResultCache()#

get stats result from cache, if any

my @Result = $StatsObject->_GetResultCache(
    Filename => 'Stats' . $Param{StatID} . '-' . $MD5Key . '.cache',
);

_DeleteCache()#

clean up stats result cache.

_FromOTRSTimeZone()#

Converts the given date/time string from OTRS time zone to the given time zone.

my $String = $StatsObject->_FromOTRSTimeZone(
    String   => '2016-02-20 20:00:00',
    TimeZone => 'Europe/Berlin',
);

Returns (example for OTRS time zone being set to UTC):

$TimeStamp = '2016-02-20 21:00:00',

_ToOTRSTimeZone()#

Converts the given date/time string from the given time zone to OTRS time zone.

my $String = $StatsObject->_ToOTRSTimeZone(
    String    => '2016-02-20 18:00:00',
    TimeZone  => 'Europe/Berlin',
);

Returns (example for OTRS time zone being set to UTC):

$TimeStamp = '2016-02-20 17:00:00',

_GetCacheString()#

returns a string that can be used for caching this particular statistic with the given parameters.

my $Result = $StatsObject->_GetCacheString(
    UseAsXvalue      => $UseAsXvalueRef
    UseAsValueSeries => $UseAsValueSeriesRef,
    UseAsRestriction => $UseAsRestrictionRef,
);

_AddDeltaYMD()#

Substitute for Date::Pcalc::Add_Delta_YMD() which uses Kernel::System::DateTime.

_AddDeltaDHMS()#

Substitute for Date::Pcalc::Add_Delta_DHMS() which uses Kernel::System::DateTime.

_AddDeltaDays()#

Substitute for Date::Pcalc::Add_Delta_Days() which uses Kernel::System::DateTime.

_DaysInMonth()#

Substitute for Date::Pcalc::Days_in_Month() which uses Kernel::System::DateTime.

_DayOfWeek()#

Substitute for Date::Pcalc::Day_of_Week() which uses Kernel::System::DateTime.

_DayOfWeekAbbreviation()#

Substitute for Date::Pcalc::Day_of_Week_Abbreviation()

_DayOfWeekToText()#

Substitute for Date::Pcalc::Day_of_Week_to_Text()

_MondayOfWeek()#

Substitute for Date::Pcalc::Monday_of_Week(), using Kernel::System::DateTime, note different parameters

_WeekOfYear()#

Substitute for Date::Pcalc::Week_of_Year(), using Kernel::System::DateTime

_HumanReadableAgeGet()#

Re-implementation of L<CustomerAge()|Kernel::Output::HTML::Layout/CustomerAge()> since this object is inaccessible from the backend.

TODO: Currently, there is no support for translation of statistic values, it’s planned to be implemented later on. For the time being, this method will return a string in English only.

my $HumanReadableAge = $StatsObject->_HumanReadableAgeGet(
    Age   => 360,
);

Returns (converted seconds in human readable format, i.e. ‘1 d 2 h’):

$HumanReadableAge = '6 h',

_TimeStamp2DateTime#

Return a datetime object from a timestamp.

Contents