Acknowledging Notifications Via Email

You can acknowledge any notification by sending a reply email back to the GNS. This method of acknowledgment is primarily used when replying to an email message sent by the GNS, but can also be used to acknowledge pager and voice notifications.

Email acknowledgment requires some additional system configuration, including:

• Configuration of a POP server or a Graph API server. See Incoming Email below.
• Configuration of the GNSPIN security event to give access to view and edit PIN and email addresses. See the GNS security reference for more information.
• Configuration of users who are permitted to send acknowledgment emails. See Configuring a PIN for more information.

The incoming acknowledgment email must contain both the acknowledgment code (Ack ID), which is provided in the original notification, and a user PIN, which is configured on the GNS PIN Manager. See Acknowledgment Reply Format (below) for information about the format of the acknowledgment email.

If the acknowledgment email is successful, you will receive a reply email indicating that the acknowledgment succeeded. If the acknowledgment failed you will receive a reply email indicating the reason for failure.

Acknowledging Email Notifications Via SMS

In addition to acknowledging by email, you can acknowledge an SMTP email notification by SMS. SMS acknowledgment uses the same methodology as email acknowledgment by sending the message via an SMS gateway address, for example, number@txt.att.net or number@vtext.com, to the incoming email sever on the GNS. See other SMS notes below.

See the following subsections for more information:

• Incoming Email
• Acknowledgment Reply Format
• Acknowledgment Email Failure
• Acknowledgment Email Logging

Incoming Email

Email (and SMS) acknowledgment requires the configuration of an incoming POP3 server or a Graph API server, with a dedicated unique email account, username, and password for each GNS. The GNS assumes complete control over the email account; no other GNS should have access to the account, even if it is on the same domain. It is acceptable to share an email server, as long as each GNS has a unique email account.

Keywords specifying the POP and Graph API parameters must be configured in the GNS configuration file. The GNS Configuration Tester utility (GNSConfig.exe) is provided for setting up this section of the configuration file so that the parameters can be encrypted and the sending and retrieval of email can be tested. See GNS Configuration Tester Utility for more information.

GNS Configuration File Keywords

The Gns.cfg keywords that must be configured to enable incoming mail are listed in the following table. Use the GNS Configuration utility to configure the keywords.

Basic authorization mode	OR	OAuth authorization mode
See POP3 Mail Keywords: POP3_HOST POP3_PASSWORD POP3_PORT POP3_RECEIVE_TIMEOUT POP3_TLS_METHOD POP3_USERNAME See Shared Mail Settings Keywords: EMAIL_ADDRESS EMAIL_AUTH_MODE EMAIL_PASSWORD EMAIL_POLLING_RATE EMAIL_RETAIN_COUNT EMAIL_USERNAME		See Graph API Keywords: EMAIL_OAUTH_AUTHORITY EMAIL_OAUTH_CLIENT_ID EMAIL_OAUTH_CLIENT_SECRET EMAIL_OAUTH_TENANT EMAIL_OAUTH_TYPE GRAPH_RESPONSE_TIMEOUT See Shared Mail Settings Keywords: EMAIL_ADDRESS EMAIL_AUTH_MODE EMAIL_POLLING_RATE EMAIL_RETAIN_COUNT

SSL Encryption and Certificates for Basic Authorization Mode

The POP3_TLS_METHOD keyword indicates the encryption method used for the POP server.

There are three options; specify one or select one from the drop-down menu, if using the GNS Configuration Tester:

Method	Description	Preferred Port
NONE	Clear text, no encryption.	110
SSL/TLS	The entire transaction is encrypted from beginning to end. This is the default option.	995
STARTTLS	The initial connection is not encrypted, but after connection the remainder of the transaction is encrypted.	110

The decision about which port to use and which encryption method to choose should be made by your network administrator.

POP3 servers usually listen on well-known port 110. If using NONE or STARTTLS encryption use port 110; otherwise use port 995.

To Install a Self-Signed Certificate

If using a self-signed certificate, install the Root Certificate Authority by performing the following steps:

1. Open the Microsoft Management Console. Click Start > Run.…
2. Type mmc.exe. Click OK.
3. On the File menu, select Add/Remove Snap-in.…
4. Select Certificates in the left-hand pane and click Add >.
5. Select Computer account and click Next >.
6. Select Local computer and click Finish.
7. Click OK.
8. Expand the Certificates node.
9. Expand the Trusted Root Certification Authorities node.
10. Right-click Certificates, select All Tasks > Import.…
11. Follow the Certificate Import Wizard to import your certificate.

Disabling Email Acknowledgment

Email (and SMS) acknowledgment of notifications can be disabled on a per service basis by disabling the incoming server:

• For Basic authorization — Comment out the POP3_HOST keyword in the Gns.cfg or remove the POP Server name in the GNS Configuration utility
• For OAUTH2 authorization — Comment out the EMAIL_OAUTH_AUTHORITY keyword in the Gns.cfg or remove the Authority URI in the GNS Configuration utility

Acknowledgment Reply Format

Email (and SMS) acknowledgment requires that the following items must be included in the body of the reply email:

• The Ack ID provided by the GNS in the original notification
• The PIN associated with the username and email address for the recipient. The system uses the PIN and the email address of the sender to identify the user to perform the acknowledgment. See Configuring a PIN more information about users and PINs.

The Ack ID will be automatically included in the original notification and must be included in the reply email. When replying to an email notification, the Ack ID is included in the reply if your email client is configured to do so.

The Ack ID must be in the format: Ack: ####   -or-   Ack #### where #### is the Ack ID.

The PIN must be in the format: Pin: ####   -or-   Pin #### where #### is the PIN.

Email Examples

The following examples show a High Alarm Notification email, an Acknowledgment email, and a Successful Acknowledgment Reply email from the GNS.

High Alarm Notification Email sent by the GNS		Acknowledgment Email sent by Recipient		Successful Acknowledgment Reply sent by the GNS (The PIN is obscured in the reply.)

Additional SMS Notes Related to Replies

SMS gateway providers may handle email replies differently. You may need to type both the Ack ID and PIN in the above format and test how your SMS gateway provider handles replies.

Some SMS gateway providers limit messages to 160 characters. Others do not. Using tokens to compose your outgoing notification message may increase the size of the reply message beyond the 160 character limit. Since the Ack ID is appended to the end of the message, it may be truncated.

Some SMS gateway providers send email replies via the email address tied to the provider's account. You will need to add that email address to the GNS PIN Manager list and test how your provider handles email replies.

Acknowledgment Email Failure

If the acknowledgment email is unsuccessful for any reason, you will receive an email indicating this, and the reason. The reasons are explained in the following table.

Failure Reason	Explanation
Acknowledgment code was not found.	The notification indicated by the Ack ID in the acknowledgment email was already acknowledged by another method or it never existed.
Security denied.	The user does not have permission to acknowledge the event associated with the Acknowledgment ID. You must have at least Level 3 authorization (Add) for the GNS service’s QUEUE event to acknowledge a notification. See GNS Security Reference for more information.
Email address or PIN is incorrect.	The system could not map the recipient's email address and PIN pairing to a username. See Configuring a PIN for more information.
PIN is not in message.	The string "Pin: ####" or "Pin ####" was not found in the acknowledgment email message.
Acknowledgment code not in message.	The string "Ack: ####" or "Ack ####" was not found in the acknowledgment email message.
The email address has been locked out.	The recipient's email address has been locked out because the number of email address and PIN combination attempts has exceeded the number configured for the PIN_LOCKOUT_MAX_ATTEMPTS keyword. See Email Lockout for more information about this security feature.

Acknowledgment Email Logging

Both successful and unsuccessful acknowledgment emails are logged as events in the configured ELS, if "CONTROL" is enabled for the LOGMASK_ELS keyword in the Gns.cfg file. The events will be logged to the service log file if "PROG_STAT" is enabled for the LOGMASK_FILE keyword. See GNS Configuration File Keywords for more information about these keywords.

In the ELS, the Event Type is O for Operational and the Category is GNS for both the "Email Sent" and "Email Ack received" events. The details for the "Email Ack received" event indicate the time the email acknowledgment was received, the Ack ID, the User ID, and the From address.