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 Queries

The list of Events are filtered by Events that only have the “new” state by default. There are two options available to view Events based on your own custom criteria.

The first option is to use the filter controls located in the table headers.

The second option is to use an advanced query.

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. These queries also support numerical operators, where critical > error > warning > info.
• state: Return Events matching – or not matching – a valid event state. These queries also support numerical operators, where resolved > acknowledged > new.
• 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.
• experienceGroupId: Return Events associated – or not associated – with an Experience Group. This is determined by whether the Event has a deviceId property set, and whether that Device is associated with a given Experience Group.
• experienceUserId: Return Events associated – or not associated – with an Experience User. This is determined by whether the Experience User is a member of an Experience Group that is associated with the Device tied to the Event.
• eventTags: Return Events matching – or not matching – a specific key, value, key/value pair.

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.

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.

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.

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.

Event Limits

Event creation is limited to 15 creations in a 15-second window per application (or, on average, one per second).

Events are also subject to your Losant Organization’s data retention limit.

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.

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.

Tags

Just 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 are also useful for building event queries to retrieve subsets of your application’s events.

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.

Using Events

Events are typically consumed one of three ways:

• The application’s “Events” page, as described above
• Using the Event List Dashboard Block
• Through a custom interface built within a Losant Experience, in which case the data is retrieved using the Event: Get Node

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 to trigger additional workflows.

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 you 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.