Events

Events provide a way to collect, view, and respond to exceptional occurrences in your application. For example, if the temperature of an engine exceeds a threshold, an event can be logged to record the anomaly. These Events can then be acknowledged by members of your organization or your Experience Users.

A list of your application’s Events can be found by clicking the “Events” link in the application menu. If your application has any Events in the “new” state, there will be a count bubble indicating how many match that state within the navigation link.

Event List

Event Queries

When retrieving lists of Events for use in your application, you may filter the Events returned through an advanced query. On the event list page, this defaults to all Events in a “new” state.

Event Query Panel

To write a new query, click the “Edit” (pencil) icon in the query box atop the event list. This will display a modal where you can build your event query.

Event Query Simple

First, choose the mode under which you would like to build your query: line by line using either the “Match any of the following …” or “Match all of the following …” options, or by building a MongoDB query using the “Advanced …” option..

Simple Queries

In most cases, you can retrieve Events by matching any or all of a series of simple queries. Choosing one of those two query modes will bring up an interface where you can build such a query:

Event Query Simple

Events may be queried by the following properties:

  • id: Return Events that match – or do not match – a given ID. (If matching by ID, this will return a maximum of one event.)
  • creationDate: Return Events created before – or after – a specific date.
  • lastUpdated: Return Events last updated before – or after – a specific date.
  • level: Return Events matching, more severe, or less severe than a valid event level.
  • state: Return Events matching – or not matching – a valid event state.
  • subject: Return Events matching, not matching, containing, starting with or ending with a given string.
  • deviceId: Return Events matching – or not matching – an associated device ID. You may also filter Events based on whether the property is set at all; for example, you may return all Events that have any deviceId value.
  • eventTags: Return Events matching – or not matching – a specific key, value, key/value pair.

Advanced Queries

If you are familiar with MongoDB’s find() syntax and would prefer to build your query that way, you may choose the “Advanced” option at the top of the query builder. The example simple query built above could also be written as the following advanced query:

Event Query Advanced

In addition to the properties listed for simple queries, in “Advanced” mode you may also build your query using the following event properties:

  • sourceId: Return Events that were created – or not created – by a specific resource by ID.
  • sourceType: Return Events that were created – or not created – by one of the valid event source types.
  • message: Return Events matching by the contents of the “message” field, much in the same was as the “subject” field can be queried.

Note: If you start by building a simple query and then switch to “Advanced” mode, your simple query will translate into an advanced query within the query editor. An advanced query may translate into a simple query depending on how the query is built; if the translation fails, you must build a new simple query from scratch.

Bulk Event Updates

After building an event query on the event list page, you may edit all Events matching the query by clicking the button in the top right corner of the list and selecting an action. Individual Events may also be edited from the table view by clicking the icon in the right column of each event row.

Bulk Event Update

Creating Events

Typically, Events are created using the Event: Create Node in the Workflow Engine since they are often a response to Device: State Triggers or the actions of Experience Users. However, it is possible to manually create an event by clicking the “Add Event” link at the top of the event list.

Add Event

Event Properties

Provide the following information when creating an event:

  • Subject: (required) This is the event’s title, which will be the primary information displayed in the event list.
  • Event Level: (required) This must be one of four values: “Critical” (default), “Error”, “Warning”, or “Info”.
  • Message: This is additional information pertaining to an event, much like a description to accompany the subject.
  • Associated Device: Optionally, you may tie this event directly to one of your application’s devices. This property can be useful for filtering your Events by a specific device - for example, to see all the times a generator’s output dipped below a threshold.
  • Additional Data: If you need to provide complex data that does not map well to the other event fields, you may place that data on the event as a JSON object.
  • Event Tags: You may provide one or more key/value pairs to store additional event metadata.

Note: Other than tags, none of an event’s properties may updated after creation. Updates may only be passed through the event’s life cycle.

Viewing Event Details

From your application’s event list, click the subject of any event to view additional information. At the top of the page is a box indicating the event’s level, subject, state, device association, and when and how the event was created.

Event Header

Beneath that are a series of tabs for viewing and updating additional event information.

Updates

This tab displays any comments and state changes applied to the event through its life cycle. Each comment / state change has an entry on the page as well as who / what made the update. You may also add an update to the event directly from this interface using the form at the bottom of the updates list.

Event Updates

Tags

Must like for other platform resources, tags are a great way to track additional metadata associated with an event. Examples include status codes, resolution instructions, or geographic information. Tags area also useful for building event queries to retrieve subsets of your application’s events.

Event Tags

Event tags may be updated after event creation, which can allow for more advanced tracking outside of the standard life cycle and event schema. For example, if your application requires additional states beyond the options provided, or if you wish to break down the provided levels more granularly, tags can help you accomplish those goals.

Similar Items

From an event’s detail page, you may also view other Events that match that event’s subject, level, and associated device. This is useful for viewing other occurrences of the same event over time, as well as if any other such occurrences have yet to be resolved.

Event Similar Items

Using Events

Events are typically consumed one of three ways:

Events can also be used to trigger other workflows. For example, if you wanted to perform additional actions when an event gets created or moved through the life cycle, you could use the Event Trigger Node to trigger additional workflows.

Event Trigger

In the above example, the workflow is triggered whenever an event is created with a specific level (error). The workflow then sends an SMS message to alert the user.

Events Life Cycle

Events include basic life cycle features for proper organization and handling. Typically, an event starts out in the new state; then, a user or a workflow marks the event as acknowledged and ultimately as resolved.

How the Events transition through these states is entirely up to your and your specific application. A log of who/what transitioned an event (as well as when that occurred) is attached to each event with optional comments and structured data, which is available on the event’s Updates tab.