<chapter id="generic-agent">
<title>Generic-Agent</title>
<para>
The Generic-Agent (bin/GenericAgent.pl) is a command line program wich can 
do some actions (like move, add note, set state, set owner) on tickets.
</para>

<sect1 id="generic-agent-config-file">
<title>Config File</title>
<para>
Kernel/Config/GenericAgent.pm is the default config file which must be copied 
(cp Kernel/Config/GenericAgent.pm.dist Kernel/Config/GenericAgent.pm). 
</para>
</sect1>


<sect1 id="generic-agent-example">
<title>Examples</title>
<para>
Now we want to go through a few examples. There is also a example config file 
(Kernel/Config/GenericAgent.pm.examples). 
</para>
<para>
Here all possible options:
<programlisting>
   'name of job' => {
      # get all tickets with these properties 
      Queue => 'system queue',
      States => ['new', 'open'],
      Locks => ['unlock'],
      # or escalation tickets
      Escalation => 1,

      # new ticket properties (no option is required, use just the options
      # which should be changed!)
      New => {
        # new queue
        Queue => 'new system queue',
        # possible states (closed successful|closed unsuccessful|open|new|removed) 
        State => 'closed successful',
        # new ticket owner (if needed)
        Owner => 'root@localhost',
        # if you want to add a Note
        Note => {
          From => 'GenericAgent',
          Subject => 'Your subject!',
          Body => 'Some comment!',
          ArticleType => 'note-internal', # note-internal|note-external|note-report
        },
        # your program (/path/to/your/program) will be executed like
        # "/path/to/your/program $TicketNumber $TicketID" ARG[0] will 
        # be the ticket number and ARG[1] the ticket id
        CMD => '/path/to/your/program',
        # DELETE ticket from database and filesystem
        Delete => 1,
     },
</programlisting>
</para>

<sect2>
<title>close spam tickets</title>
<para>
If you get spam tickets in your system and you want spend much time on it, 
create a queue (named spam) and just move the spam tickets into this queue.
If the bin/GenericAgent.pl runs, all open tickets in the queue spam will be
closed by the bin/GenericAgent.pl.
</para> 
<para>
Exampe for Kernel/Config/GenericAgent.pm
<programlisting>
[...]
   # --
   # [name of job] -> close all tickets in queue spam
   # --
   'close spam' => {
      # get all tickets with this properties  
      Queue => 'spam',
      States => ['new', 'open'],
      Locks => ['unlock'],
      # new ticket properties (no option is required, use just the options
      # which should be changed!)
      New => {
        # new queue
        Queue => 'spam',
        # possible states (closed successful|closed unsuccessful|open|new|removed) 
        State => 'closed successful',
        # new ticket owner (if needed)
        Owner => 'root@localhost',
        # if you want to add a Note
        Note => {
          From => 'GenericAgent',
          Subject => 'spam!',
          Body => 'Closed by GenericAgent.pl because it is spam!',
       },
     },
   },
[...]
</programlisting>
</para> 
</sect2>

<sect2>
<title>delete tickets</title>
<para>
If you want to delete (means delete ticket from database and filesystem) 
a ticket from a queue use this.
</para> 
<para>
Exampe for Kernel/Config/GenericAgent.pm
<programlisting>
[...]
   # --
   # [name of job] -> close and delete all tickets in queue delete
   # --
   'delete' => {
      # get all tickets with this properties  
      Queue => 'delete',
      States => ['new', 'open'],
      Locks => ['unlock'],
      # new ticket properties (no option is required, use just the options
      # witch should be changed!)
      New => {
        # DELETE!
        Delete => 1,
     },
   },
[...]
</programlisting>
</para> 
</sect2>

<sect2>
<title>move tickets from tricky to experts</title>
<para>
Moved ticket from tricky to experts queue and add note.
</para> 
<para>
Exampe for Kernel/Config/GenericAgent.pm
<programlisting>
[...]
   # --
   # [name of job] -> move all tickets from tricky to experts
   # --
   'move tickets from tricky to experts' => {
      # get all tickets with this properties  
      Queue => 'tricky',
      States => ['new', 'open'],
      Locks => ['unlock'],
      # new ticket properties
      New => {
        Queue => 'experts',
        Note => {
          From => 'GenericAgent',
          Subject => 'Moved!',
          Body => 'Moved from "tricky" to "experts" because it was not possible to find a sollution!',
          ArticleType => 'note-internal', # note-internal|note-external|note-report
        },
      },
   },
[...]
</programlisting>
</para> 
</sect2>

<sect2>
<title>move escalation ticket to experts and execute CMD</title>
<para>
If there is a escalation ticket, move it to experts and execute a command.
</para> 
<para>
Exampe for Kernel/Config/GenericAgent.pm
<programlisting>
[...]
   # --
   # [name of job] -> move all tickets from xyz to experts
   # --
   'move escalation ticket to experts and execute CMD' => {
      # get all tickets with this properties  
      Queue => 'xyz',
      Escalation => 1,
      # new ticket properties
      New => {
        Queue => 'experts',
        # your program (/path/to/your/program) will be executed like
        # "/path/to/your/program $TicketNumber $TicketID" ARG[0] will 
        # be the ticket number and ARG[1] the ticket id
        CMD => '/path/to/your/program',
      },
   },
[...]
</programlisting>
</para> 
</sect2>


</sect1>


</chapter>
