What Are Rules?

Rules define what data (i.e. device events) to capture, how to transform those events, and what to do with transformed events. Events not matching any rule are discarded. Without rules, your data pipeline ends prematurely, with all of your device data gushing into the abyss, instead of into your app.

Rules are written in a custom domain specific language called rule syntax.
All rules have four parts:

You can see the four clauses in the example "catch-all" rule below.

AllEvents Rule

The rule clause identifies and names the rule.

The two elements of the rule clause are listed below.

The rule name is any string of your choice.

The using clause allows you to transform selected event data into a new structure and enhance the data using built-in functions (listed below).

In order to properly transform an event's structure, you must know the event's incoming structure. For this, you'll need to refer to our event catalog.

• The map(s) name can be any identifier of your choice (e.g. "my_map", "message", etc.)
• The map itself is any number of recursive expressions, including arrays, objects, literal values, strings with inserted fields, and event fields.

Arrays are an ordered group of elements. This expression is most useful when the incoming event contains data that you want to convert into an ordered list. To create an array, fill two square brackets with the fields from the event you want.

The example below shows a transformation of the latitude and longitude fields in the Danlaw UDP Header into an array.

Objects contain data. If you want to group related data into an object, this is easily achieved by filling curly braces with the fields from the event you want.

In the example below, we've selected only the fields we want from the message object of the Danlaw UDP Connect Event and created our own object.

Literal values are values written exactly as they're meant to be interpreted. In some cases, you may want to add static fields to your event.

Let's take the example above. Maybe instead of getting an object that says, eventType = Connect inside an object, you want something easier to display, so you insert a literal.

You can also define whole strings and insert fields from your event into the string. A string is contained in single quote marks, preceded by a lowercase letter s, while the inserted fields are surrounded by curly braces, preceded by the $ sign.

We'll continue with the example above. Maybe you want a sentence that you can display directly on your UI, so instead of defining your map as a JSON object, you make it a string and insert the fields that provide the information you need.

The where clause is the filter that grabs the events you're interested in from the stream of your data.

Each incoming event is evaluated against the where clause of every rule you've created. If the conditions of the event match the where clause, it will be processed by the rule according to the using and with clauses.

These boolean values can be combined, but order is important.

The simplest and most common boolean usage is the eq value, which looks for an exact match in a field. Provide the map of the field that you're filtering on (and for this you'll need to look at the structure of the incoming event in the event catalog) and follow it with the string value you're interested in in single quotes.

Let's say you want to capture all the idling events sent by all of your devices. You know that your devices send information over the Danlaw UDP protocol, so you look at the Danlaw UDP Idling Message and see that the type field inside the message object inside the body object is what you're interested in.

The gt boolean allows you to ignore values below a threshold. Provide the map of the field that you're filtering on (and for this you'll need to look at the structure of the incoming event in the event catalog) and the follow it with your threshold value.

In the example below, the rule will look for Malfunction Indicator Lamp alerts where the driver has driven for more than 100 miles (160 km) with the light on. The incoming event structure can be seen here.

The lt boolean allows you to ignore values above a threshold. Provide the map of the field that you're filtering on (and for this you'll need to look at the structure of the incoming event in the event catalog) and the follow it with your threshold value in single quotes.

Maybe you're doing some analysis on short trips. You filter out Danlaw UDP Trip End Events that show a trip time of less than 10 minutes (600 seconds).

The and boolean is a powerful tool that allows you to combine the other boolean values listed here to better filter out unwanted events. To combine two boolean values, nest them inside parentheses with and in front.

Let's say you're interested in battery alerts. In order to filter out the OBD-II events that are lumped into a single event type in the UDP protocol, you would look for an exact match on two fields instead of one, using the conjunction.

The or boolean is similar to and in that it combines two nested boolean values. Only one must evaluate to true to trigger the rule, instead of both. To combine two boolean values, nest them inside parentheses with or in front.

For example, you may be interested in both current and pending DTC events. Instead of writing two rules to capture these events, you could write one using the or boolean.

The contains boolean allows you to filter events based on objects or fields that may not always be present in a certain event. This clause is especially useful when extracting PID data that is logged at varying frequencies in the TCP Relative Time Trip Data Events. In the parentheses after contains, provide the map that will contain the field or object that you're filtering on, followed by the string of the field or object name in single quotes.

For example, let's say your Dataloggers are collecting PID 12 (Engine RPM) every 2 seconds and PID 13 (Vehicle Speed) every second. Data from both of these PIDs are present in every other Trip Data event, but you want to capture them separately.

*Note: In order to only pass through the PID data that you're filtering on, instead of the entire set of PIDs present in the object, you'd need to make use of the transformations in the using clause).

Not allows you to exclude certain parameters from a rule that would otherwise collect events meeting its criteria. While not can be used alone, it's most useful when combined with another boolean value.

For example, let's say you're interested in capturing Danlaw UDP GPS events; however, you need to exclude Danlaw UDP Heartbeat events, which are a subset of GPS events. You can use the not boolean to do this.

The with clause defines what to do with events that are matched by the where clause and transformed by the using clause.

Currently, there are 3 actions supported:

Multiple actions can be defined for a single rule. Use a comma to separate actions in the with clause.

The most commonly used action is AMQP. AMQP sends transformed events to an exchange (named actions) in your vhost on RabbitMQ. You can then use standard RabbitMQ clients to consume events from managed or unmanaged queues.

The AMQP action supports three arguments: key, headers, and body.

Currently, the only supported encoding of data sent across the platform is JSON, so the action argument that body takes is a transformation of the map you defined in the using clause into a JSON object.

Send your data to cloud storage directly with the DynamoDB destination.

Send your data directly to a configured Webhook destination.

A webhook is an HTTP message that is POSTed to a configured URL.

The webhook action supports two arguments: uri and body.