
[[ga-events-event-definition]]
= Event Definition
:description: How to associate and event with an existing node in {page-component-title}, and descriptions of mandatory fields.

== Associate an event to a specific node

There are two ways to associate a given event to an existing node, prior to sending the event to the event bus:

* Set the event's `nodeId` to the database ID of the desired node.
* For requisitioned nodes, set the `_foreignSource` and `_foreignId` as parameters to the event.
In this case, any incoming event without a `nodeId` and these two parameters will trigger a database lookup.
If a node is found, the `nodeId` attribute will be dynamically set on the event, regardless of which method has been used to send it to the event bus.

[[ga-events-anatomy-of-an-event]]
== Anatomy of an event

Events are structured historical records of things that happen in {page-component-title} and the nodes, interfaces, and services it monitors.
Every event has a number of fixed fields and zero or more parameters.

*Mandatory fields*

UEI (Unique Event Identifier)::
    A String that uniquely identifies the event's type.
    UEIs are typically formatted in the style of a URI, but the only requirement is that they start with `uei.`.
Event Label::
    A short, static label that summarizes the gist of all instances of this event.
Description::
    A long-form description of all instances of this event.
    You can use HTML formatting to format the body of the event text.
Log Message::
    A long-form log message that describes this event, optionally including expansions of fields and parameters so that the value is tailored to the event at hand.
    It includes the `dest` (destination) attribute, which defines how the event is treated, including the following options:
    logndisplay:::
        Log the event in the database and display it in the web UI.
    logonly:::
        Log the event in the database, but do not display it.
    suppress:::
        Neither log the event in the database nor display it.
    donotpersist:::
        Do not log the event in the database, but still send it to daemons that are listening for this type of event, such as those being used to generate notifications.
        Note that eventd and alarmd do not process this type of event.
    discardtraps:::
        This applies only to traps coming in via trapd.
        This will cause trapd to discard the trap without creating an event.
        Other daemons that are listening for this type of event will not receive this event.
	Events not related to trapd will be processed as if they are marked with `suppress'.
Severity::
    A severity for this event type.
    Possible values range from `Cleared` to `Critical`.
    Refer to our <<deep-dive/events/event-configuration.adoc#severities, notes on severities>> for tips on how to best set the event levels.
Event ID::
    A numeric identifier used to look up a specific event in the {page-component-title} system.

*Notable optional fields*

Operator Instruction::
    A set of instructions for an operator to respond appropriately to an event of this type.
Alarm Data::
    If this field is provided for an event, {page-component-title} will create, update, or clear alarms for events of that type according to the alarm-data specifics.
