Email and SMS

Configure

In the dbWatch Monitor, go to the “Server”->”Server Extensions” menu. An item called “E-mail extension” should now be visible (v 5.2 or later).

To configure the extension, select it and click “Configure”.

You should now see the initial configuration screen (below)

The first section lets you define connection details to the SMTP server.

SMTP Host is the hostname or IP address for the email server.
SMTP Port is the port the SMTP process is listening to.
Username is the used when you need to provide credentials when sending emails.
Password is the password used to authenticate the user.
SSL/TLS will enable the encryption for this connection.

Example for Office365 user:
SMTP Host: smtp.office365.com
SMTP Port: 587
Username: some-email@dbwatch.com
Password: SomethingSecret
SSL/TLS: enabled

If you have a provider that uses individual app passwords, that will just replace the regular password used for that user.

The “From address” field lets you define which address should appear as the sender in the e-mails you receive from the dbWatch Server. Typically the same as the username.

The second section consists of a set of “Rules”.

Rulename is your name for this rule, if you make this somewhat descriptive its easier to see what you intended next time you go into this configuration.

Type can be MAIL or SMS. The difference is that SMS will cut down the message, as to fit it better on a SMS and is intended for email-to-sms gateways.

Receivers are the email addresses this message will be sent to. It can be multiple addresses with a comma separating the emails.

Schedules is a filter to only send statuses that occur in a given timeframe. If the status occur outside the timeframe it will not send a message.

Statuses is a filter to send all or just a selection of statuses. Valid statuses are “ALL” for all statuses, “LICENSE-EXPIRING” for alerting on dbWatch license that are expiring, “EXCEPTION” for procedure exceptions, errors in the monitoring jobs. “ENGINE-WARNING” is warnings from the monitoring jobs. “ENGINE-ALARM” is alarms from the jobs. “RECONNECTION-FAILURE” is a signal for when we cant connect again to an instance, after waiting and trying multiple times. (You can configure this in Server->Server Configuration->Reconnection configuration). “ENGINE-LOST-CONNECTION” is the signal we send when we lose connection to an instance. If you have many problems with network or servers restarting and you don’t want emails on this, its best to use the “RECONNECTION-FAILURE” signal, which is slower, as it will try several connection attempts before giving up, but provide less alarms.

Instance filter is a FDL filter to select what instances to send signals from. Typical filtering is:
group=‘Production’
to get signals from only instances in the group “Production” or
name=‘Server A’
to get signals from only an instance with the name “Server A”

More information about FDL is here

Job filter is also a FDL filter to select what jobs you want signals from. Typical filtering is:
name like ‘backup’
to get signals from only jobs that have “backup” as part of their name.

Template rules

Initially there are 5 template rules created. They are disabled by default, but provide example setups that can be adjusted.

Rule 1, “Production systems office Hours”

This rule is intended to send all status types from instances that is part of the group “Production”, but only within office hours. (07.00 to 16.59, Monday->Friday). Typically this would be emails that go to the DBA or helpdesk within office hours.

Rule 2, “Production systems All Hours”

This rule is intended for a EMAIL-TO-SMS gateway, as it will cut down the message to fit a SMS. It only send ALARMS, RECONNECTION-FAILURE and ENGINE-LOST-CONNECTION signals for database instances in the group “Production”. Typically this is configured to send important alarms for production database instances directly as SMS to the DBA or on-call staff.

Rule 3, “Production systems Weekends”

This rule is intended for a EMAIL-TO-SMS gateway, as it will cut down the message to fit a SMS. It only send ALARMS, RECONNECTION-FAILURE and ENGINE-LOST-CONNECTION signals for database instances in the group “Production”. It is configured only to send emails in weekends, so Saturday or Sunday. Typically this is configured to send important alarms for production database instances directly as SMS to the on call DBA during the weekend.

Rule 4, “Test and Development systems”

This rule only send ALARMS, RECONNECTION-FAILURE and ENGINE-LOST-CONNECTION signals for database instances in the groups “Test” or “Development”: It is configured to send emails within office hours. (07.00 to 16.59, Monday->Friday). Typically this is intended for the Dev or Test teams, helpdesk or DBA that works on dev or test systems.

Rule 5, “Development systems”

This rule sends all statuses, from the database instances in the group “Development”, if the job is has something with “backup” in its name. But only from 07.00 to 07.59. This could be used to send only backup related emails to a dedicated person for this. Note that the job (with backup in its name) will need to be scheduled between 07.00 and 07.59 to get any emails from this.

You can remove the rules you don’t need, or disable them. Rules must be enabled and the extension also needs to be enabled for messages to be sent.

Setting mail formats

To override the default mail format, you can place a set of format files in the “C:\ProgramData\dbWatchControlCenter\config\extensions\” catalog.

For mails related to alerts the files are:

alert_format_subject.txt
alert_format_body.txt

For mails related to lost connection the files are:

lost_connection_format_subject.txt
lost_connection_format_body.txt

For mails related to reconnection the files are:

reconnect_format_subject.txt
reconnect_format_body.txt

The files called *_subject.txt are used to generate the mail subject
field, and the files called *_body.txt are used to generate the mail body.

There is a set of values that are initiated when the email is generated. These are:

ALERT – The name of the alert that generated the event.
STATUS – The status for the alert.
INSTANCE – The name of the database instance for the alert.
ALERT_DETAILS – A description of the alert state.
GROUP – The group for the instance.

For the “ENGINE-LOST-CONNECTION”, “RECONNECTION-FAILURE” and “LICENSE-EXPIRING” type signals, STATUS, ALERT, and ALERT_DETAILS values are not generated, as it is not applicable to this signal.

So a typical format for an alert would be:

alert_format_subject.txt

%STATUS% for %ALERT% on %INSTANCE%

alert_format_body.txt

%STATUS% for %ALERT% on %INSTANCE% for %GROUP%

%ALERT_DETAILS%

This mail was generated automatically by the dbWatch Server.

This will then produce an email similar to the following;

Subject:

WARNING for Database disk space usage on SomeDatabaseInstance

Body:

WARNING for Database disk space usage on SomeDatabaseInstance for Acme Inc

Drive C: 396.7 GB free space. 39 database(s) effected

This mail was generated automatically by the dbWatch Server

Format pr. rule

In addition to the general rule format files, it is possible to specify different formats per rule.

You do this by creating additional files with the rule name in square brackets at the end of the file name.

So if you have a rule called “A”, you can create files called “alert_format_subject[A].txt and “alert_format_body[A].txt”. Then theese files will be used when creating E-mails for this rule.

Remove the “OK” messages

It is possible to stop the Mail extension from sending out the “OK” messages. However there is currently no GUI for this, so you have to edit the configuration file manually.

The configuration file can be found in the “C:\ProgramData\dbWatchControlCenter\config\extensions” catalog and is called “E-Mail extension.xml”.

Open the file in a text editor. There should be a “filter” tag for each of the filters that are defined. Here you can add a tag called “report-improvement” with the value false. This will cause the extension to skip the OK messages for this filter.

You have to restart the dbWatch Server in order for the changes to take effect.

Debugging

If you are experiencing issues when using the extension, it is possible to enable more logging by setting a tag in the configuration file manually.

The configuration file can be found in the “C:\ProgramData\dbWatchControlCenter\config\extensions” catalog and is called “E-Mail extension.xml”.

Open the file in a text editor, there should be a tag called “debug-level” with the value 0. You can change this to 1 (some logging) or 2 (a lot of logging). Doing this makes it easier to track down configuration errors as the server.log file will tell you what is going on when it is attempting to send messages. You have to restart the dbWatch Server in order for the changes to take effect.

Once this is enabled, and the dbWatch Server is restarted, when you test the email extension, you will get more information in the server.log file. (Default location C:\ProgramData\dbWatchControlCenter\log\server.log)

← Extensions and 3rd party integrations / Configuring email extension for Service Now →

Feedback

Post your comment on this topic.