Notifications

You are looking at an older version of the documentation. The latest version is found here.

The Data Virtuality Server supports two kinds of notifications: local and global.

A local notification can be created or deleted by providing a comma-separated list of job IDs:

SQL

SELECT * FROM (CALL SYSADMIN.enableJobEmailNotification(jobIds => '15, 18', jobStatuses => 'FAILED, success', recipients => 'myemail@datavirtuality.de', subjectTemplate => 'DV Report - local subject', messageTemplate => 'DV Report - Local message - description: %description%')) a;;

SELECT * FROM (CALL SYSADMIN.disableJobEmailNotification(jobIds => '15, 18')) a;;

The procedure calls return in both cases the IDs of the notification entities that have been added or removed.

A global notification can be defined by passing "*" to the job's argument and is identified in the system table by the globalNotification flag set to TRUE and a NULL jobId:

SQL

SELECT * FROM (CALL SYSADMIN.enableJobEmailNotification(jobIds => '*', jobStatuses => 'FAILED, SUcceSS', recipients => 'myemail@datavirtuality.de', subjectTemplate => 'DV Report - global subject', messageTemplate => 'DV Report - Global message - description: %Description%'
)) a ;;
SELECT * FROM (CALL SYSADMIN.disableJobEmailNotification(jobIds => '*')) a ;;

If the procedure to enable a notification is called on an already existing notification (both local and global), the old values are overridden with the new ones.

To correctly use the email notification mechanism for jobs, setting the appropriate SMTP configuration in Data Virtuality Server is necessary. This can be done using the UTILS.setSmtpConfiguration() procedure or manually changing the configuration in dvserver-standalone.xml.

Statuses and Recipients

These two arguments cannot be null or empty. The system validates if correct statuses (SUCCESS, FAILED, etc.) are provided and also if the recipients are valid email addresses.

If a local notification is defined for a given job and a global notification is enabled, the system combines statuses and recipients from both local and global notifications. For example, if a local notification is defined with a SUCCESS status and a global notification is defined in the case of FAILED jobs, the system will send a notification for this job if it succeeds or fails.

Recipients are combined similarly to send an email to all recipients defined in local and global notifications.

Templates for Subject and Body of the Email Message

The procedure to enable a new notification accepts the two parameters subjectTemplate and messageTemplate (both nullable) to specify custom templates that will be applied to the notification email. If not specified, a default template will be used.

In the subject and message templates, it is possible to specify some placeholders that will be replaced by the current values of the related job. These are the placeholders (case-insensitive) that are supported by the current implementation:

Placeholder	Description
`%id%`	ID of the job
`%description%`	Description of the job
`%description%`	Execution time of the job
`%status%`	Status of the job
`%failurereason%`	Failure reason if the status is `FAILED`, empty otherwise

The system prefers a local notification using templates for subjects and body messages if both local and global notifications are defined for a job. If the template is not defined (NULL) for a local notification, the system will use the template defined in the global notification, if not null. If no templates have been defined for the global notification, default templates will be applied.

Please note that emails are sent in HTML, and HTML tags are allowed to change the body's format (colours, styles, etc.).

The following header and footer are automatically added by the system when the email is generated:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Datavirtuality Report</title>
</head>
<body>
</body>
</html>

Default Subject and Message Templates

As mentioned before, default ones will be applied if no templates are defined.

In particular, default templates for subject and message, respectively, are defined as follows:

Datavirtuality Report - %status% - Job: %description% (jobId:%id%)

<h4>Datavirtuality Report:</h4>
<div>
Job ID: %id% <br />
Job Description: %description% <br />
Job Status: %status% <br />
Failure Reason: %failurereason% <br />
Execution time: %time%

</div>

Slack Notifications

Enabling/Disabling/Deleting Local and Global Notifications

The SYSADMIN.enableJobSlackNotification procedure creates notifications for particular jobs, and the SYSADMIN.disableJobSlackNotification procedure disables existing notifications. If you need to completely delete a notification, you can use the SYSADMIN.deleteSlackNotification procedure.

It is possible to define two kinds of notifications: local and global.

A local notification takes precedence over a global notification. This means that if the global notification is enabled and the job is not excluded from the global, and the job has its specific notification, then the message and its type will be taken from the notification for the specific job, not from the global one.

A local notification can be enabled, disabled, or deleted by providing a comma-separated list of job IDs:

SQL

CALL "SYSADMIN.enableJobSlackNotification"(
    "jobIds" => '13, 11, 9, 14',
    "jobStatuses" => 'FAILED,FAILED_AUTORETRY',
    "webHookURL" => <Slack WebHook URL>,
    "message" => 'Job %id% with description %description% fails due to %failurereason%',
    "isFormattedSlackMessage" => false
);;
 
CALL "SYSADMIN.disableJobSlackNotification"(
    "jobIds" => '13,11'
);;
 
CALL "SYSADMIN.deleteSlackNotification"(
    "jobIds" => '13,11'
);;

A global notification can be defined by passing "*" to the job's argument:

CODE

CALL "SYSADMIN.enableJobSlackNotification"(
    "jobIds" => '*',
    "jobStatuses" => 'SUCCESS',
    "webHookURL" => <Slack WebHook URL>,
    "message" => 'Job %id% with description %description% fails due to %failurereason%',
    "isFormattedSlackMessage" => false
);;
 
CALL "SYSADMIN.disableJobSlackNotification"(
    "jobIds" => '*'
);;
 
CALL "SYSADMIN.deleteSlackNotification"(
    "jobIds" => '*'
);;

Sending Notifications

The SYSADMIN.sendSlackNotification procedure enables sending an arbitrary Slack notification:

CODE

CALL "SYSADMIN.sendSlackNotification"(
    "message" => '{"text":"JSON format"}',
    "webHookURL" => <Slack WebHook URL>,
    "isFormattedSlackMessage" => true
);;
 
CALL "SYSADMIN.sendSlackNotification"(
    "message" => 'A plain format',
    "webHookURL" => <Slack WebHook URL>
);;