Email notifications

This article describes how to use and configure email notifications in GUI, command line, XML-config file.

Note 1: The email notifications are available starting from the SQL Examiner Suite 2022.

Note 2: Since the SQL Examiner and SQL Data Examiner command-line (CLI) tools are only available in the Professional edition, the functionality described in the article is also available in the Professional edition only.

Concepts

Email notifications can be configured in command line and in XML-config file.

Only a limited set of settings can be configured in the command line, full settings are possible only when using the xml configuration file (see below).

If a same setting is specified in both command line and XML configuration file, then the value specified in the command line overrides the value specified in the configuration file.

Configure default settings

Configure in CLI wizard

Learn more about CLI wizard here →

XML-config file

Sample configuration file

Learn more about XML-config file here →

<config>
    ...
    <Options>
        ...
        <NotificationOptions>
            <NotificationOption name="Enabled" value="True" />
            <NotificationOption name="To" value="john@contoso.com,bob@contoso.com" />
            <NotificationOption name="Condition" value="Always" />
            <NotificationOption name="Subject" value="[%APP] [%SCHEDULE] Task has been %STATUS" />
            <NotificationOption name="AttachLogs" value="True" />
            <NotificationOption name="AttachFiles" value="True" />
            <NotificationOption name="ZipAttachedFiles" value="True" />
            <NotificationOption name="SmtpServer" value="Default | Custom" />
            <SmtpServerOptions>
                <SmtpServerOption name="Server" value="smtp.contoso.com" />
                <SmtpServerOption name="Port" value="2525" />
                <SmtpServerOption name="From" value="no-reply@contoso.com" />
                <SmtpServerOption name="UseSsl" value="True" />
                <SmtpServerOption name="AuthenticationRequired" value="True" />
                <SmtpServerOption name="Login" value="epticylifire" />
                <SmtpServerOption name="Password" value="kDcwgQTqrK4E" />
            </SmtpServerOptions>
        </NotificationOptions>
    </Options>
    ...
</config>

NotificationOptions

Optional. If ommited, the program does not send email notifications. Each option is defined as NotificationOption tag with specific name attribute. Some options are required and some are optional. Optional options can be ommited and, if ommited, default value is used.

Enabled

Must be True, otherwise the program does not send email notifications.

To

Required, if recipents are not specified in the command line (see below). If specified in the command line, this tag can be ommited.

List of recipient email addresses. Must be explicitly defined. Multiple email addresses should be separated by a comma or by semicolon either.

Ignored, if recipients are specified in the command line. In this case, notifications are sent to recipients specified in the command line.

Condition

Required. Possible values are:

If notify and NotificationOptions parameters are specified in the command line, then the Condition value specified in XML configuration file is effectively ignored.

Subject

Optional. If specified, defines email subject, otherwise the default subject is used. All internal variables are allowed.

See the list of all internal variables here →

AttachLogs

Optional. Possible values are True or False, default is False.

If notify and NotificationOptions parameters are specified in the command line, then the AttachLogs value specified in XML configuration file is effectively ignored.

AttachFiles

Optional. Possible values are True or False, default is False.

If notify and NotificationOptions parameters are specified in the command line, then the AttachFiles value specified in XML configuration file is effectively ignored.

ZipAttachedFiles

Optional. Possible values are True or False, default is False. If True then all attached files (if any) are added to a single zip-file before sending.

If notify and NotificationOptions parameters are specified in the command line, then the ZipAttachedFiles value specified in XML configuration file is effectively ignored.

SmtpServer

Optional. If ommited, program uses default SMTP server. If default SMTP server is not specified, then the notification will not be sent and the error will be logged.

Possible values are:

SmtpServerOptions

Required if SmtpServer option value is Custom. Otherwise, optional and ignored.

If SmtpServer is Custom, but SmtpServerOptions tag is ommited (and options are not configured), then email notification will not be sent and the error will be logged.

Each option is defined as SmtpServerOption tag with specific name attribute.

Server

Required. IP address or DNS-name of a server.

Port

Optional. If not specified, default port (25) is used.

From

Required.

UseSsl

Optional. Possible values are True or False, default is False.

AuthenticationRequired

Optional. Possible values are True or False, default is False. If True specified, Login and Password must be specified (see below).

Login

Required if AuthenticationRequired is True, otherwise ignored.

Password

Required if AuthenticationRequired is True, otherwise ignored.

Command-line parameters

SMTP server and email subject cannot be configured in the command line. You need to specify default SMTP server in the program settings (either SQL Examiner, or SQL Data Examiner; see Options > Email notifications) to configure email notifications using command line only. If you need to specify a subject, you should use XML configuration file.

Sample command line

Learn more about command line parameters here →

SQLDECmd.exe ... /notify:"john@contoso.com,bob@contoso.com" /NotificationOptions:{Condition:Failed,AttachLogs,AttachFiles,ZipAttachedFiles}

notify

Enables email notifications and specify recipients simultaneously. If XML-config file is used and email notification options are configured in the file, then recipients which defined in this parameters overrides recipients, defined in XML-config file.

I.e., if john@contoso.com specified in command line and bob@contoso.com specified in XML-config, then notification will be sent to john@contoso.com only.

NotificationOptions

Required, if notify parameter is specified, otherwise ignored. Specify multiple options separated by commas in braces.

Condition

Required. Possible values are Failed or Always. Overrides Condition specified in XML configuration file (if any).

AttachLogs, AttachFiles, ZipAttachedFiles

If any of the parameters is present, it means True for the corresponding parameter. Otherwise, if the parameter is ommited, it means False.