#######
Mention
#######


****
NAME
****


Kernel::System::Mention


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


Support for mentioning users.


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


new()
=====


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


.. code-block:: perl

     my $MentionObject = $Kernel::OM->Get('Kernel::System::Mention');



AddMention()
============


Adds a mention and triggers event "UserMention" to send a notification.


.. code-block:: perl

     my $Success = $MentionObject->AddMention(
         TicketID        => 3252,
         ArticleID       => 6538,
         MentionedUserID => 5,
         UserID          => 1,
     );
 
     Returns true value on success.



CanUserRemoveMention()
======================


Checks if the given user is allowed to remove the given mention.


.. code-block:: perl

     my $UserCanRemoveMention = $MentionObject->CanUserRemoveMention(
         TicketID        => 3252,
         MentionedUserID => 5,
         UserID          => 1, # user who wants to remove the mention
     );
 
     Returns true value if the user is allowed to remove the mention.



RemoveMention()
===============


Removes all mentions of a ticket for a specific user ID.


.. code-block:: perl

     my $Success = $MentionObject->RemoveMention(
         TicketID        => 3252,
         MentionedUserID => 5,
         UserID          => 1, # user who wants to remove the mention
     );
 
     Returns true value on success.



RemoveAllMentions()
===================


Deletes all mentions of a ticket.


.. code-block:: perl

     my $Success = $MentionObject->RemoveAllMentions(
         TicketID => 3252,
     );
 
     Returns true value on success.



GetTicketMentions()
===================


Retrieves all mentions of a ticket.


.. code-block:: perl

     my $Mentions = $MentionObject->GetTicketMentions(
         TicketID  => 3252,
         OrderBy   => 'create_time',     # optional; default
         SortOrder => 'ASC',             # or 'DESC', optional; default
     );
 
     Returns:
 
     my $Mentions = [
         {
             UserID     => 5,
             TicketID   => 76,
             ArticleID  => 89,
             CreateTime => '2022-07-20 12:34:23',
         },
         # ...
     ];



GetUserMentions()
=================


Retrieves all mentions of a user.


.. code-block:: perl

     my $Mentions = $MentionObject->GetUserMentions(
         UserID     => 87,
 
         # optional, defaults to 0 and then means that all mentions of all articles per ticket are
         # counted as one combined mention;
         # if set to 1, all mentions of every article count separately
         PerArticle => 0,
 
         OrderBy    => 'create_time',    # optional; default
         SortOrder  => 'ASC',            # or 'DESC', optional; default
     );
 
     Returns:
 
     my $Mentions = [
         {
             UserID   => 5,
             TicketID => 76,
 
             # the following two entries will only be returned if parameter PerArticle is set
             ArticleID  => 89,
             CreateTime => '2022-07-20 12:34:23',
         },
         # ...
     ];



GetDashboardWidgetTicketData()
==============================


Returns data for dashboard widgets that output information about mentions.


.. code-block:: perl

     my $Data = $MentionObject->GetDashboardWidgetTicketData(
         UserID => 37,
     );
 
     Returns:
 
     my $Data = (
         TicketIDs     => [ 5, 27, 382, ],
         CustomColumns => {
             5 => {
                 LastMention => '2022-07-03 10:32:42',
             },
             27 => {
                 LastMention => '2022-07-08 14:56:20',
             },
             382 => {
                 LastMention => '2022-07-25 16:09:12',
             },
         },
     );



GetMentionedUserIDsFromString()
===============================



.. code-block:: perl

     Parses HTML string and returns the IDs of found mentioned users.
 
     my $MentionedUserIDs = $MentionObject->GetMentionedUserIDsFromString(
         HTMLString => '...<a class="Mention" href="..." target="...">@root@localhost<\/a>...',
 
         # optional
         # Limit for number of returned user IDs. The rest will silently be ignored.
         Limit => 5,
     );
 
     Returns:
     my $MentionedUserIDs = [ 1, 5, ],



IsGroupBlocked()
================


Checks if the given group is blocked for mentioning by SysConfig option 'Mentions###BlockedGroups'.


.. code-block:: perl

     my $GroupIsBlocked = $MentionObject->IsGroupBlocked(
         Group => 'users',
     );
 
     Returns true value of group is blocked.