Service Desk Notifications/Outbound Mail Technical Architecture Guide

Version 7

    Verified Product Versions

    Service Desk 7.7.xService Desk 7.8.xService Desk 2016.xService Desk 2017.x



    Introduction and Scope

    This document serves to provide an in-depth overview of the architecture of Service Desk’s notifications functionality.  The intended audience is Service Desk and server administrators wishing to gain a better understanding of the different types of notifications and how they interact within the Service Desk system.


    The information in this guide is correct for Service Desk version 7.3.2.  Please report any omissions using the comments system below the document.



    This document assumes that the reader has experience with Service Desk, specifically with the Process Designer component and configuring Response Levels and their escalations actions.


    Notifications Architecture Overview

    The architecture of the notifications functionality can be split up into four separate components.  Each are explained in detail in this document however below is a brief introduction to each:


    1.     Recipients – The configuration of who can receive a notification.

    2.     Notification Sources – The four different methods of generating a notification:

    a.     Process assignments.

    b.     Process reminders.

    c.     Response Level escalations.

    d.     Automated replies to Inbound Mail messages.

    3.     Notification Processing – the components used and resulting records created for all notifications.

    a.     Background Processing Service for reminders and escalations.

    b.     The User Message and User Message Recipient objects.

    4.     Notification Sending – the conversion to email messages sent to the network’s mail (SMTP) server.


    The diagram below shows how the components above interact with each other:


    notification flowchart 1.JPG



    The first key component of the notifications architecture is configuring the recipients.  There are four types of recipient that a notification can send to:


    1.    Service Desk Users

    For any user in Service Desk to receive an email message from a notification their Email Address must be populated and valid and the Notification Method must be either External or BothInternal notification method creates User Message records (see the section on the User Message object) but emails will not be generated.


    notification method.jpg


    2.    Service Desk Groups

    Notifications can also be sent to the Users who are members of a Group (Support Group, Company, Customer or Supplier Group).  For a user in a group to receive a notification the Receive Group Messages checkbox must be enabled on the User Group window.  This window appears whenever a user is added to a group, and can be brought up again within Administration by opening a group in the tree, expanding Users, right-clicking a user and selecting Modify User Group:


    notification user group.jpg


    3.    Service Desk Roles

    Like sending to Groups a notification can be sent to members of a Role.  However there is no configuration required to enable a member to receive messages, all members will always receive any notification sent to a role.


    4.    Other Email Addresses

    The final type of recipient is an email address not tied to any Service Desk user record.  These can be configured for escalation and (manual) reminder notifications, and are also used when the Inbound Mail Service replies to incoming messages from unrecognised email addresses.


    Notification Sources

    There are four ways a notification can be generated within Service Desk:


    1.    Process Assignments

    Notifications can be generated when creating an assignment and pressing Save, or when an automatic assignment is created as part of a process.  The notification is only generated on the first save of the assignment.  If further modifications are made to an assignment after it has been saved this will not generate any further notifications.


    a.   Selecting Recipients

    Up to four different notification recipients can be specified per assignment, each dictated by a checkbox on the Assignment record:


    a.     Assignee – The User and/or members of the Group/Role selected in the assignment being created.

    Assignment records can hold a User, Group and Role to specify who the process is assigned to.  Using the Notify Assignee checkbox a notification will be sent to those specified in these fields.  As mentioned in the section on Service Desk Groups you must ensure the Receive Group Messages? flag is enabled for a user within a group to be included in a group notification.


    If both a Group and a User are selected then a notification will be sent to the User and to the members of the Group.  To only send the notification to the User add this key to the tps.config file(s) on the server(s):


                                    <add key=”AssignmentNotificationsToUserOnly” value=”True” />

    Note that this key will not stop notifications going to members of the selected Role.  This is raised as a software issue, Problem 4914.  If you see this issue please log it with your Support provider.


    b.     Originator – The User specified in the Raise User field of the process.

    c.     Customer – Members of the Group specified in the Customer field on the process.

    d.     Supplier – Members of the Group specified in the Supplier field on the process.


    Any resulting notification subject is populated with the assignment Title field and the body with the assignment Description.  At the point of saving the assignment any placeholders in either of these fields are evaluated.


    2.    Process Reminders

    Reminders can be created either manually or automatically as part of a process.  Unlike assignments the notifications generated by reminders are not sent as the reminder is saved, but at a date/time specified on the record itself – the Send Date field.  The Background Processing Service (detailed later in this document) will process the reminder once the Send Date has passed, which it does at a 60 second poll interval.  Additionally a manual Send Message action is available on reminders once saved to manually send or re-send the notification.


    On initial creation of a Reminder the Is Active? Checkbox that exists on the record will be checked.  Once the Reminder has either been processed by the Background Processing Service or the manual Send Message action is used, this will be unchecked.  This confirms the Reminder no longer needs processing and is a good way to determine where a failure may exist if troubleshooting notifications not sending.


    If a reminder is being created manually the Send Date is a mandatory DateTime field that must be set with a date/time.  Its default value will be the current date/time.  If the reminder is created as an automatic action in a process the Send Date will either be an explicit value (likely the date/time the process was created) or dynamically populated via a calculation on the action.  In most cases an automatic reminder is created for sending immediately in which case as long as the Send Date is in the past it will be processed within the following 60 seconds when the Background Processing service next polls.


    a.   Selecting Recipients

    There are two ways to specify the recipient(s) for a Reminder.  The first is to use the dropdowns and checkboxes on the Reminder itself which allows the same options and logic as is available in Assignments.


    Note: Because the same logic is used there is a common misconception on the use of the Notify Assignee checkbox.  Unlike Assignments this does not send the notification to the currently assigned User/Group/Role of the related process.  Instead, like Assignments, it sends the notification to the User/Group/Role that is selected on that window.  Therefore the checkbox label on the Reminder window is better renamed to "Notify Specified Recipient(s):" to make its use more obvious.  A common cause of Reminders not being sent as expected is either the checkbox is selected but not a User/Group/Role, or vice versa.  To achieve the effect of notifying the current assignee in an automatic Reminder runtime values should be used in the User/Group/Role dropdowns to pick up from the Current Assignment relationship on the related process.


    The second way to specify recipients is to use the Add Recipient action available on a Reminder after its creation.  Because the action is only available after saving the Reminder it is unlikely you would use this in conjunction with an automatic Add Reminder action.  Clicking Add Recipient displays the following dialog box:


    notification reminder recipient.jpg


    Multiple recipients can be added on this dialog.  The available types of recipient includes Assignee, Originator, Customer and Supplier which all use the same values as they do on Assignments.  You can also specify a specific Group, Role, User, or Other E-Mail address.  Note that for Groups and Users the dropdown lists only display Analyst related values.


    3.    Escalation Notifications

    Escalations are configured as a component of a Response Level to perform actions at specific points in time during the a process.  Among the escalation actions available is the option to send a notification.  For more information on configuring Response Levels and Escalation Actions please see the Administrator manual.


    When a process is created with a Response Level set, a related record called an Escalation Point is created for each Escalation Action.  The Escalation Point has a Status, initially Open but later will either be Cancelled, Stopped, Completed or Expired.  It also has an Expiry Date which is a Date and Time determined on the fly for when the Escalation Action will be performed if the status has not yet changed from Open.  The Background Processing Service (detailed later in this document) checks every 60 seconds for Escalation Points that are still at the Open status but the Expiry Date has past and performs that point's associated Escalation Action.


    a.   Selecting Recipients

    Multiple recipients can be selected for each escalation notification with the same logic as used in Assignments and Reminders.  The dialog box for selecting the recipients is the same as the one used with the Add Recipient action on manual Reminders.  One additional feature however is that when selecting a User or Group you can right-click on the dropdown list of values and on the menu that appears select Value Type to select a runtime value for the recipient.  This allows the recipient to be dynamic, for example you can select the manager of the current assignee, or main contact at the customer, etc.


    Note:  Unlike Assignments and Reminders, the AssignNotificationsToUserOnly key does not stop the assigned Group from receiving the notification as well as the assigned User.


    4.    Replies to inbound emails

    The final source of a notification is automated responses to inbound emails received to create or update processes.  For generic messages these are far quicker and easier to configure than adding Assignments or Reminders to the process design, however are limited in the amount of dynamic information they can include in the message.  These are also the replies sent in the case of an error, such as the email sender not being a recognised user, an invalid process ID provided in an update email, etc.


    Within the Mail component in Console the Action Settings panel contains most of the configurable messages.  There are two additional messages that are configured from the User Settings panel.  While the email body can be configured, the subject will always be a standard "Re: ..." format of the inbound email's subject.


    The messages can be enabled or disabled for each inbound mail mapping, selecting the Send Reply On option to None, Creation, Update or Both.


    User Message and User Message Recipient records

    Regardless of how a notification is generated it will always result in records being created in the User Message and User Message Recipient objects (found in the System module).  These objects hold the queue for all notifications which are then processed by the Outbound Mail Service.  It is this service that creates and sends the emails to the network’s SMTP server.


    For each notification there is one record in the User Message object plus a User Message Recipient record for each recipient of the message (of which there may be many).  The following table shows what key information is stored in each object:

    User Message object

    Date SentThe Date and Time the message was added to the queue.
    SubjectThe subject for the resulting email.
    BodyThe body for the resulting email.

    User Message Recipient object

    MessageA relationship to the User Message record this recipient is for.
    UserA relationship to the User, if known.
    e-mail AddressThe email address of the recipient.
    Is Email SentA True/False value.  Once the Outbound Mail Service has sent the email for this recipient this is marked as True.
    Retry Count

    The number of failed attempts made by the Outbound Mail Service to send the email.

    The number of retries is configured in the Outbound Mail Server Settings.

    Next Retry Time

    The Date and Time the Outbound Mail Service will next attempt to send the email.

    The time to wait between retries is configured in the Outbound Mail Server Settings.

    Email FailedA True/False value.  If the Outbound Mail Service has failed to send the email (including retries) this is marked as True.


    Once the Is Email Sent or Email Failed attribute has been set to True by the Outbound Mail Service will no longer read the records, however the records will remain in the system.  It is highly recommended the records are periodically deleted to avoid performance issues when the records are either being created or processed.


    Prior to version 7.3.1 the only way to clear old records was via SQL scripts directly on the database (details for SQL Server: Unicode Version of Mail Archive.  For Oracle: Mail archive scripts for Oracle).  From version 7.3.1 onwards this can be achieved via the Schedule Manager component of Console.  For more information on this please see the section Clearing the Message Recipient table in the New Features manual.


    The Background Processing Service

    A key part of the Service Desk infrastructure is the Background Processing Service.  This is a windows service generally installed on the application server of the implementation and periodically runs various background tasks.  There are two tasks the service runs that both run every 60 seconds and are both relevant to sending notifications:


    1.     Notification Processing

    The Notification Processing task looks for all Reminders where the Send Date has past and the Is Active? checkbox is still checked.  It creates the necessary notifications and then unchecks Is Active?.


    2.     Escalation Point Processing

    The Escalation Point Processing task looks for all Escalation Points where the Expiry Date has past and the Status is Open, it then performs the associated Escalation Action.  In the case of notification actions the necessary notifications are created and the Status is changed to Expired.


    The Outbound Mail Service

    The final step in a notification being sent is the Outbound Mail Service.  This is a windows service generally installed on the application server of the implementation and sole job is to send emails from pending notifications.


    Service Configuration

    The service has a configuration file called Touchpaper.Service.Mail.Outbound.WindowsService.exe.config normally found in the C:\Program Files\LANDesk\LANDesk Applications folder of the server and in 7.5 and later the Service Desk\AppServices path.  It contains some standard settings required to connect to the Service Desk system, but also the following specific to this service:



    The interval (in minutes) between checks for new pending User Message/User Message Recipient records.

    The default value is 10 however it is common to have this as low as 1 or 2.

    Crystal Reports UsernameThe database username to use when creating a report to send as part of the email (a feature not covered in this document).
    Crystal Reports PasswordThe database password for the username above.  This value is encrypted.


    Note:  To alter either the Crystal Reports Password described above or the Outbound Mail Username setting which is used for logging in to the Service Desk system (usually as SA) run the TouchpaperPasswordTool.exe application found in the same folder on the server as this will encrypt the values.


    Mail Server Configuration

    The details for the SMTP (outgoing mail) server the service will connect to is configured in the Outbound Mail Server Settings panel of the Mail component in Console.  This requires the server name or IP address, the port to connect on (default is 25) and the From email address.  The From address can either be just an email address or also a display name by using the format: Display Name <email-address>.


    You can also specify a username and password if this is required by the SMTP server.



    When the service is started it will poll periodically based on the PollTimeMinutes setting in the configuration file.  Note that the first poll will not be immediately.


    On each poll the service will look for all User Message Recipient records that are neither marked as sent or failed, and where the Next Retry Time has past


    For each pending notification the service will attempt to connect to the SMTP server and send an email to the recipient.  If the SMTP server reports the message has been sent (although this does not mean the message will then be received) the service will set the Is Email Sent flag to True.


    If the service cannot connect to the SMTP server or it reports an error then the service will increase the Retry Count value and set the Next Retry Time accordingly.  If the value now exceeds the Retry Count setting in the Outbound Mail Server Settings then the Email Failed flag is set to True.