Subscription-Based Rules and Notifications

OEM users can create OEM-wide subscription-based rules that meet the needs of end-users. The notifications created using subscription-based rules are standard notifications that are disabled by default, and end-users can opt-in or opt-out as needed.

Using Subscription-Based Rules

As an OEM user, you can create subscription-based Rules and Actions and associate them together. The biggest advantage with Subscription-based Rules is that you can create a single rule (e.g. oem-model wide rule) and associate multiple devices to it, instead of creating a rule per device. Devices can be subscribed to the Rules (created by the OEM admin) by associating their Destination with subscription-based Actions.

Please note, that subscription Action cannot be associated with a non-subscription rule, and vice versa. OEM users can create subscription-based rules at the OEM-model level, while end-users can create subscription-based rules at the device level for the devices they own.

Create Subscription-Based Rule:

The following cURL example shows how to create a subscription-based rule:

curl --request POST \
     --url https://rulesservice-dev.aylanetworks.com/rulesservice/v1/rules.json \
     --header 'Authorization: auth_token 5f3075aexxxxxxxxxxf9c2178c' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "rule": {
    "action_ids": [],
    "description": "Rule Description",
    "expression": "DATAPOINT(VDxxxxxxxxx202,integer_input_tp)==10",
    "is_subscription": "true",
    "name": "TestRule_2025"
  }
}
'

Please ensure the is_subscription parameter is set to true to create a subscription-based rule.

The following is an example response to the preceding cURL request:

{
  "rule": {
    "rule_uuid": "123456789",
    "name": "TestRule_2025",
    "description": "Rule Description",
    "expression": "DATAPOINT(VDb2xxxxxxxx202,integer_input_tp)==10",
    "is_enabled": true,
    "is_abstract": false,
    "is_subscription": true,
    "is_template": false,
    "action_ids": [],
    "parameters": {},
    "user_uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2025-01-22T10:28:13.325Z",
    "updated_at": "2025-01-22T10:28:13.325Z",
    "created_by": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "updated_by": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "tags": "subscription",
    "facility_uuid": ""
  }
}

Create Subscription Action:

The following cURL example shows how to create a subscription action:

curl --request POST \
     --url https://rulesservice-dev.aylanetworks.com/rulesservice/v1/actions.json \
     --header 'Authorization: auth_token 07715cbc06ee4c40950a2f934af201a8' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "action": {
    "name": "SubscriptionExample1",
    "type": "SUBSCRIPTION",
    "rule_ids": [
      "123456789"
    ],
    "destination_ids": [
      "987654321"
    ]
  }
}
'

The following is an example response to the preceding cURL request:

{
  "action": {
    "action_uuid": "1122334455",
    "name": "SubscriptionExample",
    "user_uuid": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "SUBSCRIPTION",
    "is_abstract": false,
    "parameters": {
      "ams_message_body": "{{{dpl_event}}}"
    },
    "rule_ids": [
      "123456789"
    ],
    "created_at": "2025-01-22T17:39:58.371Z",
    "updated_at": "2025-01-22T17:39:58.371Z",
    "created_by": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "updated_by": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "destination_ids": [
      "987654321"
    ]
  }
}

Please note the following parameters in the cURL example:

• type - Please ensure you specify the action type as "SUBSCRIPTION".
• rule_ids - You can use this parameter to link rules to the action you are creating. Alternatively, you can associate actions with rules while creating the rule.
• destination_ids - Using this parameter, you link a destination to the action that you are creating. The following example shows how to create a destination.

Create Destination:

The following cURL example shows how to create a destination:

curl --request POST \
     --url https://message-dev.aylanetworks.com/messageservice/v1/destinations.json \
     --header 'Authorization: auth_token 07715cbc06ee4c40950a2f934af201a8' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "destination": {
    "type": "email",
    "body": "Destination for subscription-based rule",
    "message_template_id": "Base_xxxx_template6OF",
    "deliver_to": "[email protected]",
    "contact_id": "xxxxxxxxxxx",
    "title": "Messsage Title",
    "provider": "smtp",
    "user_message": "User Message",
    "user_name": "Methew Hedan",
    "repeat_freq": 30
  }
}
'

The following is an example response to the preceding cURL request:

{
  "destination": {
    "uuid": "987654321",
    "body": "Destination for subscription-based rule",
    "deliver_to": "[email protected]",
    "title": "Message Title",
    "message_template_id": "Base_xxxx_template6OF",
    "oem_id": "xxxxxxx",
    "provider": "smtp",
    "rule_uuid": null,
    "action_uuid": null,
    "dsn": null,
    "user_uuid": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "user_message": "User Message",
    "user_name": "Methew Hedan",
    "repeat_freq": 30,
    "created_at": "2025-01-22T17:29:44Z",
    "updated_at": "2025-01-22T17:29:44Z",
    "created_by": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "updated_by": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "email",
    "contact_id": null,
    "facility_uuid": ""
  }
}

Please note, that the preceding example creates a single destination. You can also create multiple destinations using the Create destinations in bulk API.

Use Cases for the Subscription-based Rules/Notifications

• Preconfigured Alerts/Notifications

  OEM users can preconfigure Alerts/Notifications for end-users to subscribe from the mobile app. For example, for low-battery notifications, you can offer three levels of alerts for end users to choose from: 30%, 20% (default), or 10%. End-users can either keep the default setting of 20% or change it to 30% or 10%. To achieve this, you would have to create 3 Subscription-based Rules - 1 each for 30%, 20%, and 10% battery level. To these Rules, you must associate the desired Subscription-based Action (e.g. push notification). In the app, based on the option chosen by the user, the Destination must be associated with the respective Action.

• Multi-Destination Notifications

  OEM users and end-users can create notifications associated with multiple Destinations belonging to multiple end-users. These destinations are editable without needing to modify the associated rule or action.
  • Example Use Case for Multi-Destination Notifications:
    A commercial water dispenser manufacturing OEM wants to create notifications where 25-30 push notifications or emails are triggered for each event. For devices like water dispensers installed in offices or other commercial setups, they want up to 30 different users to be notified for each notification.

• Condition-Based Destinations

  OEM users can create rules based on conditions outside of device properties (i.e., not based on any device properties) so that device data is sent to a URL/endpoint only for devices that match the conditions (e.g., user opt-ins or geographic region). For example, if you want to take some specific action only if the end-user provides consent, you could achieve that by creating a Subscription-based Rule and Action (such as URL forward Action) and associating the Destinations of customers who have provided consent to that Action.

API reference

The following links provide more information on APIs used to create rules, actions, and destinations:

• Create subscription-based rule
  Please refer the Create Rule API document to know how to create a subscription-based rule.
• Create subscription action
  Please refer the Create Action API document to know how to create a subscription action.
• Create Destination
  Please refer the Create Desctination API document to know how to create a destination.
• Create Destinations in Bulk
  Please refer the Create Destinations in Bulk API document to know how to create destinations in bulk.