Writing better notifications

Monday, May 1, 2017

By Alex Lein

Back in the middle of last year, we implemented a new feature in the notifications system to allow for dates and times to be transformed from UTC to the receiving user's local timezone. This week we are expanding on this system to provide even more flexibility to script authors for converting dates, times, and numbers.

Replacement format

When writing a script, the Notification object contains a dictionary where the key matches a specifically formatted pattern in the subject and/or body. That pattern should be formatted as either {name} for dates, or {name:hint} for dates and numbers. Both the name and hint should follow the codified format.

Replacement context hints for dates

One of the new features is the ability for the script author to add a specific context to the dates as they are changed.

Using the following replacements as an example: { "dts": new Date(), "dts:date": new Date(2008,5,4), "position": asset.position.dts }
All dates and times are given as UTC.

This template will replace the {dts} with a time if the value of dts is "today", or the full date and time string if not.
This template will replace the {dts:time} with a time no matter what day it is "today", and {dts:date} will be the specified date from June 2008.
This template will not replace the {dts:time} at all because the key "dts:time" is not in the replacements, but {position} will be replaced.
This template will replace the {dts:iso} as a UTC ISO-8601 format good for computers to parse, and {dts:utc} as the date/time in UTC (instead of the user's chosen timezone) based on the user's preferred format.

Context hints reference for dates

iso: ISO-8601 formatted UTC date string
utc: UTC date string formatted based on receiving user's preferences
date: Date string in local time for the receiving user
time: Time string in local time for the receiving user
datetime: Full date and time string in local time for the receiving user

For all others context hints (including not specified) the date is compared against the receiving user's current local time, and when the dates are the same, a time string is used, otherwise the full date and time.

Replacement context hints for numbers

First off, all numbers in the Notification replacements are converted to double-precision floating point numbers, even if the value given by the script is an integer. Your next consideration is that numbers can mean any number of things, but we've done our best to include all relevant or necessary conversions. And lastly, the system assumes all numbers to be metric until conversion.

Distance

Using the following replacements as an example: { "num": 838345.29 }
All distances are assumed to be given in kilometres (Km).

This template will replace the {num:distance} with the user's preferred measurement system, rounded to one decimal place, a space, then the unit suffix. ie; "838345.3 Km" or "520923.6 mi".
This template will replace the {num:km} with the metric value rounded to one decimal place, and {num:mi} as the US Standard value rounded to one decimal place.

Speed

Using the following replacements as an example: { "num": 45.29 }
All speeds are assumed to be given in kilometres per hour (Km/h).

This template will replace the {num:speed} with the user's preferred measurement system, rounded top the nearest integer value, a space, then the unit suffix. ie; "45.3 Km/h" or "28.1 mph".
This template will replace the {num:kmh} with the metric (Km/h) value rounded to the nearest integer, and {num:mph} as the US Standard (mph) value rounded to the nearest integer.

Temperature

Using the following replacements as an example: { "num": 36.71 }
All temperatures are assumed to be given in degrees Celcius (°C).

This template will replace the {num:temperature} with the user's preferred measurement system, where metric (Celcius) values are rounded to one decimal place, and US Standard (Fahrenheit) values are rounded to the nearest integer. ie: "36.7 °C" or "98 °F".
This template will replace the {num:c} with the metric (Celcius) values are rounded to one decimal place, and {num:f} as the US Standard (Fahrenheit) values are rounded to the nearest degree.

Weight

Using the following replacements as an example: { "num": 99.7185 }
All weights are assumed to be given in kilograms (Kg).

This template will replace the {num:weight} with the user's preferred measurement system, where metric (kilogram) values are rounded to two decimal places, and US Standard (lbs) values are rounded to one decimal place. Ie: "99.72 Kg" or "219.8 lbs".
This template will replace the {num:kg} with the metric (Kg) values are rounded to two decimal places, and {num:lbs} as the US Standard (lbs) values are rounded to one decimal place.

Volume

Using the following replacements as an example: { "num": 12.55 }
All volumes are assumed to be given in litres (L).

This template will replace the {num:volume} with the user's preferred measurement system, where metric (litres) values are rounded to one decimal place, and US Standard/British (gallons/imperial gallons) values are rounded to two decimal places. Ie: "12.6 L" or "3.32 gal" or "2.76 IG".
This template will replace the {num:l} with the metric (litre) values are rounded to two decimal places, {num:gal} as the US Standard (gallon) values are rounded to one decimal place, and {num:ig} as the British (imperial gallon) values are rounded to one decimal place.

Fuel Economy

Using the following replacements as an example: { "num": 4.539 }
All volumes are assumed to be given in litres per 100 kilometers (L/100Km).

This template will replace the {num:fuel} with the user's preferred measurement system, where metric (L/100Km) values are rounded to two decimal places, and US Standard (mpg) values are rounded to one decimal place. Ie: "4.54 L/100Km" or "51.8 mpg".
This template will replace the {num:l100km} with the metric (L/100Km) values are rounded to two decimal places, {num:mpg} as the US Standard (mpg) values are rounded to one decimal place, and {num:mpig} as the British (mpig) values are rounded to one decimal place.

Context hints reference for numbers

distance: Formats the number as a distance in the user's preferred measurement system.
km or kms: Formats the number as a distance in kilometers.
mi or mile or miles: Formats the number as a distance in miles.
speed: Formats the number as a speed in the user's preferred measurement system.
kmh or km-h or kph: Formats the number as a speed in kilometers per hour.
mph or mih: Formats the number as a speed in miles per hour.
temp or temperature: Formats the number as a temperature in the user's preferred measurement system.
c or celsius: Formats the number as a temperature in degrees celsius.
f or fahrenheit: Formats the number as a temperature in degrees fahrenheit.
weight: Formats the number as a weight in the user's preferred measurement system.
kg or kgs: Formats the number as a weight in kilograms.
lb or lbs: Formats the number as a weight in pounds.
volume: Formats the number as a volume in the user's preferred measurement system.
l or litre or litres or liter or liters: Formats the number as a volume in litres.
gal or gals or gallon or gallons: Formats the number as a volume in US (standard) gallons.
ig or igs: Formats the number as a volume in British (imperial) gallons.
fuel or economy: Formats the number as a fuel economy in the user's preferred measurement system.
l100km or l-100km: Formats the number as a fuel economy in litres per 100 kilometers (L/100Km).
mpg: Formats the number as a fuel economy in miles per US (standard) gallon.
mpig: Formats the number as a fuel economy in miles per British (imperial) gallon.

For all others context hints (including not specified) the number will be put into the notification unchanged and with all decimal places.