Object Properties ================= Some parameters of notification streams can be constructed using the same macros used to construct alert attributes (see also :func:`nw2functions.alert()`). These macros refers properties of the object that encapsulates the alert and the corresponding device (if any). - :obj:`$alert.deviceId` device Id for the device that triggered alert. This is valid only for fan-out alerts - :obj:`$alert.deviceName` device name, also valid only for the fan-out alerts - :obj:`$alert.componentIndex` component or interface index, valid only for fan-out alerts - :obj:`$alert.componentName` component or interface name, valid only for fan-out alerts - :obj:`$alert.variable` identifier of the corresponding alerting variable, this can be used to construct urls for graphs - :obj:`$alert.inputVariable` identifier of the corresponding input variable, this can be used to construct urls for graphs. This may not be available, for example when alerting rule used temporary variable. - :obj:`$alert.value` the value of the input variable that triggered alert - :obj:`$alert.key` unique deduplication key for the alert - :obj:`$alert.fanout` true or false, indicates whether this is a fan-out alert - :obj:`$alert.tags` a set of strings. For fan-out alerts this is a copy of tags from the input variable that triggered alert. For non fan-out alert this is a common set of tags from all input variable instances that contributed to the alert. - :obj:`$alert.tagsMap` a dictionary where the key is a tag facet and the value is a list of tags in that facet. You can use it to get tags only in specific facet, e.g. `$alert.tagsMap.Role` will return list of roles of the device that triggered the alert. - :obj:`$alert.activeSince` a time stamp (time in milliseconds) when alert entered state "active" - :obj:`$alert.activeSinceStr` time when alert entered state "active" as a string in time zone specified by the main configuration file parameter `network.display.tz` - :obj:`$alert.getTags("facet")` returns tags in given facet (both facet and tag word, e.g. "BGP4Peer.AS1000") - :obj:`$alert.getTagWords("facet")` returns tags in given facet, but unlike :obj:`$alert.getTags("facet")`, returns only tag words. - :obj:`$alert.details` returns a dictionary passed as argument `details` to function :func:`nw2functions.alert()` Properties of the object returned by `$device` (note that some of the properties have two names): - :obj:`$device.name` device name - :obj:`$device.reverse_dns` reverse DNS (PTR) record for the device's management address - :obj:`$device.sys_name` system name defined in SYSTEM MIB - :obj:`$device.location` location defined in the SYSTEM MIB - :obj:`$device.contact` contact name defined in the SYSTEM MIB - :obj:`$device.description` "system description" returned by SYSTEM:sysDescr OID - :obj:`$device.sys_descr` "system description" returned by SYSTEM:sysDescr OID - :obj:`$device.box_descr` "box description": usually model name and number - :obj:`$device.boxdescr` "box description": usually model name and number - :obj:`$device.sw_rev` software revision - :obj:`$device.hostname` host name as defined on the device - :obj:`$device.address` management address of the device - :obj:`$device.deviceaddress` management address of the device - :obj:`$device.tags` set of this device tags Using Velocity Tools in Templates ================================= Overview -------- Velocity Tools are powerful utilities that extend Apache Velocity templates with specialized functionality for common operations like date formatting, mathematical calculations, and number formatting. These tools are automatically available in your templates and provide a rich set of methods to manipulate and format data dynamically. The tools are accessed using the dollar sign (`$`) followed by the tool name and method. For example, `$math.add(5, 3)` uses the MathTool to perform addition. Available Tools --------------- NSG provides several built-in tools: - **Date Tool** (`$date` and `$dateTime`) - Format dates and times, work with time zones, and get timestamps - **Math Tool** (`$math`) - Perform mathematical operations - **Number Tool** (`$number`) - Format and display numbers with custom patterns Date Tool --------- The Date Tool provides comprehensive date and time formatting capabilities, including timezone support and timestamp conversion. Basic Date Formatting ^^^^^^^^^^^^^^^^^^^^^ Format dates using custom patterns: .. code-block:: none Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) *Output: `Thursday 30 September 17:00 PDT`* `$date.format()` is a tool call that takes following arguments: * date/time format * timestamp value. This can be a constant or the value of object attribute, for example you can call `$date.format('format', $alert.activeSince)` * locale (optional) * timezone (optional) Tool `$date.format()` returns date and time passed as second argument, formatted according to the first argument. If locale and timezone are provided, the date/time will be formatted according to the locale and converted to the requested time zone, taking into account possible daylight shift. last two arguments are optional. If you want to pass timezone info, you must also pass locale. Get standard timezone objects by calling `dateTime` tool as shown in the example, it accepts standard timezone names such as `America/Los_Angeles` or `UTC`. Note that this takes care of the daylight savings shift automatically. Supported formats ^^^^^^^^^^^^^^^^^ Here is a non-exhaustive list of date/time formats supported by the Date Tool Combined date and time formats: .. code-block:: none $dateTool.format('default', $testDate) $dateTool.format('full', $testDate) $dateTool.format('long', $testDate) $dateTool.format('medium', $testDate) $dateTool.format('short', $testDate) Gives this in the output: .. code-block:: none 03-Jan-2012 00:00:00 Tuesday, 3 January 2012 00:00:00 o'clock GMT 03 January 2012 00:00:00 GMT 03-Jan-2012 00:00:00 03/01/12 00:00 To get just the date without time, add sufix '_date': .. code-block:: none $dateTool.format('default_date', $testDate) $dateTool.format('full_date', $testDate) $dateTool.format('long_date', $testDate) $dateTool.format('medium_date', $testDate) $dateTool.format('short_date', $testDate) Gives this in the output: .. code-block:: none 03-Jan-2012 Tuesday, 3 January 2012 03 January 2012 03-Jan-2012 03/01/12 To get just the time, add suffix '_time' .. code-block:: none $dateTool.format('default_time', $testDate) $dateTool.format('full_time', $testDate) $dateTool.format('long_time', $testDate) $dateTool.format('medium_time', $testDate) $dateTool.format('short_time', $testDate) Gives this in the output: .. code-block:: none 00:00:00 00:00:00 o'clock GMT 00:00:00 GMT 00:00:00 00:00 Custom formatting is also supported: "YYYY/MM/DD HH:mm:ss" For more details on date/time format patterns, see the `SimpleDateFormat documentation `_. .. list-table:: Date/Time Format Letters :header-rows: 1 :widths: 10 30 15 45 * - Letter - Date or Time Component - Presentation - Examples * - G - Era designator - Text - AD * - y - Year - Year - 1996; 96 * - Y - Week year - Year - 2009; 09 * - M - Month in year (context sensitive) - Month - July; Jul; 07 * - L - Month in year (standalone form) - Month - July; Jul; 07 * - w - Week in year - Number - 27 * - W - Week in month - Number - 2 * - D - Day in year - Number - 189 * - d - Day in month - Number - 10 * - F - Day of week in month - Number - 2 * - E - Day name in week - Text - Tuesday; Tue * - u - Day number of week (1 = Monday, ..., 7 = Sunday) - Number - 1 * - a - Am/pm marker - Text - PM * - H - Hour in day (0-23) - Number - 0 * - k - Hour in day (1-24) - Number - 24 * - K - Hour in am/pm (0-11) - Number - 0 * - h - Hour in am/pm (1-12) - Number - 12 * - m - Minute in hour - Number - 30 * - s - Second in minute - Number - 55 * - S - Millisecond - Number - 978 * - z - Time zone - General time zone - Pacific Standard Time; PST; GMT-08:00 * - Z - Time zone - RFC 822 time zone - -0800 * - X - Time zone - ISO 8601 time zone - -08; -0800; -08:00 Working with Time Zones ^^^^^^^^^^^^^^^^^^^^^^^ Format dates in different time zones: .. code-block:: none ## UTC timezone Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.utc()) ## Specific timezone Date: $date.format('EEEE d MMMM HH:mm z', $testDate, $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) Unix Timestamps ^^^^^^^^^^^^^^^ Tool `$dateTime.timestamp()` returns current time as unix timestamp (in seconds). Tool `$dateTime.timestampMs()` returns timestamp in milliseconds: .. code-block:: none ## Unix timestamp in seconds Current time: $dateTime.timestamp() ## Unix timestamp in milliseconds Current time (ms): $dateTime.timestampMs() you can apply `$date.format()` to the current time if you need to format it: .. code-block:: none Current time: $date.format('EEEE d MMMM HH:mm z', $dateTime.timestamp()) Current time: $date.format('EEEE d MMMM HH:mm z', $dateTime.timestamp(), $dateTime.defaultLocale, $dateTime.get('America/Los_Angeles')) Math Tool --------- The Math Tool enables mathematical calculations directly within your templates [[4]](https://velocity.apache.org/tools/1.4/generic/MathTool.html). Basic Operations ^^^^^^^^^^^^^^^^ Perform arithmetic operations on variables: .. code-block:: none Sum: $math.add($a, $b) Product: $math.mul($a, $b) If `$a = 10` and `$b = 5`, this produces: *Output: `Sum: 15, Product: 50`* Advanced Calculations ^^^^^^^^^^^^^^^^^^^^^ Combine multiple operations for complex calculations: .. code-block:: none ## Calculate tax and total Tax (10%): $math.mul($amount, 0.1) Total: $math.add($amount, $math.mul($amount, 0.1)) Number Tool ----------- The Number Tool provides flexible number formatting capabilities [[1]](https://velocity.apache.org/tools/devel/apidocs/org/apache/velocity/tools/generic/NumberTool.html). Custom Number Formatting ^^^^^^^^^^^^^^^^^^^^^^^^ Format numbers using Java's DecimalFormat patterns: .. code-block:: none Formatted: $number.format('#,##0.00', $value) If `$value = 1234.5678`, this produces: *Output: `Formatted: 1,234.57`* Currency Formatting ^^^^^^^^^^^^^^^^^^^ Format numbers as currency: .. code-block:: none Amount: $number.format('$#,##0.00', $amount) If `$amount = 1234.56`, this produces: *Output: `Amount: $1,234.56`* Best Practices -------------- 1. **Use appropriate tools for data types**: Use the Number Tool for numeric formatting rather than trying to format numbers manually. 2. **Specify time zones explicitly**: When working with dates, always specify the time zone to ensure consistent output across different environments. 3. **Combine tools for complex operations**: Tools work well together - use Math Tool for calculations and Number Tool for formatting the results. 4. **Leverage conditional logic**: Use `#if` statements to show different content based on your data. 5. **Format for your audience**: Choose number and date formats that match your users' expectations and locale. These tools provide the foundation for creating dynamic, data-driven templates that can adapt to different contexts while maintaining consistent formatting and presentation.