####################
CommunicationChannel
####################


****
NAME
****


Kernel::System::CommunicationChannel - Functions to manage communication channels.


***********
DESCRIPTION
***********


All functions to manage communication channels.


****************
PUBLIC INTERFACE
****************


new()
=====


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


.. code-block:: perl

     my $CommunicationChannelObject = $Kernel::OM->Get('Kernel::System::CommunicationChannel');



ChannelAdd()
============


Add new communication channel.


.. code-block:: perl

     my $ChannelID = $CommunicationChannelObject->ChannelAdd(
         ChannelName => 'Email',                                          # (required) Communication channel name
         Module      => 'Kernel::System::CommunicationChannel::Internal', # (required) Module
         PackageName => 'Framework',                                      # (required) Package name
         ChannelData => {...},                                            # (optional) Additional channel data (can be array, hash, scalar).
         ValidID     => 1,                                                # (optional) Default 1.
         UserID      => 1,                                                # (required) UserID
     );


Returns:


.. code-block:: perl

     $ChannelID = 1;



ChannelGet()
============


Get a communication channel.


.. code-block:: perl

     my %CommunicationChannel = $CommunicationChannelObject->ChannelGet(
         ChannelID   => '1',      # (optional) Communication channel id
                                  # or
         ChannelName => 'Email',  # (optional) Communication channel name
     );


Returns:


.. code-block:: perl

     %CommunicationChannel = (
         ChannelID   => 1,
         ChannelName => 'Email',
         Module      => 'Kernel::System::CommunicationChannel::Email',
         PackageName => 'Framework',
         ChannelData => {...},                                               # Additional channel data (can be array, hash, scalar).
         DisplayName => 'Email',                                             # Configurable
         DisplayIcon => 'fa-envelope',                                       # Configurable
         ValidID     => 1,
         CreateTime  => '2017-01-01 00:00:00',
         CreateBy    => 1,
         ChangeTime  => '2017-01-01 00:00:00',
         ChangeBy    => 1,
     );



ChannelUpdate()
===============


Update communication channel.


.. code-block:: perl

     my $Success = $CommunicationChannelObject->ChannelUpdate(
         ChannelID   => '1',                                              # (required) ChannelID that will be updated
         ChannelName => 'Email',                                          # (required) New channel name
         Module      => 'Kernel::System::CommunicationChannel::Internal', # (optional) Module
         PackageName => 'Framework',                                      # (optional) Package name
         ChannelData => {...},                                            # (optional) Additional channel data (can be array, hash, scalar)
         ValidID     => 1,                                                # (optional) ValidID
         UserID      => 1,                                                # (required) UserID
     );


Returns:


.. code-block:: perl

     $Success = 1;



ChannelList()
=============


Get a list of all available communication channels.


.. code-block:: perl

     my @CommunicationChannels = $CommunicationChannelObject->ChannelList(
         ValidID => 1,           # (optional) filter by ValidID
     );


Returns:


.. code-block:: perl

     @CommunicationChannels = (
         {
             ChannelID   => 1,
             ChannelName => 'Email',
             Module      => 'Kernel::System::CommunicationChannel::Email',
             PackageName => 'Framework',
             ChannelData => {...},
             DisplayName => 'Email',
             DisplayIcon => 'fa-envelope',
             ValidID     => 1,
             CreateTime  => '2017-01-01 00:00:00',
             CreateBy    => 1,
             ChangeTime  => '2017-01-01 00:00:00',
             ChangeBy    => 1,
         },
         {
             ChannelID   => 2,
             ChannelName => 'Phone',
             Module      => 'Kernel::System::CommunicationChannel::Phone',
             PackageName => 'Framework',
             ChannelData => {...},
             DisplayName => 'Phone',
             DisplayIcon => 'fa-phone',
             ValidID     => 1,
             CreateTime  => '2017-01-01 00:00:00',
             CreateBy    => 1,
             ChangeTime  => '2017-01-01 00:00:00',
             ChangeBy    => 1,
         },
         # ...
     );



ChannelSync()
=============


Synchronize communication channels in the database with channel registration in configuration.


.. code-block:: perl

     my %Result = $CommunicationChannelObject->ChannelSync(
         UserID => 1,
     );


Returns:


.. code-block:: perl

     %Result = (
         ChannelsUpdated => [ 'Email', 'Phone' ],
         ChannelsAdded   => [ 'Chat' ],
         ChannelsInvalid => [ 'Internal' ],
     );



ChannelObjectGet()
==================


Returns instance of the Channel object.


.. code-block:: perl

     my $Object = $CommunicationChannelObject->ChannelObjectGet(
         ChannelName => 'Email',     # ChannelName or ChannelID required
     );
 
     my $Object = $CommunicationChannelObject->ChannelObjectGet(
         ChannelID => 2,             # ChannelName or ChannelID required
     );


\ **Warning**\ : this function returns no object in case a channel is no longer available in the system,
so make sure to check its return value.


ChannelDrop()
=============


Drop an invalid communication channel (that only exists in the database, but not in the configuration).
By default, this will only drop channels that have no associated article data; use \ ``DropArticleData``\  to
force article data removal as well. Channels provided by the OTRS framework can never be dropped.


.. code-block:: perl

     my $Success = $CommunicationChannelObject->ChannelDrop(
         ChannelID   => 1,               # (required) Delete by channel ID
                                         # or
         ChannelName => 'SomeChannel',   # (required) Delete by channel name
 
         DropArticleData => 1,           # (optional) Also drop article data if possible, default: 0
     );


Returns:


.. code-block:: perl

     $Success = 1;



ChannelDelete()
===============


Delete communication channel record from the database.


.. code-block:: perl

     my $Success = $CommunicationChannelObject->ChannelDelete(
         ChannelID   => 1,       # (optional) Delete by ChannelID
                                 # or
         ChannelName => 'Email', # (optional) Delete by Channel name
     );


Returns:


.. code-block:: perl

     $Success = 1;




*****************
PRIVATE FUNCTIONS
*****************


_ChannelListCacheCleanup()
==========================


Delete communication channel cache.


.. code-block:: perl

     my $Success = $CommunicationChannelObject->_ChannelListCacheCleanup();


Returns:


.. code-block:: perl

     $Success = 1;