Destinations & Destination Lists

Destinations are the endpoints for messages sent via “Alarm Actions”. These endpoints are typically various methods of connecting with human recipients, but API calls to other software programs is also an option. The “Destination” tab for each “Group” is like a address book, but since each destination is a single endpoint an individual human recipient may have multiple entries to list; email, cell phone, and text.

It is typical for alarm messages to be sent to multiple destinations. Destinations Lists allow you to create groups like “Field Techs”, “2nd Shift”, or “Office staff”. These groups are then selected from the drop-down-menu of the Alarm and/or Restore Actions. A Destination can be assigned to multiple lists.

Creating Destination Lists

Add List - The + Add List button at the top of the left-hand panel, under the Destination List tab, is where you create and name a new list. You may also choose to activate the list now.

Add List Step - The + Add List Step button at the top of the right-hand panel allows you to add Destinations to a list (new or old). The only requirements to adding a List Step are, select the Destination from the drop-down-menu and click Save changes. Optionally you may want to customize the Message Template. For more information on see Message Templates and Message Template Tags.

Managing Destination Lists

When an employee is added, promoted or leaves the company, this requires changes to potentially hundreds of alarms. Destination Lists allow you to make that change in one place. Add or remove a Destination from the List Step, save the changes and the change will be reflected on all the alarms using that Destination List.

Editing Destination Lists - The pencil and trash can icons under the Destination Lists' Edit column allow users, with adequate privileges, to change the name, active/inactive status or delete a Destination list.

Editing List Steps - The pencil and trash can icons under the List Steps' Edit column allow users, with adequate privileges, to swap Destinations, edit Message Templates, or delete the List Steps.

The Message Template allows a user with adequate privileges, to customize the message assigned to each List Step (Destination) using plain text and Message Template tags. The Default message templates are tailored to the Destination Type, making the default SMS messages shorter than email. You can also choose to give more or different information to some Destinations (recipients). Message Template Tags allow the message to contain current field values, device status, system info, meta data, even a Google maps link with the units location.

Default SMS Message Template

Default email Message Template

Customize an email Message Template by adding your own Subject text or tags followed by the special character “|”. Text and tags before the “|” will be formatted as the subject line, everything after the “|” will be formatted as the body of the email.

Example: [SOURCENAME] [GROUPNAME] | [ACTIONMESSAGE] [USTIME] [GPSLINK]

By default, the email sender will be {serial}@eze.io, where {serial} is the serial number of the ezeio controller generating the email. In cases where the email is sent to some automated system that only accept specific senders, the email sender can be customized by using the Token field in the destination setting.

If the token ends with an at (@) character, the text before the at-character will be used as the sender.

Example : If the token is set to marvin@, the sender address will be marvin@eze.io. The domain cannot be customized.

The token supports message tags, so [EZENAME]@ will result in a sender address using the name of the ezeio. Please be aware that the resulting address must conform to valid email addresses (https://datatracker.ietf.org/doc/html/rfc2822)

By default the system will automatically add a short footer with the serial number to email and SMS messages, and a preamble to voice messages. You can eliminate this by adding a caret (^) as the very last character in the message template.

When using the POST destination, the message will be formatted in JSON as follows (whitespace added for readability):

{
  "time": "2022-06-11T16:05:42Z",
  "subject": "ALARM Alarm name",
  "eventid": 90,
  "type": "ALARM",
  "source": "SEND",
  "sourceid": 1,
  "sourceindex": 1,
  "sourcename": "Alarm name",
  "actionname": "This is the action name",
  "param1": "0.000000",
  "param2": "0.000000",
  "param3": "0.000000",
  "param4": "0.000000",
  "message": "The message body from the action",
  "text": "",
  "meta": {
    "serial": "BAA-999",
    "group": "55",
    "accountgroupid": "2",
    "name": "Name of controller",
    "note": "Text from the note field",
    "tzofs": "0"
  },
  "adc": {
    "1": 2,
    "2": 1,
    "3": 2,
    "4": 279,
    "5": 5232,
    "6": 2,
    "7": 16960,
    "8": 2,
    "Vin": 12350,
    "Vbat": 12268,
    "V5": 5061
  },
  "out": {
    "1": 0,
    "2": 100,
    "3": 0,
    "4": 0
  },
  "pos": {
    "x": 0,
    "y": 0,
    "z": 0,
    "signal": 0
  },
  "fields": {
    "1": {
      "name": "Field 1",
      "unit": "",
      "assettag": [],
      "raw": 9659017,
      "value": "9,659,017"
    },
    "2": {
      "name": "Field 2",
      "unit": "",
      "assettag": [],
      "raw": 17,
      "value": "17"
    }
  }
}

Additionally, a “X-Hash” header is added to the message. The X-Hash is calculated as a SHA1 hash of the message payload text with the destination token appended at the end. This may be useful to validate the authenticity of the message.