GeoEvent Output: Sending a Text Message Notification

[EricIronside]

GeoEvent provides a wide array of outputs, but the Text and Email Message outputs are somewhat unique in that they are sending data directly to a human.  Because of this, it is important to be able to structure these output messages in a manner that is precise and actionable.  This blog post will go through the aspects of creating a meaningful and concise text message output.

Topics in this post:

• Creating a Text Message Output
• Standardprameters
• Advanced Properties
• Global Settings
• Common Errors

The 'Send a Text Message' output is a “fire-and-forget” type of operation. The GeoEvent Server will not contact the specified SMTP server to determine its status, and there is no way for GeoEvent to process acknowledgement or error messages which might be sent from the SMTP server. You cannot assume that because an output incremented its event count that a text message has been successfully delivered or received. The incremented event count only indicates that a message has been succesfully sent to the specified carrier's server for delivery to the specified address (mobile phone number).

Creating a Text Message Output

Start by going to the 'Services | Outputs' page in GeoEvent Manager and pressing the 'Add Output' button.  This will bring up the Output Connectors dialog.  In the search bar, type "text m" and press the 'Select' button on the "Send a Text Message" item.

This brings up the "Creating Output - Send a Text Message" 

Standard prameters

•  Name [Required]

  • The name should describe the output text message.
  • Names should be unique (but don't have to be).
  • You can use spaces and other special characters if you wish.
    • I typically use the original default name and append (or prepend) a descriptive name.
    • I also like to group my input, service, and output names by using group/project/topic names first, then more descriptive names after that.
    • Some examples: 
      • avl-sms-text-out-notification-driver-idle
      • avl-sms-text-out-warning-driver-speeding
      • safety-sms-text-out-urgent-driver-trackgap
      • safety-sms-text-out-warning-driver-outofzone

• Sender's email address [Required]

  • One email address that will be used to send the text message.
  • This email must be a valid email address on the SMTP server (see advanced parameters described below).
  • So long as the email address is valid for that server, you can use any email you wish.
  • You can use event fields to dynamically set the sender's email
    • Enclose the field name containing the sender's email address like this ${FIELD_NAME}.
    • For example, if each event contained a field named "manager_email" then you could dynamically set the value of the sender's email address by setting this property to

• Message [Required]

  • The message body should be plain text
    • text messages can't use rich text or html tags.
    • Anything that looks like a URL might be interpreted as such (this depends on your text messaging app). For me:
      • This works: "https://www.esri.com/en-us/home"
      • This works: "www.esri.com"
      • This does not: "<a href='https://www.esri.com/en-us/home'>Esri</a>"
    • Currently there is no way to embed local application calls in a text message (e.g. "arcgis-survey123://?itemID=123456789abcd1234567890abcd")
      
      • To do this, use the 'Send an Email' output
  • You can use event fields to dynamically set the message
    • Enclose the field name(s) containing the recipient's phone number(s) like this ${FIELD_NAME}.
    • For example, if each event contained fields named "fleet_id", "vehicle_vin", "vehicle_speed", "gps_datetime" then you could dynamically set the value of the message by setting this property to

• Carrier [Required]

  • Choose a carrier from the list of providers.
  • If your carrier is not listed, you can modify this list in the setting section (see the System Settings section below).
  • Please note that each 'Send a Text Message' output can only support a single carrier.
    • If your organization supports multiple carriers, you will need to set up one output for each carrier.
    • After you configure the first text message output, use the 'Copy' button on the 'Outputs' screen to duplicate your output for the other carriers. 

• Recipients [Required]

  • This is a comma separated list of cell phone numbers to send the text message to.
  • You must provide at least one (1) recipient.
  • Using characters other than numerical digits or commas will result in a 'Error occured while sending SMS: No recipient addresses' error.
  • The output is not able to validate the recipient's phone number with the carrier.  GeoEvent will not be able to determine if a phone number is incorrect, disconnected, or not supported by that carrier (see common errors below).
  • You can use event fields to dynamically set the recipient
    • Enclose the field name containing the recipient's phone number(s) like this ${FIELD_NAME}.
    • For example, if each event contained a field named "cell_number" then you could dynamically set the value of the recipients by setting this property to

Advanced Properties

Note, these properties can be set ahead of time by updating the GeoEvent Settings (see the System Settings section below).

• SMTP server host name [Required]
  • The SMTP server to use to send the text messages (Simple Mail Transport Protocol = Email Server)
  • This will typically be your corporate email server (e.g. smtp.companyx.com).
  • If you have problems, or are using an external SMTP email server (like GMail), please see RJ Sunderman's reply to the following post: I Am Not Receiving Any Emails
• SMTP server port number [Required]
  • The port the SMTP server listens on.
  • The default value for SMTP servers are:
    • Using anonymous authentication is 25.
    • For SSL/TLS, the default should usually be 465.
    • Other common SMTP ports are 2525 and 587.
  • You will need to contact your IT administrator to identify the port(s) over which SMTP messages can be sent in your organization. Note also that external ports may be blocked by your firewall, so check with your IT group.
• SMTP authentication mode [Required]
  • Anonymous
    • The email server will send anything so long as the Sender's email is valid on that server.
    • If the Sender's email address is not valid the email will be discarded without error.
  • SSL (Secure Socket Layer) - an earlier version of encryption.
  • TLS (Transport Layer Security) - a later version of encryption that replaced SSL.
• User name [optional, used only with SSL/TLS authentication modes]
  • Enter a username that can be used to authenticate with the SMTP server.
• Password [optional, used only with SSL/TLS authentication modes]
  • Enter the password for the username entered above.

Global Settings

The following GeoEvent Server global settings may be helpful in pre-configuring your SMTP server settings or adding a new text messaging carrier.  If you intend to create several text or email outputs, you should modify these settings before you create your outputs to streamline your configuration.

GeoEvent Server Global Settings: SMTP [Email Server] Settings

GeoEvent Server Global Settings: SMS [Text Messaging] Providers

Common Errors

• "Error occured while sending SMS: Unknown SMTP host: smtp.HOST-NAME.com"
  • Check the host name you are using because the one you provided cannot be found, is not responding, or is not correct.
• "Error occured while sending SMS: Could not connect to SMTP host: smtp.HOST-NAME.com, port: ##"
  • Check the port that your server is monitoring, it may be wrong
    • Port 25 is typical for anonymous authentication
    • Port 465 is typical for SSL/TLS
  • Please note that the host name you are using was found (because it tried the port on that server).
• Sender gets an email response from the carrier that destination is invalid:
  • One or more recipients is invalid or incorrect.
  • Check the phone numbers of the recipients and/or the format of this property value.
• GeoEvent says it sent the message, there are no errors in the GeoEvent Server logs, but the text message was not recieved.
  • Check the Sender's email address and verify it is a valid email address on the SMTP server.
  • Check the phone numbers of the recipients to verify they are correct.
  • Romove any characters from the recipients property that are not digits or a comma (spaces, dashes, etc.)
  • Your firewall may block outbound communication on the configured port (talk to your IT about what ports are allowed/blocked).
  • Your external SMTP provider may require additional settings to allow you to use it from GeoEvent.  For example, please see Hugo Gaignard's reply to the post I Am Not Receiving Any Emails for Google security settings.