Universal Event Templates

Universal Event Templates

Universal Events are administrator-defined events with administrator-defined attributes.

Universal Events can be defined:

Globally

In a Universal Event Template.

Locally

As part of a Universal Extension-based Universal Template.

Note

When publishing Universal Events through the Web Service API or an extension-based Universal Task Publisher, take into consideration both Universal Controller server and Database server sizings.

Global Universal Events

For any global Universal Event, you must define a Universal Event Template for it to allow the event to be monitored by a Universal Monitor.


Local Universal Events

If a Universal Template type is Extension, and the Universal Extension can generate a local Universal Event, you must identify the Event by using the Event Templates tab on the Universal Template Details to allow the event to be monitored by an Universal Monitor.

Global and Local Universal Events

Additionally, Extension-based Universal Templates can publish global Universal Events.



Creating a Universal Event Template

Step 1

From the Automation Center navigation pane, select Configuration > Universal Event Templates. The Universal Event Templates list displays a list of all existing Universal Event Templates.

Below the list, Universal Event Template Details for a new Universal Event Template displays.


 

Step 2

Enter / select Details for a new Universal Event Template, using the field descriptions below as a guide.

  • Required fields display an asterisk ( * ) after the field name.
  • Default values for fields, if available, display automatically.

To display more of the Details fields on the screen, you can either:

  • Use the scroll bar.
  • Temporarily hide the list above the Details.
  • Click the  button above the list to display a pop-up version of the Details.

Step 3

Click a  button. The task is added to the database, and all buttons and tabs in the Universal Task Details are enabled.

Note

To open an existing record on the list, either:

  • Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
  • Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
  • Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).

Universal Event Template Details

The following Universal Event Template Details is for a new Universal Event Template.

Depending on the values that you enter / select for these fields, more (or less) fields may display. See the field descriptions, below, for a description of all fields that may display in the Universal Event Template Details.

Universal Event Template Details Field Descriptions

The following table describes the fields, buttons, and tabs that display in the Universal Event Template Details.
 

Field Name

Description

DetailsThis section contains assorted detailed information about a Universal Event Template.

Name

Name of this Universal Event.

Label

User-friendly display name for this event, to be displayed within the client. The Label must be unique for Global Events and unique within Local Events.

Description

Description of this event.

Time To Live

Default value for the length of time, in minutes, that the Universal Event data is valid. This value can be unspecified (null).

The Time To Live value can be overridden in the published event.

If the Time To Live does not exist in the published event, then this value, if defined, will be used.

If neither value exists, the Time To Live is 0, which means the event is deleted as soon as it is published.

Unmapped Attributes Policy

Defines how unmapped/unknown attributes that are in the published event are handled.

  • Prohibit Universal Event
    If the published event has any attributes that have not been defined in the template, the publish is rejected and not allowed.

  • Include Attributes
    Any extra attributes will be allowed and passed through as variables.

  • Exclude Attributes
    Any extra attributes are excluded and ignored. They will not be passed along as variables.

Attributes

Name, Label, and Type of each attribute.

  • Name
    Unique name for this attribute.

  • Label
    User-friendly display name for this attribute, to be displayed within the client.

  • Type
    Type of attribute:

    • Text

    • Integer

    • Boolean

    • Float
    • Text Array
    • Integer Array
    • Boolean Array
    • Float Array
System EventIndication if this type of event is a System Event.
Metrics

This section contains information about configuring metrics for a Universal Event Template.

To enable OpenTelemetry metrics, you must configure an Open Telemetry metrics exporter in uc.properties , otherwise, a noop meter provider is used.

Metric Type

Specifies the type of metric to instrument. Options are:

  • None

  • Counter

  • UpDownCounter

  • Histogram

Metric Name

Specifies the metric name.

The metric name can be a maximum of 63 characters and should be universally unique, for example:

<event_name>[.<value_attribute>]

<extension>.<event_name>[.<value_attribute>]

The universal event Description will be used as the metric description.

The following namespaces (prefixes) are reserved and cannot be used for user-defined metric names.

  • uc. and uc_

  • ua. and ua_

  • uac. and uac_

Metric Value Attribute

Specifies the name of an Integer or Float universal event attribute to use for the metric value when incrementing the counter or recording a histogram value.

If left unspecified, a counter will be incremented by 1, and a histogram will record a value of 1, for each published universal event.

Metric Unit

Specifies an optional unit of measure.

Maximum length of 63 ASCII characters. Units should follow the Unified Code for Units of Measure.

Metric Label Attributes

Specifies a comma-delimited list of universal event attribute names to use for metric labels.

For example, attribute1,attribute2,attribute3

At most 8 label attributes can be specified.

Do not specify attributes with high cardinality (many different attribute values) or attributes that may contain sensitive information.

Optional Metric Labels

Specifies which system-supplied metric labels to include.

  • Agent Id

    • Label: agent.id

  • Business Services

    • Label: security.business_services

  • Task Name

    • Label: task.name

The Task Name value will be represented by the unresolved task name at launch time to avoid the high cardinality of resolved task instance names.

If multiple business services are assigned to the universal event, the Business Services value will be represented as a comma-delimited list of business services in alphabetical order.Be mindful that the Business Services metric label could have high cardinality depending on how you assign business service membership.

User-Defined Metric Name and Labels

If the OTEL metrics exporter is configured, for each Universal Event Template or Universal Template Event Template with a metrics designation, the following metric will be exported.

Name

<metric-name>_<metric-unit>_total

The metric name and labels may differ depending on the metric type and/or any normalization you are using, for example, Prometheus Normalization.

Type

Counter, UpDownCounter, or Histogram

Description

The metric description is inherited from the Universal Event Template or Universal Template Event Template.

Default Labels

  • exported_instance
  • exported_job
  • universal_event_name
  • universal_template_name
  • universal_extension_name

Optional Labels

  • label_attr_1, …, label_attr_n
  • agent_id
  • task_name
  • security_business_services

Example

The universal_template_name and universal_extension_name label values are non-empty for published local Universal Events (defined by a Universal Template Event Template) and empty for published global Universal Events (defined by a Universal Event Template).

<metric-name>_<metric-unit>_total{

exported_instance="<service-instance-id>",

exported_job="<service-namespace>/<service-name>",

universal_event_name="<unv-event-name>",

universal_template_name="<unv-template-name>,

universal_extension_name="<unv-extension-name>",

[label_attr_1="<attr-1-value>",]

...,

[label_attr_n=”<attr-n-value>”,]

[agent_id="<agent-id>",]

[task_name="<task-name>",]

[security_business_services="<security-business-services>"]}

Pre-Defined Global Universal Event

Universal Controller is pre-populated with global Universal Event system templates:

  • System Property Changed
  • Agent Changed
  • Task SLA

  • Task Status Changed 

(System Templates are read-only and cannot be deleted. During a new installation or a maintenance update, System Templates are imported.)

System Property Changed Universal Event

Whenever a Universal Controller system property is updated (from an active or passive node), a UAC - Property Changed Universal Event will be published.

The event attributes are shown below.

Agent Changed Universal Event

A UAC - Agent Changed Universal Event will be published if one of the following conditions is met.

  • Active - Agent becomes Active.

  • Decommissioned - Agent gets marked as Decommissioned.

  • Deleted - Agent is Deleted.

  • Offline - Agent goes Offline.

  • Suspended - Agent gets Suspended.

  • Registered - New Agent is Registered into the system.

  • Resumed - Agent is Resumed.

  • Updated - Agent is updated, for example any update from the UI or Web Service to any of the Agent fields (Name, Description, Business Services, Log Level, Heartbeat info, Task Execution info, Credentials).

The event attributes are shown below.

Task SLA Universal Event

A UAC - Task SLA Universal Event will be published if any task instance has a Late Start, Late Finish or Early Start SLA violation.

The event attributes are shown below.

Task Status Changed Universal Event

A UAC - Task Status Changed Universal Event will be published if the task instance status changes.

The event attributes are shown below.