Leap Event Framework

What is Eventing?

Leap Eventing is the process by which Leap Features are able to securely Subscribe to and Publish events. The events can be system-level events as well as feature-level events.

When Subscribing to an event source, Leap allows you to specify an MVEL value as criteria to the subscription. That way only a certain subset of messages even make it into the subscriber. Additionally, once an event reaches a subscriber it can be routed based on an optional expression. This allows a single subscriber to take different actions based on the contents of the event.

Events can even be routed over other protocols like HTTP or the Leap Pipeline

In the case that an error occurs while routing an event, a custom retry strategy can be implemented. Yet, the LeapDefaultRetryStrategy will suffice for the most common use cases. This allows for flexible yet durable integrations.

When to use Eventing?

Most commonly Leap Eventing will be used to handle and generate events such as:

• EAS Event Subscriptions
• System Events
• Feature Events
• Externally Sourced Events

Eventing should be considered whenever data need to be published or consumed in a de-coupled environment. Event-based systems allow separate pieces of a solution to work independently without knowing how each other functions or even where they are located. Instead, unlike integrations that use HTTP, event-based systems rely on a common ally, usually a Topic or Queue, to bridge the gap.

Event Subscriptions

At this time, Leap Eventing supports subscribing to either Kafka Topics or JMS Queues. Further subscription implementations can be easily added as necessary, however, to date, these two are the most common subscription types and are fully supported.

For a detailed guide on Leap Event Subscriptions, please read Leap Event Subscriptions

Event Publishers

Leap Eventing refers to Publishers as Event Dispatchers. This is because the term “publish” is often associated with certain types of message/event methods. The term “dispatcher” is a more general term that better fits the wide variety of potential output methods for events.

Currently, Event Dispatchers support sending events to:

• File – some file on the local server with appropriate permissions
• JMS – publish events into the provided queue for a given tenant
• Topic – publish events into the provided topic for a given tenant
• Leap Service – able to dispatch events directly to an existing Service defined on the same server.
• HTTP – Send and HTTP GET or POST request with the event contents as the body

For a detailed guide on Leap Event Publishers, please read Leap Event Publishers.

Event Data Format

In order to fully support multi-tenant eventing and authentication, the Leap Event Framework requires that the event data consumed by a subscriber is of a specific format.

At this time, the event at format only supports JSON

Event ID

This value should always be a unique value, it is used as a fingerprint to identify specific events that pass through the Leap Eventing Framework. It is the responsibility of the event originator to ensure proper event ID values are used.

Event Header

The first part of the JSON structure is called the EventHeader this is where the multi-tenant information belongs. When generating an Event from the Leap Framework, this will be added automatically. But, when creating events from an external source, the data format must be maintained manually.

Required fields:

• sideId – this represents the specific site associated with the event. The smallest unit of value when determining multi-tenancy
• tenantId – unique value representing a tenant on this Leap instance. When the account is generated, the public tenant ID is also generated.

TenantId is like a public key, Leap maintains the private Tenant Information in a secure, encrypted store. This allows for the public tenantId to be easily updated in the case of a security breach.

Event Param

Event Param is the part of the Event JSON where all of the custom data fields exist. The format of this structure follows the Leap Request Specification. This means that the originator must provide the following fields:

• apiVersion – at this time “1.0” is the only supported value. With future iterations of Leap, this may change in order to support a wider collection of API versions
• context – although this field can be blank, it should be used to store any unique identifiers associated with this specific event data
  • For example, when sending a JMS message the CorrelationId might go here in order to support Request/Reply
• lang – ISO 639 language code for internationalized data
• data – the main payload of the event or event body. This is where all of the custom event data exists

Event Data Examples

{
   "EventHeader":{
      "siteId":"all",
      "tenantId":"all"
   },
   "EventId":"SENSOR_EVENT",
   "EventParam":{
      "apiVersion":"1.0",
      "context":"",
      "lang":"en",
      "data":{
         "publisher":"temp_sense_082_dht11",
         "sensorData":{
            "tempF":"74.2",
            "humid":"43%"
         }
      }
   }
}