Configuring EDQ Web Push Notifications

3.1 Setting Up and Registering for Web Push Notifications

Notifications are generated by triggers and therefore can report on job start/stop/error and other events. These notifications should be used for infrequent events, which may demand immediate attention from users. Note that these notifications are not meant to replace existing methods like emails, which you should use for more frequent events such as case management assignment.

To enable support for web push notifications, add the following setting to director.properties and restart the server:

web.push.enabled = true
web.push.sub     = mailto:systemadminemailaddress

The email address in the web.push.sub property identifies an administrative contact for the EDQ installation. It is used only if the browser provider identifies a problem. For example:

web.push.sub     = mailto:systemadmins@example.com

When you set this property, a new Web Interface system permission called Register for web push notifications is available.

You should enable this permission for any user who can register for notifications. For users with this permission a new option called Enable Notifications appears in the menu under the user name in the top right of the Launchpad. Make sure that EDQ uses HTTPS connections with a valid SSL certificate.

Selecting Enable Notifications will request a subscription from the browser. If this is the first time for the site the browser will ask for confirmation. After the confirmation is granted the subscription information is sent to the EDQ server and persisted in the database.

To generate a notification, the EDQ server must make an HTTPS call to an external endpoint. If a proxy is required to reach the external location, ensure that the Java proxy settings are specified. You can set the proxy settings either using command line settings or in jvm.properties. For example:

https.proxyHost = proxy.example.com
  
https.proxyPort = 80
http.nonProxyHosts = *.example.com|localhost

3.2 Generating Web Push Notifications

A new webpush library is available for use in script triggers. The basic usage is:

addLibrary("webpush")
 
function getPath() {
  return "/job/(start|end)"
}
 
function run(path, id, env, ...) {
  var push = WebPush.create("message")
  WebPush.push(push)
}

The notification object has these attributes:

Attribute	Description	Default Value
title	Notification title.	Oracle Enterprise Data Quality.
message	Notification body.
icon	Notification icon, relative to EDQ web root.	images/logo64.png
image	Top image for notification, relative to EDQ web root. This attribute is not supported in Mozilla Firefox and Safari browsers.
requireInteraction	If set to `true`, the notification remains open and must be closed manually. This attribute is not supported in Mozilla Firefox and Safari browsers.	`false`
usernames	User name filter.
userids	User ID filter.
groupnames	Group name filter.
groupids	Group ID filter.
projectID	Project ID filter.

Example:

function run(path, id, env, ...) {
  var push = WebPush.create("a message")
 
  push.title = "System notification"
  push.icon  = "local/images/logo.png"
 
  WebPush.push(push)
}

Normally the notifications are sent to all registered subscriptions. You can filter subscriptions by user, group, and project ID. To apply filtering, set options on the notification before sending. For example:

function run(path, id, env, ...) {
  var push = WebPush.create("a message")
 
  push.title      = "Job notification"
  push.icon       = "images/logo.png"
 
  push.usernames  = ["username"]
  push.userids    = [1]
  push.groupnames = ["Administrators"]
  push.groupids   = [1]
  push.projectID  = 1
 
  push.push()
}

The push will proceed if the user matches any of the user names or IDs, and matches any of the group names or IDs, and has access to the project. Note that the filtering applies to the user who created the subscription originally and not the user, if any, that is currently logged into the site from the browser. The notification image is displayed above the title and message.

3.3 Example Trigger Script

Here's a trigger script that runs on job completion and sends notifications on error.

addLibrary("jobNotification");
addLibrary("webpush")
 
function getPath() {
  return "/job/end";
}
 
function run(path, id, env, missionbean, map) {
 
  // Report badness
 
  if (map.mission.currentStatus != 'FINISHED') {
    var str       = ""
    var sections  = map.sections;
    var tsections = missionbean.taskSections;
    var nsecs     = tsections.length
 
 
    for (var k = 0; k < nsecs; k++) {
      var sec = tsections[k]
      var tasks = sec.tasks;
      var xs   = sections['section' + k]
 
      for (var t = 0; t < tasks.length; t++) {
        var task = tasks[t]
        var tcx  = xs[task.taskId.taskDetail + ":" + task.taskId.version]
 
        if (tcx != null) {
          var tc = tcx.taskcontext
 
          str += "Phase: " + sec.sectionName + " task: " + task.taskId.taskType + "/" + task.taskId.taskDetail + ": status: " + tc.currentStatus + "\n"
 
          if (tc.currentStatusMessage) {
            str += "Message: " + tc.currentStatusMessage.getMessage() + "\n"
          }
 
          str += "\n"
        }
      }
    }
 
    var push = WebPush.create(str)
 
    push.title     = "Job error"
    push.projectID = missionbean.projectID
 
    WebPush.push(push)
  }
}

Here's an example notification generated by the script:
Example push notification

3.4 REST API for Web Push Notifications

You can use a system administration REST API to trigger push notifications. Administrators can use this to notify users of important events such as an impending shutdown. To trigger push notifications, use the following interface:

POST http://server/edq/admin/web/push

The user must have the administer system permission. The payload is a JSON object with the same attributes as the script push object described in Generating Web Push Notifications.

Example:

{ "title"              : "Sys admin",
  "message"            : "System Admin notification",
  "image"              : "local/agamemnon.jpg",
  "requireInteraction" : true
}