############
EventHandler
############


****
NAME
****


Kernel::System::EventHandler - event handler interface


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


Inherit from this class if you want to use events there.


.. code-block:: perl

     use parent qw(Kernel::System::EventHandler);


In your class, have to call `EventHandlerInit()`_ first.

Then, to register events as they occur, use the `EventHandler()`_
method. It will call the event handler modules which are registered
for the given event, or queue them for later execution (so-called
'Transaction' events).

In the destructor, you should add a call to `EventHandlerTransaction()`_
to make sure that also \ ``Transaction``\  events will be executed correctly.
This is only necessary if you use \ ``Transaction``\  events in your class.


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


EventHandlerInit()
==================


Call this to initialize the event handling mechanisms to work
correctly with your object.


.. code-block:: perl

     $Self->EventHandlerInit(
         # name of configured event modules
         Config     => 'Example::EventModule',
     );


Example 1:


.. code-block:: perl

     $Self->EventHandlerInit(
         Config     => 'Ticket::EventModulePost',
     );


Example 1 XML config:


.. code-block:: perl

     <ConfigItem Name="Example::EventModule###99-EscalationIndex" Required="0" Valid="1">
         <Description Translatable="1">Example event module updates the example escalation index.</Description>
         <Group>Example</Group>
         <SubGroup>Core::Example</SubGroup>
         <Setting>
             <Hash>
                 <Item Key="Module">Kernel::System::Example::Event::ExampleEscalationIndex</Item>
                 <Item Key="Event">(ExampleSLAUpdate|ExampleQueueUpdate|ExampleStateUpdate|ExampleCreate)</Item>
                 <Item Key="SomeOption">Some Option accessable via $Param{Config}->{SomeOption} in Run() of event module.</Item>
                 <Item Key="Transaction">(0|1)</Item>
             </Hash>
         </Setting>
     </ConfigItem>


Example 2:


.. code-block:: perl

     $Self->EventHandlerInit(
         Config     => 'ITSM::EventModule',
     );


Example 2 XML config:


.. code-block:: perl

     <ConfigItem Name="ITSM::EventModule###01-HistoryAdd" Required="0" Valid="1">
         <Description Translatable="1">ITSM event module updates the history for Change and WorkOrder objects..</Description>
         <Group>ITSM Change Management</Group>
         <SubGroup>Core::ITSMEvent</SubGroup>
         <Setting>
             <Hash>
                 <Item Key="Module">Kernel::System::ITSMChange::Event::HistoryAdd</Item>
                 <Item Key="Event">(ChangeUpdate|WorkOrderUpdate|ChangeAdd|WorkOrderAdd)</Item>
                 <Item Key="SomeOption">Some Option accessable via $Param{Config}->{SomeOption} in Run() of event module.</Item>
                 <Item Key="Transaction">(0|1)</Item>
             </Hash>
         </Setting>
     </ConfigItem>
     <ConfigItem Name="ITSM::EventModule###02-HistoryAdd" Required="0" Valid="1">
         <Description Translatable="1">ITSM event module updates the ConfigItem History.</Description>
         <Group>ITSM Configuration Management</Group>
         <SubGroup>Core::ITSMEvent</SubGroup>
         <Setting>
             <Hash>
                 <Item Key="Module">Kernel::System::ITSMConfigurationManagement::Event::HistoryAdd</Item>
                 <Item Key="Event">(ConfigItemUpdate|ConfigItemAdd)</Item>
                 <Item Key="SomeOption">Some Option accessable via $Param{Config}->{SomeOption} in Run() of event module.</Item>
                 <Item Key="Transaction">(0|1)</Item>
             </Hash>
         </Setting>
     </ConfigItem>



EventHandler()
==============


call event handler, returns true if it was executed successfully.

Example 1:


.. code-block:: perl

     my $Success = $EventHandler->EventHandler(
         Event => 'TicketStateUpdate',   # event classification, passed to the configured event handlers
         Data  => {                      # data payload for the event, passed to the configured event handlers
             TicketID => 123,
         },
         UserID => 123,
         Transaction => 1,               # optional, 0 or 1
     );


In 'Transaction' mode, all events will be collected and executed together,
usually in the destructor of your object.

Example 2:


.. code-block:: perl

     my $Success = $EventHandler->EventHandler(
         Event => 'ChangeUpdate',
         Data  => {
             ChangeID => 123,
         },
         UserID => 123,
     );



EventHandlerTransaction()
=========================


handle all queued 'Transaction' events which were collected up to this point.


.. code-block:: perl

     $EventHandler->EventHandlerTransaction();


Call this method in the destructor of your object which inherits from
Kernel::System::EventHandler, like this:


.. code-block:: perl

     sub DESTROY {
         my $Self = shift;
 
         # execute all transaction events
         $Self->EventHandlerTransaction();
 
         return 1;
     }



EventHandlerHasQueuedTransactions()
===================================


Return a true value if there are queued transactions, which
\ ``EventHandlerTransaction``\  handles, when called.