Alert Policies

Use an Alert Policy to monitor incoming DataStream values, record an alert when a trigger condition takes effect, and resolve it when the reset condition takes effect. You can also configure a notification for the firing alert.

This guide monitors temperature_a, a numeric Celsius DataStream such as the converted temperature in the Analyzer end-to-end scenario. The example triggers above 80 °C, resets below 75 °C, and uses a 10-second delay in each direction.

For the API requests, use your deployment's base URL, an authorized access token, the target Org ID and the Device ID of the monitored stream. For the SubNode example, use the SubNode's Device ID. Replace all route placeholders and illustrative IDs with your actual resources.

Understand Alert Evaluation

An Alert Policy is an Org-level resource. Its definition, DataStream attachments and events have different roles:

• The policy defines the trigger condition, reset condition, delay and optional notification.
• Attachments select the device/DataStream pairs to monitor. A policy can monitor several streams, and a stream can have several policies.
• An event records a firing alert and its later resolution. A recorded event is separate from successful notification delivery.

Each attached stream is evaluated separately. Attaching two temperature streams does not create an AND condition across them. Calculations that depend on several readings belong in an Analyzer; the policy conditions below compare one incoming numeric value at a time.

Choose the conditions. Put the comparison operator and number in the condition string, without a variable name or unit. For example, use ">80", not "temperature_a > 80":

Setting	Example	Meaning
alertLevel	">80"	A reading above 80 °C starts a trigger wait when no alert is active.
alertResetLevel	"<75"	A reading below 75 °C starts a reset wait when an alert is active.
delay	10	Wait ten seconds before firing or resolving, unless the opposite condition cancels the wait. The default 0 adds no debounce delay.

Supported comparisons use >, >=, <, <=, == or != followed by a number, such as ">80" or "<75". Use separate, non-overlapping trigger and reset conditions. This threshold syntax is not JavaScript and does not combine named inputs with && or ||.

Spaces, negative numbers and decimals such as ">= -5.5" are supported. A leading +, exponent notation (1e3), numbers without a leading digit (.5), strings, booleans and combined AND/OR conditions are unsupported.

Note: A successful save does not validate the condition syntax

Malformed expressions are not rejected by format validation. A policy created with a malformed expression never fires; a malformed expression in a PATCH leaves the previous condition unchanged. Read the saved conditions back and verify evaluation with actual readings.

Note: Readings between the thresholds do not cancel a wait

With this example, 75 °C through 80 °C matches neither condition. Such a reading leaves the current alert or pending wait unchanged.

A reading below 75 °C cancels a pending trigger; a reading above 80 °C cancels a pending reset. Another matching reading does not restart the existing wait. The delay is not proof that every intervening reading remained above or below the threshold, and a lack of later readings is not a cancellation signal.

The following timeline illustrates arrivals and waits, not device sample timestamps or a guaranteed execution time:

The trigger wait can still complete after the 77 °C reading. Likewise, the reset wait can complete after the later 77 °C reading. Continued high readings while the alert is already active do not create a new event for every sample.

Create an Alert Policy

Prepare an existing Celsius stream with recent values. DataStreams explains how to check its value and timestamp.

Create the policy with Create Alert Policy:

POST /api/v1/orgs/{orgId}/alert-policies
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "policyName": "Temperature A high alert",
  "description": "Monitor the converted Celsius temperature",
  "alertLevel": ">80",
  "alertResetLevel": "<75",
  "delay": 10
}

• Required: policyName, alertLevel and alertResetLevel.
• Name: Must be unique among existing policies in the Org.
• Description: Optional, up to 500 characters.
• Delay: A non-negative whole number of seconds.
• Notification: Optional. This request omits it, so you can first verify events without sending a message.

After 201 Created, retain the returned alertPolicyId. Device/DataStream attachments are configured separately. Read the definition with Get Alert Policy:

GET /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Check the result: The saved conditions and delay match the request, and enabled is false. Use the enable/disable action to change that state; do not add enabled to the create or PATCH body.

To find an existing policy, use List Alert Policies. It supports name keyword, pagination and sorting by response field names. Its dataStreamId filter finds policies already attached to a stream.

Attach DataStreams

Bind the policy to the actual device/DataStream pair. The illustrative temperature ID below matches temperature_a in the earlier Analyzer example; replace it with the ID on your device.

Copy the Device ID exactly. Device IDs are case-sensitive in attachments and alert-event filters.

PUT /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}/data-streams
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

[
  {
    "deviceId": "{deviceId}",
    "dataStreamId": "d4444444-4444-4444-8444-444444444444"
  }
]

Caution: This replaces the complete attachment list

Set Attached DataStreams applies the entire desired list. Any existing pair omitted from the request is detached. Sending [] detaches every stream from this policy.

Before adding or removing a pair, read all current attachment pages and construct the full list you intend to keep.

After 200 OK, inspect the returned final list. You can also verify it with List Attached DataStreams:

GET /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}/data-streams?skipCount=0&maxResultCount=20
Authorization: Bearer YOUR_ACCESS_TOKEN

Check the result: The intended device and temperature_a stream are attached. Creating a policy alone does not select a stream to monitor, and attaching a stream does not enable the policy.

Configure Alert Notifications

Add a notification when you want a message requested as the alert fires. Use an existing channel in the same Org. Notifications covers channel setup, templates and delivery results; this section configures only the policy's use of those resources.

Choose one message method:

Method	Fields to provide
Literal message	subject and content.
Existing template	templateId and the variables required by that template. Variable values are strings.

Both methods also use channelIds and recipients. Each recipient has a required target and type (to, cc or bcc); name is optional. Use recipient targets appropriate for the selected channel.

For example, PATCH a literal message for an existing email channel. Replace the illustrative channel ID and recipient with your actual values:

PATCH /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "notification": {
    "channelIds": ["channel_3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "recipients": [
      {"name": "Operations", "target": "operations@example.com", "type": "to"}
    ],
    "subject": "Temperature A alert",
    "content": "A temperature alert has fired. Review the alert event and recent readings."
  }
}

Note: Send the complete notification configuration

Providing a non-null notification replaces the whole object, including its channels and recipients. It does not merge individual fields with the previous configuration. Omitting it or sending notification: null retains the existing configuration. A PATCH containing only notification: null returns 400 EmptyRequest.

Use either the literal-message fields or the template fields. Do not combine templateId / variables with subject / content.

Check the result: After 200 OK, GET the policy and confirm its channel IDs, recipients and message method. A firing event can be recorded even when notification delivery fails, so verify delivery separately in Notifications.

Enable and Disable a Policy

When the definition, attachments and optional notification are ready, call Enable / Disable Alert Policy:

POST /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}:enable
Authorization: Bearer YOUR_ACCESS_TOKEN

1. After 204 No Content, GET the policy and confirm enabled: true.
2. Check that the attached temperature stream continues to report new values.
3. Observe a trigger condition and its delay, then query the resulting event. The enabled state alone is not proof that an alert fired or a message arrived.

To pause evaluation for this policy:

POST /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}:disable
Authorization: Bearer YOUR_ACCESS_TOKEN

Check the result: After 204, GET shows enabled: false. The definition and attachments remain available. Disabling does not itself acknowledge or resolve an existing event.

View Alert Events

Use List Alert Events to inspect the policy and device you are testing:

GET /api/v1/orgs/{orgId}/alert-events?alertPolicyId={alertPolicyId}&deviceId={deviceId}&skipCount=0&maxResultCount=20
Authorization: Bearer YOUR_ACCESS_TOKEN

Optional filters combine with AND:

• status: Use numbers: 0 for Firing, 1 for Acknowledged or 2 for Resolved. For example, status=2 selects resolved events. Manual acknowledgement is unavailable, so status 1 does not occur in this version.
• alertPolicyId / deviceId: Narrow the results to a policy and/or device. Inspect each item's dataStreamId when the policy monitors several streams.
• start / end: ISO 8601 UTC bounds on firedTime; start is inclusive and end is exclusive.
• sorting, skipCount, maxResultCount: Order and page the results. The default order is newest firing time first.

Read the fields together:

Field	What to check
alertEventId	Identifies this alert occurrence.
policyName, alertLevel	Snapshots at firing time; later policy edits do not rewrite them.
deviceId, dataStreamId	Identify the stream for this event.
triggeredValue	Value recorded when the event was created, represented as a string. With a delay, it can differ from the reading that first started the wait.
firedTime	Event firing time in ISO 8601 UTC, rather than the device's original sample timestamp.
resolvedTime, resolvedBy	A resolution time with resolvedBy: null indicates automatic resolution. A null resolvedBy alone does not tell you whether the event is resolved.
acknowledgedTime, acknowledgedBy	Both are null in this version because manual acknowledgement is unavailable.

The status meanings are:

Status	Meaning
0 (Firing)	Active, not yet resolved.
1 (Acknowledged)	Reserved for acknowledgement; does not occur in this version.
2 (Resolved)	Closed automatically after the reset condition and delay. resolvedBy is null.

Note: Event queries do not provide acknowledgement actions

The public alert-event API in this version lists events. It does not provide an acknowledge or manual-resolve operation. The presence of acknowledgement fields or a status filter does not add such an action.

Check the result: Identify the new event by policy, device, stream and firing time. After a reset wait completes, verify the event's resolved state and resolvedTime. Check notification delivery independently.

Update, Delete and Troubleshoot

Update Alert Policy is a PATCH. Omitted fields retain their current values, and an entirely empty request is rejected. For example:

PATCH /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "description": "Temperature monitoring for the converted SubNode signal"
}

After 200 OK, GET the policy and verify the saved fields. PATCH can update an enabled policy, and its updated definition is made available for evaluation. Disable first if you want evaluation paused while changing conditions or attachments. Use the dedicated operations to change enabled state or attachment lists.

To remove a policy, disable it and confirm enabled: false, then use Delete Alert Policy:

DELETE /api/v1/orgs/{orgId}/alert-policies/{alertPolicyId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Check the result: After 204 No Content, GET for that policy returns 404 Not Found. Deleting an enabled policy returns 409 Conflict.

Observation	Start here
No event appears	Check enabled, all attachment pages, the actual temperature stream's recent values, condition syntax and the delay. A saved definition is not proof of successful evaluation.
An event fires after the value drops to 77 °C	Under this example, 77 matches neither condition and does not cancel a pending trigger. It must fall below 75 to cancel that wait.
An alert stays active	Check the reset condition and delay. Another trigger-condition reading cancels a pending reset.
An event exists but no message arrives	Inspect the policy's complete notification configuration and the channel's delivery results. Event creation does not confirm delivery.
400 while creating or updating	Check required fields, delay and the mutually exclusive message methods. A PATCH must include a change.
404 while attaching or configuring notifications	Verify the policy, device/stream pair and Org-owned channel/template IDs.
409	Check for a duplicate policy name, or disable an enabled policy before deleting it.
A previously monitored stream disappears from the attachments	Compare the last full-replacement request with the complete intended list.

After a change, verify the saved definition and attachments, then use new readings to check the next trigger/reset cycle. Keep event verification and message-delivery verification as separate checks.