## 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: .. code-block:: perl my $CommunicationDBObject = $Kernel::OM->Get('Kernel::System::CommunicationLog::DB'); CommunicationCreate() ===================== Create a new communication element. .. code-block:: perl my $CommunicationID = $CommunicationDBObject->CommunicationCreate( Transport => '...', Direction => '...', Status => '...', AccountType => '...', AccountID => '...', ); Returns the created ID. CommunicationUpdate() ===================== Update Communication elements. .. code-block:: perl 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. .. code-block:: perl 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: .. code-block:: perl $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. .. code-block:: perl 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: .. code-block:: perl C - in case of error 1 - in case of success CommunicationGet() ================== Get a communication entry data. .. code-block:: perl my $CommunicationData = $CommunicationDBObject->CommunicationGet( CommunicationID => 123, # Required ); Returns: .. code-block:: perl $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. .. code-block:: perl my $ParamString = $CommunicationDBObject->CommunicationAccountLinkGet(); Returns something like this: .. code-block:: perl $ParamString = "Action=AdminMailAccount;Subaction=Update;ID=2"; CommunicationAccountLabelGet() ============================== Get related account label if AccountType and AccountID are present. .. code-block:: perl my $AccountLabel = $CommunicationDBObject->CommunicationAccountLabelGet(); Returns something like this: .. code-block:: perl $AccountLabel = "Example.com / Alice (IMAPS)"; ObjectLogCreate() ================= Creates the logging for a specific communication object. .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl 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: .. code-block:: perl $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. .. code-block:: perl my $Result = $CommunicationDBObject->ObjectLogDelete( CommunicationID => '...', # optional ObjectLogID => '...', # optional ObjectLogStatus => '...', # optional ); ObjectLogGet() ============== Returns the Communication Log Object by ID .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl my $Result = $CommunicationDBObject->GetConnectionsObjectsAndCommunications( ObjectLogStartDate => '...', # Required Status => '...', # Optional ); Returns Arrayref of Hashes. .. code-block:: perl $Result = [ { CommunicationID => '...', ObjectLogStatus => '...', AccountType => '...', AccountID => '...', }, # ... ]; ObjectLookupSet() ================= Inserts or updates a lookup information. .. code-block:: perl my $Result = $CommunicationDBObject->ObjectLookupSet( ObjectLogID => '123', # (required) TargetObjectType => 'Article', # (required) TargetObjectID => '123', # (required) ); Returns: .. code-block:: perl 1 in case of success, in case of errors ObjectLookupSearch() ==================== Get a list of the objects lookup information. .. code-block:: perl my $List = $CommunicationDBObject->ObjectLookupSearch( ObjectLogID => '123', # (optional) ObjectLogType => 'Message', # (optional) TargetObjectType => 'Article', # (optional) TargetObjectID => '123', # (optional) CommunicationID => '123', # (optional) ); Returns: .. code-block:: perl - if any error occur An arrayref of object lookup - in case of success $List = [ { ObjectLogID => '...', TargetObjectType => '...', TargetObjectID => '...', }, # ... ]; ObjectLookupGet() ================= Gets the object lookup information. .. code-block:: perl my $Result = $CommunicationDBObject->ObjectLookupGet( ObjectLogID => '123', # (optional) TargetObjectID => '123', # (optional) TargetObjectType => '123', # (optional) ); Returns: .. code-block:: perl $Result = { CommunicationID => '...', ObjectLogID => '...', TargetObjectType => '...', TargetObjectID => '...', } - 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. .. code-block:: perl my %CommunicationData = $CommunicationDBObject->CommunicationGetByObjectLogID( ObjectLogID => 123, ); Returns: .. code-block:: perl %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: .. code-block:: perl undef - case not found module - case found _LogError() =========== Helper Method for logging. _IsValidDirection() =================== Check if the given direction is valid. .. code-block:: perl my $Result = $LogModuleObject->_IsValidDirection( Direction => '...', ); _IsValidObjectLogType() ======================= Check if the given Object Log Type is valid. .. code-block:: perl my $Result = $LogModuleObject->_IsValidObjectLogType( ObjectLogType => '...', ); _IsValidStatus() ================ Check if the given status is valid. .. code-block:: perl my $Result = $LogModuleObject->_IsValidStatus( Status => '...', ); _DurationSQL() ============== Return the SQL expression to get the difference between two dates in seconds.