############
GenericAgent
############


****
NAME
****


Kernel::System::GenericAgent - to manage the generic agent jobs


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


All functions to manage the generic agent and the generic agent jobs.


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


new()
=====


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


.. code-block:: perl

     my $GenericAgentObject = $Kernel::OM->Get('Kernel::System::GenericAgent');



JobRun()
========


run a generic agent job


.. code-block:: perl

     $GenericAgentObject->JobRun(
         Job          => 'JobName',
         OnlyTicketID => 123,        # (optional) for event based Job execution
         SleepTime    => 100_000,    # (optional) sleeptime per ticket in microseconds
         UserID       => 1,
     );



JobList()
=========


returns a hash of jobs


.. code-block:: perl

     my %List = $GenericAgentObject->JobList();



JobGet()
========


returns a hash of the job data


.. code-block:: perl

     my %Job = $GenericAgentObject->JobGet(Name => 'JobName');



JobAdd()
========


adds a new job to the database


.. code-block:: perl

     $GenericAgentObject->JobAdd(
         Name => 'JobName',
         Data => {
             Queue => 'SomeQueue',
             # ...
             Valid => 1,
         },
         UserID => 123,
     );



JobDelete()
===========


deletes a job from the database


.. code-block:: perl

     my $Success = $GenericAgentObject->JobDelete(
         Name   => 'JobName',
         UserID => 123,
     );


returns:


.. code-block:: perl

     $Success = 1;       # or false in case of a failure



JobExport()
===========


export a job


.. code-block:: perl

     my $ExportData = $GenericAgentObject->JobExport(
         # required either Name or ExportAll
         Name       => 'job1', # required
                               # or
         ExportAll  => 0,      # required, possible: 0, 1
     );


returns Job hashes in an array with data:


.. code-block:: perl

     my $ExportData =
     [
         {
             'Name' => 'job1',
             'NewNoteBody' => '123123',
             'ChangeTimeSearchType' => '',
             'NewCustomerID' => '123213',
             'NewTypeID' => '2',
             'TicketCreateTimePoint' => '16',
             'NewParamKey6' => '',
             'LastCloseTimeSearchType' => '',
             'NewQueueID' => '13',
             'TicketLastChangeTimeOlderDate' => '2026-07-02 23:59:59',
             ...
         },
         {
             'Name' => 'job2',
             ...
         }
     ];



JobImport()
===========


import a job YAML file/content


.. code-block:: perl

     my $JobImport = $GenericAgentObject->JobImport(
         Content               => $YAMLContent, # mandatory, YAML format
         OverwriteExistingJobs => 0,            # optional, possible: 0, 1
         UserID                => 1,            # mandatory
     );


Returns:


.. code-block:: perl

     $JobImport = {
         Success          => 1,                                  # 1 if success or undef if operation could not
                                                                 # be performed
         Message          => 'The Message to show.',             # error message
         Added            => 'Job1, Job2',                       # string list of Jobs correctly added
         Updated          => 'Job3, Job4',                       # string list of Jobs correctly updated
         NotUpdated       => 'Job5, Job6',                       # string of Jobs not updated due to existing entity
                                                                 # with the same name
         Errors           => 'Job5',                             # string list of Jobs that could not be added or updated
         AdditionalErrors => ['Some error occured!', 'Error2!'], # list of additional error not necessarily related to specified Job
     };



JobCopy()
=========


copy a job


.. code-block:: perl

     my $NewJobName = $GenericAgentObject->JobCopy(
         Name    => 'job1', # mandatory
     );



JobExportDataGet()
==================


get data to export job


.. code-block:: perl

     my %JobData = $GenericAgentObject->JobExportDataGet(
         Name => 'job1', # mandatory
     );


Returns:


.. code-block:: perl

     my %JobData = (
         'Name' => 'job1',
         'NewNoteBody' => '123123',
         'ChangeTimeSearchType' => '',
         'NewCustomerID' => '123213',
         'NewTypeID' => '2',
         'TicketCreateTimePoint' => '16',
         'NewParamKey6' => '',
         'LastCloseTimeSearchType' => '',
         'NewQueueID' => '13',
         'TicketLastChangeTimeOlderDate' => '2026-07-02 23:59:59',
         ...
     )



JobExportFilenameGet()
======================


get export file name based on job name


.. code-block:: perl

     my $Filename = $GenericAgentObject->JobExportFilenameGet(
         Name => 'Job_1',
         Format => 'YAML',
     );



StopWordsErrorsGet()
====================


check if passed fields contain invalid stop word


.. code-block:: perl

     my %Errors = $GenericAgentObject->StopWordsErrorsGet(
         Fields => {
             SomeField => 'over',
             MIMEBase_From => 'the',
         },
         CheckConfig => 1, # optional
                           # possible: 0, 1
                           # default: 1
     );



JobInsertErrorsCheck()
======================


Perform checks for insert job action.
Recommended to use before every add/update function or
as additional layer of validation.


.. code-block:: perl

     my %Errors = $GenericAgentObject->JobInsertErrorsCheck(
         Name             => 'job1',
         NewNoteFrom      => $GetParam{NewNoteFrom},
         NewNoteSubject   => $GetParam{NewNoteSubject},
         NewNoteBody      => $GetParam{NewNoteBody},
         MIMEBase_From    => $GetParam{MIMEBase_From},
         MIMEBase_To      => $GetParam{MIMEBase_To},
         MIMEBase_Cc      => $GetParam{MIMEBase_Cc},
         MIMEBase_Subject => $GetParam{MIMEBase_Subject},
         MIMEBase_Body    => $GetParam{MIMEBase_Body},
     );



JobEventList()
==============


returns a hash of events for each job


.. code-block:: perl

     my %List = $GenericAgentObject->JobEventList();



_JobRunTicket()
===============


run a generic agent job on a ticket


.. code-block:: perl

     $GenericAgentObject->_JobRunTicket(
         TicketID     => 123,
         TicketNumber => '2004081400001',
         Config       => {
             %Job,
         },
         UserID       => 1,
     );