DB#

NAME#

Kernel::System::CommunicationLog::DB - Database interface to Communication Log

DESCRIPTION#

Global module to handle all the Database operations for the Communication Log.

PUBLIC INTERFACE#

new()#

Create a Communication Log Database object. Do not use it directly, instead use:

my $CommunicationDBObject = $Kernel::OM->Get('Kernel::System::CommunicationLog::DB');

CommunicationCreate()#

Create a new communication element.

my $CommunicationID = $CommunicationDBObject->CommunicationCreate(
    Transport       => '...',
    Direction       => '...',
    Status          => '...',
    AccountType     => '...',
    AccountID       => '...',
);

Returns the created ID.

CommunicationUpdate()#

Update Communication elements.

my $Result = $CommunicationDBObject->CommunicationUpdate(
    CommunicationID => '...',
    Status         => '[Successful|Warning|Failed]',
);

Returns 1 or undef.

CommunicationList()#

List communication entries. If parameters are given, the listing will be filtered, otherwise all available entries will be returned.

my $CommunicationList = $CommunicationDBObject->CommunicationList(
    Transport   => 'Email',      # (optional) Log type/transport/module
    Direction   => 'Incoming',   # (optional) 'Incoming' or 'Outgoing'
    Status      => 'Processing', # (optional) 'Successful', 'Processing' or 'Failed'
    Date        => '2017-07-03', # (optional) List communications just from the given date.
    StartDate   => '2017-07-03', # (optional) List communications starting from the given date.
    OlderThan   => '2017-07-03', # (optional) List communications older than the given date.
    Result      => 'ARRAY',      # (optional) Can be ARRAY or AVERAGE. ARRAY returns the results as
                                 #            an array while AVERAGE returns the communication average in seconds.
                                 #            Default: ARRAY
    OrderBy     => 'Down',       # (optional) Down|Up; Default: Down
    SortBy      => 'StartTime',  # (optional) Transport|Direction|Status|StartTime|EndTime|Duration, default: StartTime
    AccountType => 'POP3',       # (optional) The used account type
    AccountID   => 123,          # (optional) The used account id
);

Returns:

$CommunicationList = [
    {
        CommunicationID => 33,
        Transport       => 'Email',
        Direction       => 'Incoming',
        Status          => 'Failed',
        AccountType     => 'IMAPS',
        AccountID       => 1,
        StartTime       => '2017-07-20 08:57:56',
        EndTime         => '2017-07-20 08:57:57',
        Duration        => 1,
    },
    {
        CommunicationID => 34,
        Transport       => 'Email',
        Direction       => 'Outgoing',
        Status          => 'Successful',
        AccountType     => 'DoNotSendEmail',
        AccountID       => undef,
        StartTime       => '2017-07-20 08:58:43',
        EndTime         => '2017-07-20 08:58:49',
        Duration        => 6,
    },
];

CommunicationDelete()#

Deletes a Communication entry if specified. Otherwise deletes all communications.

my $Result = $CommunicationDBObject->CommunicationDelete(
    CommunicationID => 1,            # (optional) Communication ID
    Status          => 'Processing', # (optional) 'Successful', 'Processing' or 'Failed'
                                     # for example, using '!Processing', means different from
    Date            => '2017-07-03', # (optional) Delete communications just from the given date.
    OlderThan       => '2017-07-03', # (optional) Delete communications older than the given date.
);

Returns:

C<undef> - in case of error
1        - in case of success

CommunicationGet()#

Get a communication entry data.

my $CommunicationData = $CommunicationDBObject->CommunicationGet(
    CommunicationID => 123, # Required
);

Returns:

$CommunicationData = {
    CommunicationID => 123,
    Transport       => 'Email',
    Direction       => 'Incoming',
    Status          => 'Processing',
    StartTime       => '2017-05-31 09:26:20',
    EndTime         => '2017-05-31 09:30:15',
    Duration        => 235,
};

CommunicationAccountLinkGet()#

Get relative link information if AccountType and AccountID are present.

my $ParamString = $CommunicationDBObject->CommunicationAccountLinkGet();

Returns something like this:

$ParamString = "Action=AdminMailAccount;Subaction=Update;ID=2";

CommunicationAccountLabelGet()#

Get related account label if AccountType and AccountID are present.

my $AccountLabel = $CommunicationDBObject->CommunicationAccountLabelGet();

Returns something like this:

$AccountLabel = "Example.com / Alice (IMAPS)";

ObjectLogCreate()#

Creates the logging for a specific communication object.

my $ObjectLogID = $CommunicationDBObject->ObjectLogCreate(
    CommunicationID => 123,          # (required) The CommunicationID of the related ongoing communication.
    ObjectLogType   => 'Connection', # (required) Must be 'Connection' or 'Message'.
    Status          => 'Processing', # (optional) Needs to be either 'Successful', 'Processing' or 'Failed'
);

ObjectLogUpdate()#

Stop the logging for a specific communication object.

my $Result = $CommunicationDBObject->ObjectLogUpdate(
    CommunicationID => 123,             # (required) The CommunicationID of the related ongoing communication.
    ObjectLogID     => 234,             # (required) The ObjectLogID to be used
    ObjectLogType   => 'Connection',    # (required) Must be 'Connection' or 'Message'.
    Status          => 'Processing',    # (optional) Needs to be either 'Successful', 'Processing' or 'Failed'
);

ObjectLogList()#

Get the object list for a specific communication.

my $Result = $CommunicationDBObject->ObjectLogList(
    CommunicationID    => '123',         # (optional)
    ObjectLogID        => '123',         # (optional)
    ObjectLogType      => 'Connection',  # (optional)
    StartDate          => '2017-07-03',  # (optional) List communications starting from the given date.
    ObjectLogStartTime => '2017-07-03',  # (optional)
    ObjectLogEndTime   => '2017-07-03',  # (optional)
    ObjectLogStatus    => 'Successful',  # (optional)
    OrderBy            => 'Down',        # (optional) Down|Up; Default: Down
    SortBy             => 'ID',          # (optional) ID|CommunicationID|ObjectLogType|StartTime|EndTime|Status|Duration, default: ID
);

Returns:

$Result = [
    {
        ObjectLogID        => '19',
        CommunicationID    => '11',
        ObjectLogStatus    => 'Successful',
        ObjectLogType      => 'Connection',
        ObjectLogStartTime => '2017-07-20 10:50:22',
        ObjectLogEndTime   => '2017-07-20 10:50:22',
        ObjectLogDuration  => '0',
    },
    {
        ObjectLogID        => '18',
        CommunicationID    => '11',
        ObjectLogType      => 'Message',
        ObjectLogStatus    => 'Successful',
        ObjectLogStartTime => '2017-07-20 10:50:21',
        ObjectLogEndTime   => '2017-07-20 10:50:22',
        ObjectLogDuration  => '1',
    },
];

ObjectLogDelete()#

Delete the logging.

my $Result = $CommunicationDBObject->ObjectLogDelete(
    CommunicationID => '...',    # optional
    ObjectLogID     => '...',    # optional
    ObjectLogStatus => '...',    # optional
);

ObjectLogGet()#

Returns the Communication Log Object by ID

my $Result = $CommunicationDBObject->ObjectLogGet(
    CommunicationID  => '...',
    ObjectLogID      => '...',
);

Returns something like:

$Result = {
    ObjectLogID        => '18',
    CommunicationID    => '11',
    ObjectLogType      => 'Message',
    ObjectLogStatus    => 'Successful',
    ObjectLogStartTime => '2017-07-20 10:50:21',
    ObjectLogEndTime   => '2017-07-20 10:50:22',
    ObjectLogDuration  => '1',
};

ObjectLogEntryCreate()#

Create a log entry for the specific communication object.

my $Result = $CommunicationDBObject->ObjectLogEntryCreate(
    ObjectLogID => '...', # required
    Key         => '...', # required
    Value       => '...', # required
    Priority    => '...', # required
);

Returns 1 on success.

ObjectLogEntryList()#

Get the logging list for a specific communication.

my $Result = $CommunicationDBObject->ObjectLogEntryList(
    CommunicationID     => '...',
    ObjectLogID         => '...',   # optional
    ObjectLogType       => '...',   # optional
    ObjectLogStartTime  => '...',   # optional
    ObjectLogEndTime    => '...',   # optional
    ObjectLogStatus     => '...',   # optional
    LogID               => '...',   # optional
    LogKey              => '...',   # optional
    LogValue            => '...',   # optional
    LogPriority         => '...',   # optional
    LogCreateTime       => '...',   # optional
    OrderBy             => 'Down',  # (optional) Down|Up; Default: Down
    SortBy              => 'LogID',    # (optional) ObjectLogID|ObjectLogType|ObjectStartTime|ObjectEndTime|ObjectStatus|LogID|LogKey|LogPriority|LogCreateTime; Default: LogID
);

GetConnectionsObjectsAndCommunications()#

Method specifically created for optimization purposes for the Support Data Collector. Joins the Communication Log Object and Communications.

my $Result = $CommunicationDBObject->GetConnectionsObjectsAndCommunications(
    ObjectLogStartDate => '...',    # Required
    Status             => '...',    # Optional
);

Returns Arrayref of Hashes.

$Result = [
    {
        CommunicationID => '...',
        ObjectLogStatus => '...',
        AccountType     => '...',
        AccountID       => '...',
    },
    # ...
];

ObjectLookupSet()#

Inserts or updates a lookup information.

my $Result = $CommunicationDBObject->ObjectLookupSet(
    ObjectLogID      => '123',     # (required)
    TargetObjectType => 'Article', # (required)
    TargetObjectID   => '123',     # (required)
);

Returns:

1 in case of success, <undef> in case of errors

ObjectLookupSearch()#

Get a list of the objects lookup information.

my $List = $CommunicationDBObject->ObjectLookupSearch(
    ObjectLogID      => '123',     # (optional)
    ObjectLogType    => 'Message', # (optional)
    TargetObjectType => 'Article', # (optional)
    TargetObjectID   => '123',     # (optional)
    CommunicationID  => '123',     # (optional)
);

Returns:

<undef> - if any error occur
An arrayref of object lookup - in case of success
$List = [
    {
        ObjectLogID      => '...',
        TargetObjectType => '...',
        TargetObjectID   => '...',
    },
    # ...
];

ObjectLookupGet()#

Gets the object lookup information.

my $Result = $CommunicationDBObject->ObjectLookupGet(
    ObjectLogID      => '123',         # (optional)
    TargetObjectID   => '123',         # (optional)
    TargetObjectType => '123',         # (optional)
);

Returns:

$Result = {
    CommunicationID  => '...',
    ObjectLogID      => '...',
    TargetObjectType => '...',
    TargetObjectID   => '...',
}

<undef> - if any error occur
An hashref with object lookup information - in case info exists
An empty hasref                           - in case info doesn't exists

CommunicationGetByObjectLogID()#

Get a communication entry data by a communication object id.

my %CommunicationData = $CommunicationDBObject->CommunicationGetByObjectLogID(
    ObjectLogID => 123,
);

Returns:

%CommunicationData = (
    CommunicationID => 123,
    Transport       => 'Email',
    Direction       => 'Incoming',
    Status          => 'Processing',
    AccountType     => '...',
    AccountID       => '...',
    StartTime       => '2017-05-31 09:26:20',
    EndTime         => '2017-05-31 09:30:15',
);

_GetTransportModule()#

Lookup for the transport module.

Returns:

undef  - case not found
module - case found

_LogError()#

Helper Method for logging.

_IsValidDirection()#

Check if the given direction is valid.

my $Result = $LogModuleObject->_IsValidDirection(
    Direction => '...',
);

_IsValidObjectLogType()#

Check if the given Object Log Type is valid.

my $Result = $LogModuleObject->_IsValidObjectLogType(
    ObjectLogType => '...',
);

_IsValidStatus()#

Check if the given status is valid.

my $Result = $LogModuleObject->_IsValidStatus(
    Status => '...',
);

_DurationSQL()#

Return the SQL expression to get the difference between two dates in seconds.