NOTIFY command

Concept Information

Send email notifications from Analytics

Submits an outgoing email notification message to an SMTP mail server to be relayed to recipients.

Syntax

Authenticated command syntax

NOTIFY SMTP SMTPUSER SMTP_account_name PORT port_number <ENABLESSL> USER sender_email PASSWORD encrypted_password MAILBOX SMTP_server_name ADDRESS recipient_email <CC cc_recipient_email> <BCC bcc_recipient_email> SUBJECT subject_line MESSAGE message_text <ATTACHMENT file_path>

Non-authenticated command syntax

Note

This older version of the NOTIFY command is intended for use with local mail systems, or SMTP mail servers that do not require authentication. It does not work with modern email systems that typically require authentication.

NOTIFY USER sender_email <PASSWORD encrypted_password> MAILBOX SMTP_server_name ADDRESS recipient_email <CC cc_recipient_email> <BCC bcc_recipient_email> SUBJECT subject_line MESSAGE message_text <ATTACHMENT file_path>

Parameters

Name Description
SMTP

Specifies making an authenticated submission to an SMTP server (Simple Mail Transfer Protocol server).

  • Specify SMTP your SMTP server requires authenticated connections

  • Do not specify SMTP you are using an open SMTP server and connecting using port 25, or a local mail system that does not require authentication

Note

Virtually all modern email systems using SMTP require authentication.

You must specify SMTP to enable the following parameters:

  • SMTPUSER

  • PORT

  • ENABLESSL

SMTPUSER SMTP_account_name

The name of the user account to authenticate against and access the SMTP server.

If you omit SMTPUSER, the sender email address specified by USER is used to access a local mail system, or an SMTP mail server that does not require authentication.
PORT port_number

The port number to use to access the SMTP server.

You may need to contact your IT department to find out which port you should use. Common port numbers for SMTP servers are:

  • 587
  • 2525
  • 465

You must use PORT if you use SMTPUSER. If you omit SMTPUSER you can omit PORT and the default port 25 is used.

ENABLESSL

optional

Specifies accessing the SMTP server using a secure SMTP/SSL connection.

You may need to contact your IT department to find out if your SMTP server requires an SSL connection. Or send test emails with and without ENABLESSL specified.
USER sender_email

Defines a sender email address for the email notifications sent via the SMTP server.

Note

Depending on how your SMTP server is configured, USER and SMTPUSER may or may not be the same account.

PASSWORD encrypted_password

The user account password for the SMTP server. The password must be provided as an encrypted string.

For more information, see Generating an encrypted password.

A password may not be required to access a local mail system, or an SMTP mail server that does not require authentication.
MAILBOX SMTP_server_name

The domain name of the SMTP server to use to send the email message. For example:

MAILBOX "smtp.example.com"
ADDRESS recipient_email

The email address of one or more recipients.

Separate multiple email addresses with a comma. Enter a maximum of 1020 characters.
CC cc_recipient_email

optional

The email address of one or more carbon copy recipients.

Separate multiple email addresses with a comma. Enter a maximum of 1000 characters.
BCC bcc_recipient_email

optional

The email address of one or more blind carbon copy recipients.

Separate multiple email addresses with a comma.
SUBJECT subject_line The subject line of the email message.
MESSAGE message_text

The body text of the email message.

The message is plain text and does not support HTML. If you want to insert a line break in your message, use two carat characters: ^^
ATTACHMENT file_path

optional

The path and file name of one or more attachments.

You do not have to specify a path if the file is located in the same folder as the Analytics project.

Enclose the path and file name in quotation marks. Specify multiple attachments by entering a comma-separated list of files for file_path:

ATTACHMENT "result1.csv,result2.csv"

Note

In a comma-separated list, make sure there are no spaces after the commas.

Examples

Sending an error report email

Note

Authenticated command syntax.

You are running a script, and you want to send a notification email if the script fails. Using NOTIFY, you define the email message and include two attachments:

  • the log file
  • a .fil file containing recorded errors
NOTIFY SMTP SMTPUSER "mail_admin@example.com" PORT 587 ENABLESSL USER "support@company.com" PASSWORD "9QZC2524830864..." MAILBOX "smtp.company.com" ADDRESS "script_admin@company.com" SUBJECT "Error Report" MESSAGE "Failed to process script. Details attached." ATTACHMENT "Errors.fil,ACL_Demo.log"

Sending an error report email

Note

Non-authenticated command syntax.

You are running a script, and you want to send a notification email if the script fails. Using NOTIFY, you define the email message and include two attachments:

  • the log file
  • a .fil file containing recorded errors
NOTIFY USER "support@company.com" MAILBOX "mail.company.com" ADDRESS "script_admin@company.com" SUBJECT "Error Report" MESSAGE "Failed to process script. Details attached." ATTACHMENT "Errors.fil,ACL_Demo.log"

Remarks

Recipients and attachments

You can use the NOTIFY command to send email notification messages to one or more recipients. Messages can include attached data files and Analytics projects.

A common use of the NOTIFY command is to alert the appropriate personnel when a script fails unexpectedly.

Compatible SMTP servers

The NOTIFY command can be used with any mail server that supports SMTP (Simple Mail Transfer Protocol), and should work with a wide range of SMTP servers requiring authenticated connections. However, it does not work with all SMTP servers or services. For example, NOTIFY does not work with Gmail. For third-party apps to connect to a Google account requires a security configuration beyond the user name and password supported by NOTIFY.

In general, be aware that successfully using NOTIFY to submit outgoing emails to an SMTP server requires a compatible configuration on the Analytics side, and also on the SMTP server side. If NOTIFY is failing to connect and successfully send emails, work with your IT department to make sure a compatible connection configuration exists between Analytics and the server.

Generating an encrypted password

Note

Analytics supports a maximum length of 30 characters when specifying or entering a server profile password, a database profile password, or a mail server password. Specifying a password value that exceeds the length results in a truncated password and a connection failure.

You need to provide an encrypted password value with the PASSWORD parameter in the NOTIFY command. To appropriately encrypt a password for use with NOTIFY, you must enter the password in the Notify dialog box in the Analytics user interface.

  1. Optional. In Analytics, in the command line, enter SET NOTIFYRETRYATTEMPTS TO 0

    Temporarily turning off NOTIFY retry attempts will speed up generating the encrypted password.

  2. From the Analytics main menu, select Tools > Notify by Email.

  3. In the Notify dialog box, complete the required fields, and any optional fields as needed:

    Sender sender_email Required
    Password

    The user account password, in clear text, for the SMTP server.

    Note

    If the password exceeds 30 characters, the NOTIFY command will fail.

    		 Required
    Mailbox Path SMTP_server_name Required
    To recipient_email Required
    Cc cc_recipient_email Optional
    Bcc bcc_recipient_email Optional
    Subject subject_line Required
    Text message_text Required
    Attachment file_path Optional

  4. Click OK.

    If you are attempting to connect to an SMTP server that requires authentication, the connection attempt will fail (as expected), even if the NOTIFY command appears successful.

  5. Copy the NOTIFY command from the log and paste it into a script.

    The NOTIFY command now includes an encrypted value for PASSWORD.

  6. In the script, add the following parameters to the copied NOTIFY command and provide appropriate parameter values.

    You can insert the parameters immediately after the NOTIFY keyword.

    • SMTP

    • SMTPUSER SMTP_account_name

    • PORT port_number

    • ENABLESSL (if required)

  7. If you previously set the number of NOTIFY retry attempts to 0 , enter SET NOTIFYRETRYATTEMPTS TO 5 in the command line.

    If you originally had a different number of retry attempts specified, instead of 5 , enter the appropriate number.

  8. Run the script to test the NOTIFY command.

    If all required values are correctly configured to work with the SMTP mail server, the NOTIFY command should now succeed.

How Analytics responds to failed connection attempts

If Analytics is unable to connect with the mail server, it makes five additional attempts to connect, with a 10-second pause between each attempt. This automated retry functionality addresses the issue of a mail server being momentarily unavailable.

If all connection attempts are unsuccessful, the NOTIFY command is canceled, with a message written to the log, but the script containing the command continues processing.

You can use the SET command to change the default retry behavior. You can specify:

  • a different number of connection attempts

  • no additional connection attempts

  • a different amount of time between attempts

  • script failure if the NOTIFY command fails to connect and is canceled

For additional information about the SET command, see SET command.

SET command syntax Examples and remarks

SET NOTIFYRETRYATTEMPTS <TO> num

 
SET NOTIFYRETRYATTEMPTS TO 10

Default setting: 5 attempts

Specifies the number of times the NOTIFY command will attempt to send an email if the initial attempt is unsuccessful. Enter a number from 0 to 255. If you enter 0, no additional attempts are made after an initial failure.

One possible reason for the NOTIFY command failing to send an email is that the email server is unavailable.

SET NOTIFYRETRYINTERVAL <TO> seconds

 
SET NOTIFYRETRYINTERVAL TO 30

Default setting: 10 seconds

Specifies the amount of time in seconds between NOTIFYRETRYATTEMPTS. Enter a number from 1 to 255.

SET NOTIFYFAILSTOP {ON | OFF}

 
SET NOTIFYFAILSTOP ON

Default setting: OFF

  • NOTIFYFAILSTOP is OFF Analytics allows a script to continue even if a NOTIFY command in the script fails.
  • NOTIFYFAILSTOP is ON Analytics stops processing a script, and writes a message to the log, if a NOTIFY command in the script fails. The script stops after the initial failure, or after the specified number of NOTIFYRETRYATTEMPTS, if none of the attempts are successful.

Note

An invalid email recipient is not considered a failure of the NOTIFY command and does not cause a script to stop regardless of the NOTIFYFAILSTOP setting.