Rule Based Notifications

Rule: A rule is used to evaluate conditions and to run actions based on result of the evaluation. Conditions are user-defined expressions of logical statements about relationship between device entities. Expressions are written using Ayla Rule Expression Syntax (ARES).

Action: An action is used to execute specific tasks and/or to update data. When a rule expression evaluates to true, associated actions are executed.

The below table lists some of the action types. Refer Get Action Types to know the complete list of action types.

Destination: A destination contains a message, a delivery address, and a provider type. Destination types include email, sms, and push. Providers are tied to the destination type:

• EMAIL providers include smtp.
• SMS providers include twilio and yunpian.
• PUSH providers include fcm and apns.
  Depending on the type, destinations may include additional fields.

Notification Types

Ayla platform supports two types of rule based notifications:

Property Based Notification

Each device can have a number of properties. Property based notification is sent when a property value changes through their datapoint(s). You can create rules to address a single property value change or combination of multiple properties’ values.
For example, send a text message when the Blue_button is pressed on an Ayla devkit.

Device Event Based Notification

A device event-based notification is sent when a device loses and/or restores connectivity to the Ayla Device Service, changes IP address, etc. A threshold value is set to know when a change can be intimated to the application using Connection Status Services.

Relationships

This section describes the relationships among events, rules, actions, and destinations.

Figure1 suggests that rules provide a criterion for decision-making, actions define the data payload, and destinations provide delivery information.

Figure2 describes that Ayla Rule Service (ARS) determines whether an event satisfies a rule expression. If satisfied, the associated action(s) are executed.

NOTE:

• One rule can reference to multiple actions.
• One rule can reference different types of actions.
• More than one rule can reference the same action.
• Actions do not reference rules.
• Deleting a rule does not delete an action.
• The actions and destinations must be of the same type.
• Destinations do not reference actions.
• Deleting an action does not delete a destination.

Use Case

The following is an example use case:

1. You have a device called Edge Device (dsn = AC000W000000001) connected to Ayla Cloud. Your device has three properties:

2. Whenever the Edge Device host app receives a new decimal_in value, it sets decimal_out to the same value, and sends the new decimal_out value to the cloud. This is a technique for prompting your device to send certain values to the cloud as if originating at the device, thus simulating changes in temperature, pressure, gas levels, etc.
3. When decimal_out is less than 90.0, you must set Blue_LED to 1. The first part requires a rule, and the second part requires an action. You can inform the user about this change in the Edge Device by creating a destination. An example SMS destination would be as follows:

{ "destination":  
{ "type": "sms",  
   "body": "Blue LED is switched on",  
   "country_code": "+91",  
   "deliver_to": "9100008888",  
   "provider": "twilio",  
   "repeat_freq": 30  
}  
}

To learn how to create rules, actions, and destinations, please refer to Ayla API Reference.

Ayla Rule Expression Syntax (ARES)

ARES is designed to express rules. ARS expects rule expressions and certain action parameters to be written with ARES. The following are basic information about rule expressions:

• Rule expressions evaluate to true or false.
  Example rule expression: DATAPOINT(AC000W000000001, Blue_LED) == 1
• Rule expressions include at least one rule subject.
  Example rule subject: DATAPOINT(AC000W000000001, Blue_LED)
• Rule expressions can include many rule subjects. The one below includes two rule subjects:
  DATAPOINT(AC000W000000001, Blue_LED) == 1 && DATAPOINT(AC000W000000001, Green_LED) == 1
• Rule subject names are uppercase. In the example below, the rule subject name is CONNECTION: CONNECTION(AC000W000000001, online) == 0
• Rule expression space characters are optional.
• A rule subject name is also the rule subject type. It indicates the type of event the rule can evaluate:

• Rule expressions use the following operators:

  Examples:  
        `DATAPOINT(AC000W000000001,Blue_button) == 1` 
        `DATAPOINT(AC000W000000001,Oxygen_Pct) < 90.0`  
        `DATAPOINT(AC000W000000001, Blue_LED) >= 1 && DATAPOINT(AC000W000000001, Green_LED) == 1` 

• ome rule expressions require functions. In the below example, str_equals is the function:
  str_equals(DATAPOINT(AC000W000000001,cmd),'cmd_on')

Functions

This section lists the available functions:

Distance functions:

• distance_km
  Example: distance_km(LOCATION(dsn), LOCATION(uuid))
• distance_miles
  Example: distance_miles(LOCATION(dsn), LOCATION(uuid))
• lat_long
  Example: lat_long(latitude,longitude)

Retrieval functions:

• changed
  Example: changed(DATAPOINT(dsn, property_name))

String functions:

• str_contains
  Example: str_contains(DATAPOINT(dsn,prop_name), 'other string')
• str_equals
  Example: str_equals(DATAPOINT(dsn,prop_name), 'foo')

Time/Date functions:

• current_time
  Example: current_time()
• time
  Examples: time(dsn)
time(uuid)
time('2017-05-26T20:40:22.000Z')

Abstract Rule Expressions

The following list describes abstract rule expressions:

• They contain terms that filter for types of entities (e.g. model, status) rather than specific entities (e.g. device, user).
• They are limited to OEM scope. Only an OEM::Admin can create abstract rules.
• Evaluation does not cause a database query because abstract rules are cached in ARS memory.
• Tags in the expressions refer to field names within the Event JSON object.
• All terms with the ${ } construct must evaluate to true in order for the rule to evaluate to true.

Example: The following abstract rule expression example asserts that the decimal_out property value is LTE 90.0 for any device.