Kernel::System::Ticket::Article - functions to manage ticket articles
Since OTRS 6, article data is split in a neutral part for all articles (in the article database table),
and back end specific data in custom tables (such as article_data_mime for the MIME based back ends).
This class only manages back end neutral article data, like listing articles with ArticleList()
or manipulating
article metadata like ArticleFlagSet()
.
For all operations involving back end specific article data (like ArticleCreate and ArticleGet),
please call BackendForArticle()
or BackendForChannel()
to get to the correct article back end.
See ArticleList()
for an example of looping over all article data of a ticket.
See Kernel::System::Ticket::Article::Backend::Base for the definition of the basic interface of all article back ends.
Don't use the constructor directly, use the ObjectManager instead:
my $ArticleObject = $Kernel::OM->Get('Kernel::System::Ticket::Article');
Returns the correct back end for a given article, or the Invalid back end, so that you can always expect a back end object instance that can be used for chain-calling.
my $ArticleBackendObject = $ArticleObject->BackendForArticle( TicketID => 42, ArticleID => 123 );
Alternatively, you can pass in a hash with base article data as returned by ArticleList()
, this will avoid the
lookup for the CommunicationChannelID of the article:
my $ArticleBackendObject = $ArticleObject->BackendForArticle( %BaseArticle );
See Kernel::System::Ticket::Article::Backend::Base for the definition of the basic interface of all article back ends.
Returns the correct back end for a given communication channel, or the Invalid back end, so that you can always expect
a back end object instance that can be used for chain-calling.
my $ArticleBackendObject = $ArticleObject->BackendForChannel( ChannelName => 'Email' );
See Kernel::System::Ticket::Article::Backend::Base for the definition of the basic interface of all article back ends.
Returns an filtered array of base article data for a ticket.
my @Articles = $ArticleObject->ArticleList(
TicketID => 123,
# Optional filters, these can be combined:
ArticleID => 234, # optional, limit to one article (if present on a ticket)
CommunicationChannel => 'Email', # optional, to limit to a certain CommunicationChannel
CommunicationChannelID => 2, # optional, to limit to a certain CommunicationChannelID
SenderType => 'customer', # optional, to limit to a certain article SenderType
SenderTypeID => 2, # optional, to limit to a certain article SenderTypeID
IsVisibleForCustomer => 0, # optional, to limit to a certain visibility
# After filtering, you can also limit to first or last found article only:
OnlyFirst => 0, # optional, only return first match
OnlyLast => 0, # optional, only return last match
);
Returns a list with base article data (no back end related data included):
(
{
ArticleID => 1,
TicketID => 2,
ArticleNumber => 1, # sequential number of article in the ticket
CommunicationChannelID => 1,
SenderTypeID => 1,
IsVisibleForCustomer => 0,
CreateBy => 1,
CreateTime => '2017-03-01 00:00:00',
ChangeBy => 1,
ChangeTime => '2017-03-01 00:00:00',
},
{ ... }
)
Please note that you need to use ArticleGet() via the article backend objects to access the full backend-specific article data hash for each article.
for my $MetaArticle (@Articles) {
my %Article = $ArticleObject->BackendForArticle( %{$MetaArticle} )->ArticleGet( %{$MetaArticle} );
}
Get a ticket ID for supplied article ID.
my $TicketID = $ArticleObject->TicketIDLookup(
ArticleID => 123, # required
);
Returns ID of a ticket that article belongs to:
$TicketID = 123;
NOTE: Usage of this lookup function is strongly discouraged, since its result is not cached.
Where possible, use ArticleList() instead.
Set article flags.
my $Success = $ArticleObject->ArticleFlagSet(
TicketID => 123,
ArticleID => 123,
Key => 'Seen',
Value => 1,
UserID => 123,
);
Events: ArticleFlagSet
Delete an article flag.
my $Success = $ArticleObject->ArticleFlagDelete(
TicketID => 123,
ArticleID => 123,
Key => 'seen',
UserID => 123,
);
my $Success = $ArticleObject->ArticleFlagDelete(
TicketID => 123,
ArticleID => 123,
Key => 'seen',
AllUsers => 1, # delete for all users
);
Events: ArticleFlagDelete
Get article flags.
my %Flags = $ArticleObject->ArticleFlagGet(
ArticleID => 123,
UserID => 123,
);
Get all article flags of a ticket.
my %Flags = $ArticleObject->ArticleFlagsOfTicketGet(
TicketID => 123,
UserID => 123,
);
returns (
123 => { # ArticleID
'Seen' => 1,
'Other' => 'something',
},
)
Returns the accounted time of a article.
my $AccountedTime = $ArticleObject->ArticleAccountedTimeGet(
ArticleID => $ArticleID,
);
Delete accounted time of an article.
my $Success = $ArticleObject->ArticleAccountedTimeDelete(
ArticleID => $ArticleID,
);
List all article sender types.
my %ArticleSenderTypeList = $ArticleObject->ArticleSenderTypeList();
Returns:
(
1 => 'agent',
2 => 'customer',
3 => 'system',
)
Lookup an article sender type id or name.
my $SenderTypeID = $ArticleObject->ArticleSenderTypeLookup(
SenderType => 'customer', # customer|system|agent
);
my $SenderType = $ArticleObject->ArticleSenderTypeLookup(
SenderTypeID => 1,
);
Set the article flags to indicate if the article search index needs to be rebuilt.
my $Success = $ArticleObject->ArticleSearchIndexRebuildFlagSet(
ArticleIDs => [ 123, 234, 345 ] # (Either 'ArticleIDs' or 'All' must be provided) The ArticleIDs to be updated.
All => 1 # (Either 'ArticleIDs' or 'All' must be provided) Set all articles to $Value. Default: 0,
Value => 1, # 0/1 default 0
);
Get a list of ArticleIDs and TicketIDs for a given flag (either needs rebuild or not)
my %ArticleTicketIDs = $ArticleObject->ArticleSearchIndexRebuildFlagList(
Value => 1, # (optional) 0/1 default 0
Limit => 10000, # (optional) default: 20000
);
Returns:
%ArticleIDs = (
1 => 2, # ArticleID => TicketID
3 => 4,
5 => 6,
...
);
gets an article indexing status hash.
my %Status = $ArticleObject->ArticleSearchIndexStatus();
Returns:
%Status = (
ArticlesTotal => 443,
ArticlesIndexed => 420,
ArticlesNotIndexed => 23,
);
Rebuilds the current article search index table content. Existing article entries will be replaced.
my $Success = $ArticleObject->ArticleSearchIndexBuild(
TicketID => 123,
ArticleID => 123,
UserID => 1,
);
Returns:
True if indexing process was successfully finished, False if not.
Deletes entries from the article search index table base on supplied ArticleID or TicketID.
my $Success = $ArticleObject->ArticleSearchIndexDelete(
ArticleID => 123, # required, deletes search index for single article
# or
TicketID => 123, # required, deletes search index for all ticket articles
UserID => 1, # required
);
Returns:
True if delete process was successfully finished, False if not.
Checks the given search parameters for used article backend fields.
my $Needed = $ArticleObject->ArticleSearchIndexSQLJoinNeeded(
SearchParams => {
...
ConditionInline => 1,
ContentSearchPrefix => '*',
ContentSearchSuffix => '*',
MIMEBase_From => '%spam@example.com%',
MIMEBase_To => '%service@example.com%',
MIMEBase_Cc => '%client@example.com%',
MIMEBase_Subject => '%VIRUS 32%',
MIMEBase_Body => '%VIRUS 32%',
MIMEBase_AttachmentName => '%anyfile.txt%',
Chat_ChatterName => '%Some Chatter Name%',
Chat_MessageText => '%Some Message Text%'
...
},
);
Returns:
True if article search index usage is needed, False if not.
Generates SQL string extensions, including the needed table joins for the article index search.
my $SQLExtenion = $ArticleObject->ArticleSearchIndexSQLJoin(
SearchParams => {
...
ConditionInline => 1,
ContentSearchPrefix => '*',
ContentSearchSuffix => '*',
MIMEBase_From => '%spam@example.com%',
MIMEBase_To => '%service@example.com%',
MIMEBase_Cc => '%client@example.com%',
MIMEBase_Subject => '%VIRUS 32%',
MIMEBase_Body => '%VIRUS 32%',
MIMEBase_AttachmentName => '%anyfile.txt%',
Chat_ChatterName => '%Some Chatter Name%',
Chat_MessageText => '%Some Message Text%'
...
},
);
Returns:
$SQLExtension = 'LEFT JOIN article_search_index ArticleFulltext ON art.id = ArticleFulltext.article_id ';
Generates SQL query conditions for the used article fields, that may be used in the WHERE clauses of main SQL queries to the database.
my $SQLExtenion = $ArticleObject->ArticleSearchIndexWhereCondition(
SearchParams => {
...
ConditionInline => 1,
ContentSearchPrefix => '*',
ContentSearchSuffix => '*',
MIMEBase_From => '%spam@example.com%',
MIMEBase_To => '%service@example.com%',
MIMEBase_Cc => '%client@example.com%',
MIMEBase_Subject => '%VIRUS 32%',
MIMEBase_Body => '%VIRUS 32%',
MIMEBase_AttachmentName => '%anyfile.txt%',
Chat_ChatterName => '%Some Chatter Name%',
Chat_MessageText => '%Some Message Text%'
...
},
);
Returns:
$SQLConditions = " AND (MIMEBase_From.article_value LIKE '%spam@example.com%') ";
Find stop words within given search string.
my $StopWords = $ArticleObject->SearchStringStopWordsFind(
SearchStrings => {
'Fulltext' => '(this AND is) OR test',
'MIMEBase_From' => 'myself',
},
);
Returns Hashref with found stop words.
Checks if warnings for stop words in search strings are active or not.
my $WarningActive = $ArticleObject->SearchStringStopWordsUsageWarningActive();
Get list of searchable fields across all article backends.
my %SearchableFields = $ArticleObject->ArticleSearchableFieldsList();
Returns:
%SearchableFields = (
'MIMEBase_Body' => {
Filterable => 1,
Key => 'MIMEBase_Body',
Label => 'Body',
Type => 'Text',
},
'MIMEBase_Subject' => {
Filterable => 1,
Key => 'MIMEBase_Subject',
Label => 'Subject',
Type => 'Text',
},
...
);
Returns an array-hash with the meta articles of the current ticket.
my @MetaArticles = $ArticleObject->_MetaArticleList(
TicketID => 123,
);
Returns:
(
{
ArticleID => 1,
TicketID => 2,
ArticleNumber => 1, # sequential number of article in the ticket
CommunicationChannelID => 1,
SenderTypeID => 1,
IsVisibleForCustomer => 0,
CreateBy => 1,
CreateTime => '2017-03-01 00:00:00',
ChangeBy => 1,
ChangeTime => '2017-03-01 00:00:00',
},
{ ... },
)
Removes all article caches related to specified ticket.
my $Success = $ArticleObject->_ArticleCacheClear(
TicketID => 123,
);
This software is part of the OTRS project (https://otrs.org/).
This software comes with ABSOLUTELY NO WARRANTY. For details, see the enclosed file COPYING for license information (GPL). If you did not receive this file, see https://www.gnu.org/licenses/gpl-3.0.txt.