# Alarm Templating Data
When alarm actions (triggers and notifications) are executed, comprehensive templating data is available through the `options` object and additional context variables. This data enables dynamic alarm message generation and context-aware transformations.
## Available Template Variables
The alarm system provides the following data structure accessible in templates:
### Item Data (`options.item`)
Information about the sensor data that triggered the alarm:
- `source` (string): Data source identifier of the triggering sensor
- `id` (string): Sensor ID that triggered the alarm
- `dimension` (number): Dimension index of the value that triggered the alarm
- `unit` (string): Unit of measurement for the triggering value
- `datetime` (string): Human-readable date and time of the alarm trigger
- `timestamp` (number): Unix timestamp in milliseconds of the alarm trigger
- `value` (any): The actual value that triggered the alarm
- `valuename` (string): Name/label of the dimension that triggered the alarm
### Alarm Configuration (`options.trigger`)
Complete alarm trigger configuration:
- `interval` (number): Interval in milliseconds for alarm repetition
- `time` (object): Time-based trigger configuration
- `value` (number): Time value in milliseconds
- `type` (string): Type of trigger rule
#### Trigger Types (`trigger.type`)
Trigger types determine when an alarm should fire. All condition rule types can also be used as triggers, plus these trigger-only types:
**Change Detection Triggers:**
- `string_change`: Trigger when string value changes from previous value
- `number_change`: Trigger when number value changes from previous value
- `boolean_change`: Trigger when boolean value changes from previous value
**Boolean Edge Triggers:**
- `boolean_rising_edge`: Trigger when boolean changes from false to true
- `boolean_falling_edge`: Trigger when boolean changes from true to false
**Time-based Triggers:**
- `ts_last_value_changed`: Trigger if value hasn't changed within specified time
- `ts_last_value_received`: Trigger if no value received within specified time
**All Condition Rules:** Any rule type from the Condition Data section can also be used as a trigger (string_includes, number_gt, boolean_true, etc.).
#### Example Trigger Configurations
```json
// Value change trigger
{
"type": "number_change"
}
// Boolean edge trigger
{
"type": "boolean_rising_edge"
}
// Time-based trigger with threshold
{
"type": "ts_last_value_changed",
"time": {
"value": 300000
}
}
// Using condition rule as trigger
{
"type": "number_gt"
}
```
### Condition Data (`options.condition`)
Alarm condition configuration (if present):
- `rule` (object): Rule configuration with type-specific properties
- `source` (string): Condition source identifier
- `id` (string): Condition sensor ID
- `type` (string): Condition type
- `dimension` (number): Dimension index for condition evaluation
- `key` (string): Unique condition key identifier
#### Rule Types (`rule.type`)
**String Comparison Rules:**
- `string_includes` / `string_includes_not`: Check if value includes/excludes a substring
- `string` (string): The substring to search for
- `string_starts_with` / `string_starts_with_not`: Check if value starts/doesn't start with text
- `string` (string): The prefix to check for
- `string_ends_with` / `string_ends_with_not`: Check if value ends/doesn't end with text
- `string` (string): The suffix to check for
- `string_equals` / `string_equals_not`: Check if value equals/doesn't equal text
- `string` (string): The exact string to compare
**Number Comparison Rules:**
- `number_equals` / `number_equals_not`: Check if value equals/doesn't equal a number
- `value` (number): The number to compare against
- `number_gt` / `number_lt`: Check if value is greater than/less than a number
- `value` (number): The threshold number
- `number_in_range` / `number_out_of_range`: Check if value is within/outside a range
- `min` (number): Minimum value (inclusive)
- `max` (number): Maximum value (inclusive)
**Boolean Rules:**
- `boolean_true`: Check if value is true
- `boolean_false`: Check if value is false
**Time-based Rules:**
- `ts_last_value_changed`: Trigger if value hasn't changed within time period
- `time.value` (number): Time threshold in milliseconds
- `ts_last_value_received`: Trigger if no value received within time period
- `time.value` (number): Time threshold in milliseconds
**Change Detection Rules (Trigger Only):**
- `string_change`: Trigger when string value changes
- `number_change`: Trigger when number value changes
- `boolean_rising_edge`: Trigger when boolean changes from false to true
- `boolean_falling_edge`: Trigger when boolean changes from true to false
- `boolean_change`: Trigger when boolean value changes
#### Example Rule Configurations
```json
// String contains check
{
"rule": {
"type": "string_includes",
"string": "error"
}
}
// Number range check
{
"rule": {
"type": "number_in_range",
"min": 20.0,
"max": 25.0
}
}
// Boolean state check
{
"rule": {
"type": "boolean_true"
}
}
// Time-based check
{
"rule": {
"type": "ts_last_value_changed",
"time": {
"value": 1800000
}
}
}
```
### Action Configuration (`options.action`)
Action execution details:
- `templateType` (string): Template engine type ("VTL" for Velocity, "JP" for JSONPath)
- `payload` (string): Template payload string
- `topic` (string): Action topic/subject
- `target` (string): Action target (e.g., phone number, email address)
- `type` (string): Actuator type (e.g., "telegram", "email", "webhook")
- `actionId` (string): Unique action identifier
- `label` (string): Human-readable action label
- `extra` (object): Additional action-specific configuration
- `supportedTypes` (array): Supported data types for this action
### User Data (`options.user`)
Information about the user being notified:
- Complete user object in JSON format with user details and permissions
- `uid` (string): User unique identifier
- `name` (string): User display name
- `email` (string): User email address
- `session` (string): User session identifier
- `data` (object): Custom user data
- `roles` (array): User roles and permissions
- `permissions` (object): Detailed access permissions
- `featurePermissions` (object): Feature-specific permissions
### Time Range (`options.start`, `options.end`)
- `start` (number): Unix timestamp of when the alarm was last sent
- `end` (number): Unix timestamp of the current alarm trigger
### Data Context Variables
Additional variables available in templates:
#### Data Object (`$data`)
- `name` (string): Sensor display name
- `id` (string): Sensor ID
- `source` (string): Data source
- `meta` (object): Sensor metadata
- `values` (array): Array of sensor values
- `value` (array): Array of dimension values
- `date` (number): Timestamp of the value
- `valueTypes` (array): Array of value type definitions
- `name` (string): Dimension name
- `unit` (string): Dimension unit
- `type` (string): OpenWare data type
#### Datasets Array (`$datasets`)
Array containing all available data items, including historical and current values.
## Template Engine Support
### Velocity Template Language (VTL)
When `templateType` is set to "VTL", you can use Velocity syntax:
**Available Tools:**
- `$datetool`: Date formatting utilities
- `$esc`: String escaping utilities
**Variable Access:**
- `$options.item.source` - Sensor source
- `$options.item.value` - Triggering value
- `$options.item.datetime` - Formatted date/time
- `$options.user.name` - User name
- `$data.name` - Sensor name
- `$data.values[0].value[$options.item.dimension]` - Current value at specific dimension
- `$data.valueTypes[$options.item.dimension].unit` - Unit for specific dimension
### JSONPath Templates (JP)
When `templateType` is not specified or set to "JP", use JSONPath syntax:
**Variable Access:**
- `{{#$.options.item.source#}}` - Sensor source
- `{{#$.options.item.value#}}` - Triggering value
- `{{#$.options.user.name#}}` - User name
- `{{#$.data.name#}}` - Sensor name
## Example Alarm Configuration
```json
{
"trigger": {
"interval": 0,
"time": {
"value": 1800000
},
"type": "ts_last_value_changed"
},
"condition": {
"rule": {
"type": "boolean_true"
},
"source": "home_garage",
"id": "binary_sensor",
"type": "rule",
"dimension": 0,
"key": "bdbecdc3-bfd8-4d99-9f64-de927d6d52b9"
},
"action": {
"templateType": "VTL",
"payload": "Der Alarm für den Wert \"$data.name - $options.item.valuename\" wurde um $options.item.datetime ausgelöst.\n\nDer Wert lag bei: $data.values[0].value[$options.item.dimension] $data.valueTypes[$options.item.dimension].unit\n",
"topic": "openINCBot",
"target": "CHATID",
"type": "telegram"
},
"item_source": "home_garage",
"item_id": "binary_sensor",
"item_dimension": 0
}
```
## Example Usage in Template Transformer
```json
{
"action": "de.openinc.opentransformations.TemplateTransformer",
"params": {
"template": {
"id": "alarm_notification",
"source": "alerts",
"name": "Alarm: {{item.source}}/{{item.id}}",
"meta": {
"triggered_by": "{{item.valuename}}",
"trigger_value": "{{item.value}}",
"trigger_time": "{{item.datetime}}",
"user_notified": "{{user.name}}",
"alarm_type": "{{trigger.type}}",
"action_type": "{{action.type}}"
},
"valueTypes": [
{
"name": "alarm_severity",
"unit": "level",
"type": "de.openinc.model.data.OpenWareString"
},
{
"name": "trigger_value",
"unit": "{{item.unit}}",
"type": "de.openinc.model.data.OpenWareNumber"
}
]
}
}
}
```
## Advanced Template Examples
### Velocity Template (VTL) Examples
```velocity
## Simple notification
Alert: $data.name value changed to $options.item.value $options.item.unit at $options.item.datetime
## Conditional formatting
#if($options.item.value > 100)
HIGH: $data.name exceeded threshold!
#else
Normal: $data.name is within range.
#end
## Date formatting
Triggered: $datetool.format('yyyy-MM-dd HH:mm:ss', $options.item.datetime)
## User-specific messages
Hello $options.user.name, your sensor "$data.name" requires attention.
```
### JSONPath Template Examples
```json
{
"message": "Alert: {{#$.data.name#}} value is {{#$.options.item.value#}}",
"timestamp": "{{#$.options.item.timestamp#}}",
"user": "{{#$.options.user.name#}}"
}
```
## Integration with Transformation Operations
Alarm templating data is automatically available when transformation operations are invoked as part of alarm actions. This enables:
- **Dynamic alarm message generation** based on sensor data and user context
- **Context-aware data transformations** using current and historical values
- **User-specific alarm formatting** based on permissions and preferences
- **Multi-dimensional data analysis** across different sensor dimensions
- **Historical alarm data analysis** using the datasets array
- **Conditional alarm processing** based on trigger types and conditions
## ActuatorAdapter Integration
The `ActuatorAdapter` class provides the templating infrastructure:
- **Template Processing**: Handles both VTL and JSONPath template engines
- **Data Context Building**: Assembles complete data context for templates
- **Asynchronous Execution**: Processes templates asynchronously for performance
- **Tool Integration**: Provides date and escape tools for VTL templates
- **Fetch Data Support**: Can fetch additional data via transformation pipelines