This document is meant for users who have installed DBXL and are interested in configuring and using the Notifications functionality. The attached zip file contains the same text below as a Microsoft Word document, as well as the QdNotifications executables needed to run on the server.
Setup a notification
To create a notification, open the DBXL Administration Tool (DAT) and click to open the Document Type Configuration called QdNotification.
SLA Notification
A SLA Notification will send out an email based on Service Level Agreements. The admin will be able to specify the following parameters (See Image 1):
a. Type of Notification: In this case, we are creating an SLA Notification.
b. Document Type: This is the Document Type Configuration upon which this notification will act. The dropdown will be auto-populated with the names of the DocTypes present in your installation of DBXL.
c. Subtype:
i. Assigned: Sends an email when a document has been assigned to a person for a certain period of time.
ii. Status: Sends an email when a document has been in a status for a certain period of time. When Status is selected, an additional dropdown field will be shown, which allows the user to select the Status value. In addition, you can add a Status value other than those available by default using the Custom checkbox and field.
iii. Inactive: Sends an email when a document has been inactive for a certain period of time.
d. The field labeled Number of days allows you to enter the number of days that complete the Subtype specification. For instance, selecting Inactive and entering 5 will send a notification to users who have a document assigned to them if the document has been inactive for 5 days or more.
e. Reminder frequency indicates the number of hours in between notification emails. Note that the lowest reminder frequency you can have is equal to the frequency of your scheduled tasks.
f. Notify by email: Only select No if you’re only interested in keeping a log in the database table, without sending emails to the users.
Note that all SLA Notifications will send email when the number of days that have passed is greater than or equal to the “number of days” entered in the Notification’s configuration.
Image 1
Image 2: Sample SLA email as received by the user, for document type qFormTest, which contains a document that has been inactive for 2 days.
STAT Notification
A STAT Notification will send out an email containing statistics on a specific document type. You will be able to specify the following parameters (See Image 3):
a. Type of Notification: In this case, we are creating a STAT Notification.
b. Document Type: This is the DocType upon which this notification will act. The dropdown will be auto-populated with the Document Type names present in your installation of DBXL.
c. Subtype: The statistics can be compiled on a daily, weekly or monthly basis. Selecting Weekly will show an additional dropdown which allows the user to specify the day of the week. Selecting Monthly will allow the user to enter the day of the month when the action executes.
d. Scheduling information: This indicates the time of day to compile the statistics.
Image 3
You must also specify the user alias of the person who will receive this notification. This is specified in the right-hand pane, in the Assigned To and CC Alias fields.
Image 4 shows an example of a STAT Notification email, as received by the end user.
Image 4
The STAT email contains a maximum of four distinct tables: Overdue documents, Assigned Documents, Active Documents Status and a detailed Active Document List.
Notice that documents are labeled as ‘overdue’ in a qForm-based solution only after a SLA Notification has been sent out. The Overdue column in the Active Document List table contains the number of days between the SLA and STAT Notifications.
USER Notification
The USER notification enables the users to get a periodic notification of assigned documents. You will be able to specify the following parameters (See Image 5):
a. Type of Notification: In this case, we are creating a USER Notification.
b. Document Type: This is the DocType on which this notification will act upon. The dropdown will be auto-populated with the DocTypes present in your installation of DBXL.
c. Number of days: Specify the number of days after which you will receive notifications regarding documents that have been assigned.
d. Reminder frequency indicates the number of hours in between notification emails. Note that the lowest reminder frequency you can have is equal to the frequency of your scheduled tasks.
Image 5
Image 6 shows an example of a USER notification email as received by the user.
Image 6
All three of these server-side notifications depend on scheduled tasks. The first executable is NotificationSPCaller.exe, which analyzes the path each form has taken through the DBXL workflow and then creates a queue of notification emails that will be sent out. This queue is stored in a SQL table that holds the data necessary to send email to the users. The second executable, QdEmailSenderApplication, will be responsible for generating the notifications, while scheduled tasks will determine the delivery schedule.
Installing the notifications executables
a. Download the Notifications Package zip file.
b. Unzip the file contents to the folder C:\Program Files\Qdabra Software.
Configuring QdNotificationSpCaller
a. Open the configuration file located in the QdNotificationsSpCaller folder, called notificationspcaller.exe.config, in the text editor of your choice.
b. Modify the connection string to match your DBXL installation. Be sure to specify a connection to the user specified database. Save and close the configuration file. See Image 7.
Image 7
c. Run notificationspcaller.exe in a command window to test. Note that if there is a problem or error, a log file will be created in the same folder where QdNotificationSpCaller.exe is located.
Configuring QdEmailSenderApplication
a. Navigate to the subfolder that contains QdEmailSenderApplication.exe.
b. Open the configuration file, called QdEmailSenderApplication.exe.config, in the text editor of your choice.
c. Modify the connection string to match your DBXL installation, as done in step c above. See Image 8.
Image 8
d. Modify the following fields under /configuration/appSettings (for more information see the comments included in the configuration file itself and Image 9):
i. QdAdminId is the email address placed in the “From” and “Reply To” fields in the email that will be sent out. This must be a valid email address in order for notifications to work.
ii. QdAdminDisplayName is the name that will be displayed in the “From” field.
iii. smtpServer is the mail server used to send out the email. If you don’t know the value for this, contact your system administrator.
iv. stmpPort is the port used to send email, usually left blank if using the default port. Don’t set the value unless you will be using a non-standard port to connect.
v. smtpAuth determines the type of authentication scheme used. The three options are detailed as comments in the config file. The fields username, password and domain are only used if smtpAuth is set to “Basic”.
Image 9
e. Specify the values QdwebserviceDocumentsPath and QdwebserviceTemplatePath parameters that will help form any links that are included in the email notifications. Make sure this server is accessible from the receiver’s computer. For instance, using localhost as the servername will not likely work. Always use a trailing slash (/) to finish the path. See Image 10.
Image 10
f. Save the config file and close it.
g. Run QdEmailSenderApplication.exe in a command window to test. Note that if there is a problem or error, a log file will be created in the same folder.
Adding scheduled tasks
a. Go to Control Panel and locate Scheduled Tasks. Click on Add Scheduled Task. In the initial dialog, click Next.
b. Click on Browse and navigate to the location of QdNotificationSpCaller.exe. Select QdEmailSenderApplication.exe and click Next.
c. In the next dialog, name the task and select the task’s frequency (daily, weekly, etc.). Click Next.
d. In the following dialog you may provide further details regarding the scheduling of the task. You may adjust these to fit your needs. When done, click Next.
e. Specify the password to be used for the pre-populated username. This is the account that will be used to run the notifications task. Click Next and then click on Finish.
Image 11
Repeat the same steps for QdEmailSenderApplication.exe, noting that QdNotificationSpCaller.exe must run before QdEmailSenderApplication.exe in order to build the email queue. It is recommended that users keep these two tasks an hour apart.
The administrator is able to change the contents of the email notifications that the users will receive. QdEmailContentSource.xml, located in the C:\Program Files\Qdabra Software\QdNotifications\QdEmailSenderApplication\LanguageResource folder, contains the email contents, which the user may modify as desired.
This also supports localization, allowing the user to translate the contents of the email to the language of their choice. Note that to switch the language of the emails that are sent, you will need to modify the QdEmailSenderApplication.exe.config file located in C:\Program Files\Qdabra\QdNotifications\QdEmailSenderApplication, making sure that the node <add key="Language" value="es-AR" /> matches the Language locale you wish to use in QdEmailContentSource.xml.
An example of localization is shown in Image 12, with three examples of nodes in the QdEmailContentSource.xml mapped to the email received.
Image 12