EventHandler

EventHandler#

NAME#

Kernel::System::EventHandler - event handler interface

DESCRIPTION#

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

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.

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

Example 1:

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

Example 1 XML config:

<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:

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

Example 2 XML config:

<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:

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:

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

EventHandlerTransaction()#

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

$EventHandler->EventHandlerTransaction();

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

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.

Contents