TicketSearch#

NAME#

Kernel::System::Ticket::TicketSearch - ticket search lib

DESCRIPTION#

All ticket search functions.

TicketSearch()#

To find tickets in your system.

my @TicketIDs = $TicketObject->TicketSearch(
    # result (optional, default is 'HASH')
    Result => 'ARRAY' || 'HASH' || 'COUNT',

    # limit the number of found tickets (optional, default is 10000)
    Limit => 100,

    # Use TicketSearch as a ticket filter on a single ticket,
    # or a predefined ticket list
    TicketID     => 1234,
    TicketID     => [1234, 1235],

    # ticket number (optional) as STRING or as ARRAYREF
    # The value will be treated as a SQL query expression.
    TicketNumber => '%123546%',
    TicketNumber => ['%123546%', '%123666%'],

    # ticket title (optional) as STRING or as ARRAYREF
    # The value will be treated as a SQL query expression.
    # When ConditionInline is set then remaining whitespace will be treated as a && condition and
    # and the settings of ContentSearchPrefix and ContentSearchSuffix will be honored.
    Title => '%SomeText%',
    Title => ['%SomeTest1%', '%SomeTest2%'],

    Queues   => ['system queue', 'other queue'],
    QueueIDs => [1, 42, 512],

    # use also sub queues of Queue|Queues in search
    UseSubQueues => 0,

    # You can use types like normal, ...
    Types   => ['normal', 'change', 'incident'],
    TypeIDs => [3, 4],

    # You can use states like new, open, pending reminder, ...
    States   => ['new', 'open'],
    StateIDs => [3, 4],

    # (Open|Closed) tickets for all closed or open tickets.
    StateType => 'Open',

    # You also can use real state types like new, open, closed,
    # pending reminder, pending auto, removed and merged.
    StateType    => ['open', 'new'],
    StateTypeIDs => [1, 2, 3],

    Priorities  => ['1 very low', '2 low', '3 normal'],
    PriorityIDs => [1, 2, 3],

    Services   => ['Service A', 'Service B'],
    ServiceIDs => [1, 2, 3],

    SLAs   => ['SLA A', 'SLA B'],
    SLAIDs => [1, 2, 3],

    Locks   => ['unlock'],
    LockIDs => [1, 2, 3],

    OwnerIDs => [1, 12, 455, 32],

    ResponsibleIDs => [1, 12, 455, 32],

    WatchUserIDs => [1, 12, 455, 32],

    # CustomerID (optional) as STRING or as ARRAYREF
    # The value will be treated as a SQL query expression.
    CustomerID => '123',
    CustomerID => ['123', 'ABC'],

    # CustomerIDRaw (optional) as STRING or as ARRAYREF
    # CustomerID without QueryCondition checking.
    # The param CustomerID will be ignored when CustomerIDRaw is set.
    # The raw values will be quoted and combined with 'OR' for the query.
    CustomerIDRaw => '123 + 345',
    CustomerIDRaw => ['123', 'ABC','123 && 456','ABC % efg'],

    # CustomerUserLogin (optional) as STRING as ARRAYREF
    # The value will be treated as a SQL query expression.
    CustomerUserLogin => 'uid123',
    CustomerUserLogin => ['uid123', 'uid777'],

    # CustomerUserLoginRaw (optional) as STRING as ARRAYREF
    # CustomerUserLogin without QueryCondition checking.
    # The param CustomerUserLogin will be ignored when CustomerUserLoginRaw is set.
    # The raw values will be quoted and combined with 'OR' for the query.
    CustomerUserLoginRaw => 'uid',
    CustomerUserLoginRaw => 'uid + 123',
    CustomerUserLoginRaw => ['uid  -  123', 'uid # 777 + 321'],

    # create ticket properties (optional)
    CreatedUserIDs     => [1, 12, 455, 32]
    CreatedTypes       => ['normal', 'change', 'incident'],
    CreatedTypeIDs     => [1, 2, 3],
    CreatedPriorities  => ['1 very low', '2 low', '3 normal'],
    CreatedPriorityIDs => [1, 2, 3],
    CreatedStates      => ['new', 'open'],
    CreatedStateIDs    => [3, 4],
    CreatedQueues      => ['system queue', 'other queue'],
    CreatedQueueIDs    => [1, 42, 512],

    # DynamicFields
    #   At least one operator must be specified. Operators will be connected with AND,
    #       values in an operator with OR.
    #   You can also pass more than one argument to an operator: ['value1', 'value2']
    DynamicField_FieldNameX => {
        Empty             => 1,                       # will return dynamic fields without a value
                                                      # set to 0 to search fields with a value present
        Equals            => 123,
        Like              => 'value*',                # "equals" operator with wildcard support
        GreaterThan       => '2001-01-01 01:01:01',
        GreaterThanEquals => '2001-01-01 01:01:01',
        SmallerThan       => '2002-02-02 02:02:02',
        SmallerThanEquals => '2002-02-02 02:02:02',
    },

    # User ID for searching tickets by ticket flags (optional, defaults to UserID)
    TicketFlagUserID => 1,

    # search for ticket flags
    TicketFlag => {
        Seen => 1,
    },

    # search for ticket flag that is absent, or a different value than the
    # one given:
    NotTicketFlag => {
        Seen => 1,
    },

    # User ID for searching tickets by article flags (optional, defaults to UserID)
    ArticleFlagUserID => 1,


    # search for tickets by the presence of flags on articles
    ArticleFlag => {
        Important => 1,
    },

    # article stuff (optional)
    MIMEBase_From    => '%spam@example.com%',
    MIMEBase_To      => '%service@example.com%',
    MIMEBase_Cc      => '%client@example.com%',
    MIMEBase_Subject => '%VIRUS 32%',
    MIMEBase_Body    => '%VIRUS 32%',

    # attachment stuff (optional, applies only for ArticleStorageDB)
    AttachmentName => '%anyfile.txt%',

    # use full article text index if configured (optional, defaults to off)
    FullTextIndex => 1,

    # article content search (AND or OR for From, To, Cc, Subject and Body) (optional, defaults to 'AND')
    ContentSearch => 'AND',

    # article content search prefix (for From, To, Cc, Subject and Body) (optional, defaults to '*')
    # For Title the default is the empty string.
    ContentSearchPrefix => '*',

    # article content search suffix (for From, To, Cc, Subject and Body) (optional, defaults to '*')
    # For Title the default is the empty string.
    ContentSearchSuffix => '*',

    # content conditions for From, To, Cc, Subject, Body,
    # and Title (all optional)
    # For Title it also activates ContentSearchPrefix and ContentSearchSuffix,
    ConditionInline => 1,

    # articles created more than 60 minutes ago (article older than 60 minutes) (optional)
    ArticleCreateTimeOlderMinutes => 60,
    # articles created less than 120 minutes ago (article newer than 60 minutes) (optional)
    ArticleCreateTimeNewerMinutes => 120,

    # articles with create time after ... (article newer than this date) (optional)
    ArticleCreateTimeNewerDate => '2006-01-09 00:00:01',
    # articles with created time before ... (article older than this date) (optional)
    ArticleCreateTimeOlderDate => '2006-01-19 23:59:59',

    # tickets created more than 60 minutes ago (ticket older than 60 minutes)  (optional)
    TicketCreateTimeOlderMinutes => 60,
    # tickets created less than 120 minutes ago (ticket newer than 120 minutes) (optional)
    TicketCreateTimeNewerMinutes => 120,

    # tickets with create time after ... (ticket newer than this date) (optional)
    TicketCreateTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with created time before ... (ticket older than this date) (optional)
    TicketCreateTimeOlderDate => '2006-01-19 23:59:59',

    # ticket history entries that created more than 60 minutes ago (optional)
    TicketChangeTimeOlderMinutes => 60,
    # ticket history entries that created less than 120 minutes ago (optional)
    TicketChangeTimeNewerMinutes => 120,

    # ticket history entry create time after ... (ticket history entries newer than this date) (optional)
    TicketChangeTimeNewerDate => '2006-01-09 00:00:01',
    # ticket history entry create time before ... (ticket history entries older than this date) (optional)
    TicketChangeTimeOlderDate => '2006-01-19 23:59:59',

    # tickets changed more than 60 minutes ago (optional)
    TicketLastChangeTimeOlderMinutes => 60,
    # tickets changed less than 120 minutes ago (optional)
    TicketLastChangeTimeNewerMinutes => 120,

    # tickets with changed time after ... (ticket changed newer than this date) (optional)
    TicketLastChangeTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with changed time before ... (ticket changed older than this date) (optional)
    TicketLastChangeTimeOlderDate => '2006-01-19 23:59:59',

    # tickets closed more than 60 minutes ago (optional)
    TicketCloseTimeOlderMinutes => 60,
    # tickets closed less than 120 minutes ago (optional)
    TicketCloseTimeNewerMinutes => 120,

    # tickets with closed time after ... (ticket closed newer than this date) (optional)
    TicketCloseTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with closed time before ... (ticket closed older than this date) (optional)
    TicketCloseTimeOlderDate => '2006-01-19 23:59:59',

    # tickets with last close time more than 60 minutes ago (optional)
    TicketLastCloseTimeOlderMinutes => 60,
    # tickets with last close time less than 120 minutes ago (optional)
    TicketLastCloseTimeNewerMinutes => 120,

    # tickets with last close time after ... (ticket last close newer than this date) (optional)
    TicketLastCloseTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with last close time before ... (ticket last close older than this date) (optional)
    TicketLastCloseTimeOlderDate => '2006-01-19 23:59:59',

    # tickets with pending time of more than 60 minutes ago (optional)
    TicketPendingTimeOlderMinutes => 60,
    # tickets with pending time of less than 120 minutes ago (optional)
    TicketPendingTimeNewerMinutes => 120,

    # tickets with pending time after ... (optional)
    TicketPendingTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with pending time before ... (optional)
    TicketPendingTimeOlderDate => '2006-01-19 23:59:59',

    # you can use all following escalation options with this four different ways of escalations
    # TicketEscalationTime...
    # TicketEscalationUpdateTime...
    # TicketEscalationResponseTime...
    # TicketEscalationSolutionTime...

    # ticket escalation time of more than 60 minutes ago (optional)
    TicketEscalationTimeOlderMinutes => -60,
    # ticket escalation time of less than 120 minutes ago (optional)
    TicketEscalationTimeNewerMinutes => -120,

    # tickets with escalation time after ... (optional)
    TicketEscalationTimeNewerDate => '2006-01-09 00:00:01',
    # tickets with escalation time before ... (optional)
    TicketEscalationTimeOlderDate => '2006-01-09 23:59:59',

    # search in archive (optional)
    # if archiving is on, if not specified the search processes unarchived only
    # 'y' searches archived tickets, 'n' searches unarchived tickets
    # if specified together all tickets are searched
    ArchiveFlags => ['y', 'n'],

    # OrderBy (optional, default is 'Down')
    OrderBy => 'Down',  # Down|Up
    # SortBy (optional, default is 'Age')
    SortBy  => 'Age',   # Created|Owner|Responsible|CustomerID|State|TicketNumber|Queue|Priority|Age|Type|Lock
                        # Changed|Title|Service|SLA|PendingTime|EscalationTime
                        # EscalationUpdateTime|EscalationResponseTime|EscalationSolutionTime
                        # DynamicField_FieldNameX

    # OrderBy and SortBy as ARRAY for sub sorting (optional)
    OrderBy => ['Down', 'Up'],
    SortBy  => ['Priority', 'Age'],

    # user search (UserID is required)
    UserID     => 123,
    Permission => 'ro' || 'rw', # optional, default is 'ro'

    # customer search (CustomerUserID is required)
    CustomerUserID => 123,
    Permission     => 'ro' || 'rw', # optional, default is 'ro'

    # CacheTTL, cache search result in seconds (optional, the default is four minutes)
    CacheTTL => 60 * 15,
);

Returns:

Result: ‘ARRAY’

@TicketIDs = ( 1, 2, 3 );

Result: ‘HASH’

%TicketIDs = (
    1 => '2010102700001',
    2 => '2010102700002',
    3 => '2010102700003',
);

Result: ‘COUNT’

$TicketIDs = 123;

TicketCountByAttribute()#

Returns count of tickets per value for a specific attribute.

my $TicketCount = $TicketObject->TicketCountByAttribute(
    Attribute => 'ServiceID',
    TicketIDs => [ 1, 2, 3 ],
);

Returns:

$TicketCount = {
    Attribute_Value_1 => 1,
    Attribute_Value_2 => 3,
    # ...
};

PRIVATE INTERFACE#

_TicketHistoryReferenceForSearchArgument#

Returns the ticket history reference to the given search argument.

my $Self->_TicketHistoryReferenceForSearchArgument(
    Argument => '...' # argument name
);
Result

undef - in case the argument is not mapped string - the ticket history reference name