Customizing Microsoft Project Server E-mail Notifications and Reminders

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Summary

This article will show you how to add custom e-mail notification and reminder data to the Microsoft® Project Server database, as well as how to customize Microsoft Project Web Access so that it is available for members of your organization. This article also describes how you can use three Microsoft Project methods to enable Microsoft Project Web Access e-mail notifications and reminders in a third-party timesheet application.

Understanding E-mail Notifications and Reminders

E-mail notifications and reminders are an automated feature of Microsoft Project Server. They are sent out automatically whenever a task assignment is made from Microsoft Project to Microsoft Project Server, or whenever assignment data is updated from Microsoft Project Server to Microsoft Project. The primary differences between a reminder and a notification are that:

  • E-mail notifications are used to alert users of changes or actions within the various projects to which they belong. E-mail notifications are generated by a wide range of user-initiated events; for example, a project manager sending a new task to a resource can trigger an alert to the resource so that he knows he has a new assignment.
  • E-mail reminders are used to alert users of upcoming or overdue events for which they are responsible. E-mail reminders are driven by timed events; for example, a reminder is sent to the resource if a task is past its completion date.

To subscribe to the e-mail notification and reminder service, users must log on to Microsoft Project Web Access and then click Set my e-mail notificationsand reminders or Set e-mail reminders for my resources on the Home page. The following Microsoft ASPs in Microsoft Project Web Access are part of the e-mail notification and reminder service:

  • Notification.asp The page on which an administrator sets the system settings for the e-mail server. This is the Notifications and reminders page in the Admin area of Microsoft Project Web Access.
  • Self_Notifications.asp The page on which users subscribe to e-mail notifications and reminders. This is the Set my e-mail notifications and reminders page in Microsoft Project Web Access.
  • Mgr_Notifications.asp The page on which managers subscribe to e-mail notifications and reminders. This is the Set e-mail reminders for my resources page in Microsoft Project Web Access.

These pages contain settings that are stored in the Microsoft Project Server database. The Notification Processing Engine (NPE) periodically queries the database for user notification subscriptions. Notifications are sent whenever assignment data is sent to Microsoft Project Server from Microsoft Project (or vice versa) and the settings specified for each user match the action being queried.

The NPE consists of the following components:

  • PjSchSvc.exe A Microsoft Windows® service program that calls the PjNPE.dll every [n] minutes (default is 30).
  • PjNPE.dll A component that sends e-mail (via Simple Mail Transfer Protocol [SMTP]) based on subscription and reminder settings.
  • CDOSYS.dll A Windows system-provided object that handles SMTP calls.
  • SMTP (CDOSYS) A protocol used by the NPE to send notification and reminder e-mail messages.
  • ADO/OLEDB A protocol used by the NPE to call the PjQuery.dll component to access the Microsoft Project Server database.

The tables in the Microsoft Project Server database that are used for storing notification and reminder settings and data include:

  • MSP_WEB_NOTIFICATIONS Stores user and manager e-mail notification and reminder subscription information.
  • MSP_WEB_NOTIFICATION_EVENTS Stores the information related to each e-mail notification and reminder message for new, updated, or cancelled task assignments.
  • MSP_WEB_REMINDERS Contains all the reminders that users create while using Microsoft Project, including the send frequency of the reminder, SQL queries associated with the reminder, and who should be included in the e-mail reminder.
  • MSP_WEB_REMINDER_TYPES Links reminders to status reports or assignments. It also identifies whether the reminder is a self-reminder, and provides localized e-mail text that is part of any automatic reminder.
  • MSP_WEB_REMINDERS_TEMP Temporarily stores all reminder e-mail messages to be sent out by the NPE. This process creates a single record for each recipient, and then attaches e-mail messages to generate a single, unified e-mail message.
  • MSP_WEB_ADMIN Stores administrative settings for Microsoft Project Web Access, including the name and port of the SMTP mail server, the default reply address for all e-mail notifications and reminders, your organization's e-mail address, the default e-mail message, and the frequency that the NPE will run. The information stored in this table that is related to the Microsoft Project Server e-mail notifications and reminder service can be modified from the Notifications and reminders page in Microsoft Project Web Access.

Note For more information about these tables, see the SvrDB.htm file in the \Docs\1033 folder on the Microsoft Project installation CD, or in the C:\Program Files\Microsoft Office\Office10\1033 folder (1033 is the locale ID [LCID] for U.S. English, the folder for localized versions will vary; for example, the LCID for Japanese is 1041) folder on your Microsoft Project Server CD-ROM.

Triggering E-mail Notifications Programmatically

You can use Microsoft Project Server e-mail notifications in your existing timesheet application. For example, you can implement an e-mail notification that is sent when a resource updates any task that utilizes the TaskUpdate event in Microsoft Project Server.

There are three methods that can be used to programmatically trigger an e-mail notification: EventNotify, EventContentNotify, and SendEmail. These methods must initiate the PjENAgent object as part of the process that triggers the e-mail notification.

To send out an e-mail notification using the PjENAgent object, the SMTP Mail Server Information on the Notifications and Reminders page (Notification.asp) in Microsoft Project Web Access must be completed.

Using EventNotify

The EventNotify method sends a notification e-mail message for all predefined event notification types in Microsoft Project Server by using a predefined e-mail format. The receiver must have an e-mail address, and must have subscribed in Microsoft Project Web Access to receive event notification e-mail messages.

To use this method in an e-mail notification for a third-party application, create a custom extension that includes server-side script that does the following:

  • Creates a variable that can be used in an array that holds all of the assignment IDs for the assignments you want e-mail notifications sent out for.
  • Creates a variable that holds the TaskUpdate event ID for the e-mail notification. The TaskUpdate ID can be found in the MSP_WEB_NOTIFICATION_EVENTS table (WNTFY_EVENT_ID column) in the Microsoft Project Server database.
  • Creates variables to hold the sender's and receiver's Microsoft Project Server resource ID.
  • Sets the PjENAgent, PjQuery, and oCnxCookie objects, and specifies the location of your Microsoft Project Server.
  • Creates the data array and specifies to which project each assignment in the array belongs.
  • Calls the EventNotify method and links the projects, assignments, manager, resources, and notification together into a single e-mail notification.
  • Disconnects and cleans up.

Copy and paste the following code into the file you want to use with the custom e-mail notification:

  '-- Array to hold WASSN_IDs
'--If you are using VBScript remove As Integer from the following variable before running the code
  Dim rgData() As Integer
  
  '-- Project Server predefined Task Update notification event
  MgrEvtTaskUpdate = 1009  
  
  '-- Sender WRES_ID
  nSenderWResID = 102   
  '-- Email receiver WRES_ID (must have email defined)
  nReceiverWResID = 101 
  
  Set oPjENAgent = CreateObject("Pjsvrutl.PjENAgent")
  Set oPjQuery = CreateObject("PjQuery.PjGenericQuery2.1")
  adUseClient = 3
  Set oCnxCookie = oPjQuery.Connect("ProjectServer", 0, adUseClient, 65001)
  
  '-- Use your Microsoft Project Server machine's name here
  oPjENAgent.SetConnectionInfo oCnxCookie, "http://SERVER_NAME/ProjectServer"
  
  '-- Handle your normal task here, and find out tasks need to update
  '-- And put those updated tasks WASSN_ID into an array
  '-- Also remember which project those tasks belong to
'--Change "ProjectName" to the name of the project that the updated assignments belong to
  sProjectName = "ProjectName" 
  nNumTasksUpdate = 2
'--If you are using VBScript remove As Integer from the following variable before running the code
  ReDim rgData(nNumTasksUpdate) As Integer
  rgData(0) = 101  '-- WASSN_ID for the assignment you want to update
  rgData(1) = 102  '-- WASSN_ID for the assignment you want to update
  
  '-- Call EventNotify to send email for the event using Project Server predefined format
  oPjENAgent.EventNotify nSenderWResID, nRecverWresID, MgrEvtTaskUpdate, sProjectName, rgData
  
  '-- Disconnect and Cleanup
  oPjQuery.Disconnect oCnxCookie, 0
  Set oENAgent = Nothing
  Set oCnxCookie = Nothing
  Set oPjQuery = Nothing
Using EventContentNotify

The EventContentNotify method sends out notification e-mail messages. Like the EventNotify method, this method also requires the recipient to have an e-mail address and to have subscribed to the notification in Microsoft Project Web Access.

To use this method in a non-Microsoft Project Server e-mail notification, create a custom extension that includes server-side script that does the following:

  • Creates a variable that holds the TaskUpdate event ID for the e-mail notification. The TaskUpdate ID can be found in the MSP_WEB_NOTIFICATION_EVENTS table (WNTFY_EVENT_ID column) in the Microsoft Project Server database.
  • Creates variables to hold the sender's and receiver's Microsoft Project Server resource ID.
  • Sets the PjENAgent, PjQuery, and oCnxCookie objects, and specifies the location of your Microsoft Project Server.
  • Creates the parameters for the content to be included in the e-mail notification, including date ranges.
  • Calls the EventContentNotify method and links the projects, content, manager, resources, and notification together into a single e-mail notification.
  • Disconnects and cleans up.

Copy and paste the following code into the file you want to use with the custom e-mail notification:

  '-- Project Server predefined Task Update notification event
  MgrEvtTaskUpdate = 1009  
  
  '-- Sender WRES_ID
  nSenderWResID = 102   
  '-- Email receiver WRES_ID (must have email defined)
  nReceiverWResID = 101 
  
  Set oPjENAgent = CreateObject("Pjsvrutl.PjENAgent")
  Set oPjQuery = CreateObject("PjQuery.PjGenericQuery2.1")
  adUseClient = 3
  Set oCnxCookie = oPjQuery.Connect("ProjectServer", 0, adUseClient, 65001)
  
  '-- Use your Microsoft Project Server machine's name here
  oPjENAgent.SetConnectionInfo oCnxCookie, "http://SERVER_NAME/ProjectServer"
  
  '-- Handle your normal task here, and find out tasks need to update
  '-- And construct your email content yourself
  '-- Also remeber which project those tasks belong to
  sProjectName = "Project-1"
  CRLF = Chr(&HD) + Chr(&HA)
  sContent = "Task Name: Design Product" + CRLF + "Start: 01/01/2002   Finish: 01/31/2002" + CRLF + CRLF
  sContent = sContent + "Task Name: Develop Product" + CRLF + "Start: 02/01/2002   Finish: 03/31/2002" + CRLF + CRLF
  sContent = sContent + "Task Name: Develop Product" + CRLF + "Start: 04/01/2002   Finish: 06/30/2002" + CRLF + CRLF
  
  '-- Call EventContentNotify to send email for the event using Project Server predefined format
  oPjENAgent.EventContentNotify nSenderWResID, nRecverWresID, MgrEvtTaskUpdate, sProjectName, sContent
  
  '-- Disconnect and Cleanup
  oPjQuery.Disconnect oCnxCookie, 0
  Set oENAgent = Nothing
  Set oCnxCookie = Nothing
  Set oPjQuery = Nothing
Using SendEmail

The SendEmail method is the simplest and most flexible method to use when sending out event notification e-mail messages. The person who creates the e-mail notification can specify any parts of the e-mail they need, including the from, to, and cc: addresses, subject, and content.

To use this method in a non-Microsoft Project Server e-mail notification, create a custom extension that includes server-side script that does the following:

  • Sets the PjENAgent, PjQuery, and oCnxCookie objects, and specifies the location of your Microsoft Project Server.
  • Constructs the e-mail notification message; for example, the from, to, and cc: addresses, e-mail subject, and content.
  • Calls the SendEmail method and links the projects, content, manager, resources, and notification together into a single e-mail notification.
  • Disconnects and cleans up.

Copy and paste the following code into the file you want to use with the custom e-mail notification:

  Set oPjENAgent = CreateObject("Pjsvrutl.PjENAgent")
  Set oPjQuery = CreateObject("PjQuery.PjGenericQuery2.1")
  adUseClient = 3
  Set oCnxCookie = oPjQuery.Connect("ProjectServer", 0, adUseClient, 65001)
  
  '-- Use your Microsoft Project Server machine's name here
  oPjENAgent.SetConnectionInfo oCnxCookie, "http://SERVER_NAME/ProjectServer"
  
  '-- Construct email content, subject etc and call SendEmail
  sFromAddress = "notification@yourcompany.com"
  sToAddress = "mgremail@yourcompany.com"
  sCCAddress = ""
  sEmailSubject = "Notification: Task Update"
  sEmailContent = "The following tasks have been updated: T1, T2, T3"
  fHTML = 0      '-- use text email
  nLCID = 1033   '-- English
  oPjENAgent.SendEmail sFromAddress, sToAddress, sCCAddress, _ 
                       sEmailSubject, sEmailContent, fHTML, nLCID
  
  '-- Disconnect and Cleanup
  oPjQuery.Disconnect oCnxCookie, 0
  Set oENAgent = Nothing
  Set oCnxCookie = Nothing
  Set oPjQuery = Nothing

Adding New User E-mail Notifications

Microsoft Project Server includes many useful e-mail notifications. If there are notifications that your organization requires, but aren't included, you can create custom notifications by modifying the pages in Microsoft Project Web Access. For example, you can add a notification that sends an e-mail message to a new user when her account is created in Microsoft Project Web Access. Creating this specific notification is as simple as adding a check box to the Microsoft Project Web Access user interface, and adding some code that identifies the new e-mail notification action. This enables the SendEmail property in the PjENAgent object to send the notification to the new user.

Modifying the Sec_Users_AddModify.asp Page

To add the notification, place the downloaded Sec_Users_AddModify.asp page in the IIS Virtual Root\Admin folder of the Microsoft Project Server computer. This modified page differs from the original Microsoft Project Web Access page in the following locations:

  • A check box has been added to the user interface that enables an administrator to notify a new user that his account has been created in Microsoft Project Web Access (search for Change #1a in the download file):
  <%if (fAddUser) {%>
    <input ID="idNotifyNewUser" TYPE="CHECKBOX"> Send users an e-mail notifying them that their account has been created.
<%}%>
  • It sets the available values for the idNotifyNewUser check box to be either True or False (search for Change #1b in the download file):
  _form._notifyUser.value = idNotifyNewUser.checked ? 1 : 0;
  • It makes the new check box available to the POST method on the page (search for Change #1c in the download file):
  <input type="hidden" name="_notifyUser" value="0">
Modifying the Sec_Svr_Users.asp Page

To add the notification, find the downloaded Sec_Svr_Users.asp page in the IIS Virtual Root\Admin folder of the Microsoft Project Server computer. This modified page differs from the original Microsoft Project Web Access page in the following locations:

  • A variable for the new e-mail notification is declared (search for Change #2a in the download file):
  var fNotifyNewUser = GetInputAsNumber('_notifyUser');
  • The user is added to the appropriate Microsoft Project subwebs on a server running SharePoint Team Services™ from Microsoft (search for Change #2b in the download file):
  if (fNotifyNewUser)
{
NotifyNewAccount(unescape(sUserName), unescape(sEmail), true);
}
  • It declares a variable for the new e-mail notification (search for Change #2c in the download file):
  var fNotifyNewUser = GetInputAsNumber('_notifyUser');
  • The user is added to the Microsoft Project Server (search for Change #2d in the download file):
  if (fNotifyNewUser && nErr == 0)
{
NotifyNewAccount(unescape(sPJAccount), unescape(sEmail), false);
}
  • It adds a function that uses the SendEmail method of the PjENAgent object to send out an e-mail notification for new users (search for Change #2e in the download file):
  function NotifyNewAccount(sAcctName, sEmailAddress, fNT)
{
oPJQuery.Connect();
var oPjENAgent = Server.CreateObject("Pjsvrutl.PjENAgent");
oPjENAgent.SetConnectionInfo(oPJQuery.oCookie, sAppPath);
var sSubject = (fNT ? "Your NT account " : "Your account ") + "has been created in Project Server";
var sContent = "You can log onto the project server at " + sAppPath + " using ";
if (fNT)
sContent += "your NT account."
else
sContent += "'" + sAcctName + "'. Please contact administrator for the password."
oPjENAgent.SendEmail("notification@yourcompany.com", sEmailAddress, "", sSubject, sContent, 0, 1033);
oPJQuery.Disconnect();
oPjENAgent = null;
}

Customizing E-mail Reminders

E-mail reminders are automatically generated by a scheduled reminder service in Microsoft Project Server. You can extend the e-mail reminder service on Microsoft Project Server to include additional querying conditions based on tasks and status reports (though they cannot be extended to query for project- or resource-level information). For example, you can define an enterprise custom field, such as TaskEnterpriseFlag1, as a flag to indicate if a task is important. When you click Collaborate, point to Publish, and then click All Information in Microsoft Project Professional, this flag displays in Microsoft Project Web Access views (it is stored in the MSP_VIEW_PROJ_TASKS_ENT table, in the Microsoft Project Server database), and there is a corresponding assignment in the assignments table (MSP_WEB_ASSIGNMENTS) in the Microsoft Project Server database.

The examples and code samples in the following sections show you how to extend the e-mail reminder service through the addition of a reminder for project managers that queries task information to determine who should be sent an update when a critical task slips.

This example walks through the following steps:

  • Creating a localizable string for the e-mail reminder option
  • Creating a new e-mail reminder option in the Microsoft Project Server database
  • Modifying the Microsoft Project Web Access user interface
  • Adding code to the custom reminder file on Microsoft Project Server
  • Validating the new e-mail reminder option
Creating a Localizable String for a New E-mail Reminder Option

To create a localizable string for a new e-mail reminder option, add the following entries to the MSP_WEB_CONVERSIONS table in the Microsoft Project Server database:

  STRING_TYPE_ID:     3
CONV_VALUE: 950
LANG_ID: 1033
CONV_STRING: The following important tasks have slipped.\n\n
  STRING_TYPE_ID:     3
CONV_VALUE: 951
LANG_ID: 1033
CONV_STRING: To view and respond to the changes, please connect to Microsoft Project Web Access.\n\n

The information in the CONV_STRING field can be localized.

For more information about the MSP_WEB_CONVERSIONS table and the fields contained within this table, see the ProjDB.htm file in the \Docs\1033 folder on the Microsoft Project installation CD, or in the C:\Program Files\Microsoft Office\Office10\1033 folder (1033 is the locale ID [LCID] for U.S. English, the folder for localized versions will vary; for example, the LCID for Japanese is 1041).

Creating a New E-mail Reminder Option in the Database

To create a new e-mail reminder option in the Microsoft Project Server database, add the following information to the MSP_WEB_REMINDER_TYPES table:

  WRMND_TYPE_ID:       100000
WRMND_TABLE_ID: 2
  WRMND_IS_SELF:       0
WRMND_QUERY: Select WA.WPROJ_ID, WA.WRES_ID, WA.TASK_ID, WA.TASK_NAME, WR.RES_NAME,
         WA.ASSN_START_DATE, WA.ASSN_FINISH_DATE, WA.ASSN_WORK, 
         WA.ASSN_REM_WORK 
    From MSP_WEB_ASSIGNMENTS WA
         INNER JOIN MSP_VIEW_PROJ_TASKS_ENT PTE 
               ON (WA.WPROJ_ID=PTE.WPROJ_ID and 
                   WA.TASK_UID=PTE.ENT_TaskUniqueID and
                   PTE.TaskEnterpriseFlag1=1)
         INNER JOIN MSP_WEB_RESOURCES WR ON (WA.WRES_ID=WR.WRES_ID)
   Where WA.WRES_ID_MGR=^0 and (^1)
   order by WA.WPROJ_ID, WA.WRES_ID, ASSN_FINISH_DATE
WRMND_EMAIL_TITLE: 950
WRMND_EMAIL_TAIL1: 951
WRMND_TPE_DESC: TMR_005: Remind when a important task is slipped [every] [day]

For more information about the fields, descriptions, and values for the MSP_WEB_REMINDER_TYPES table, see the SvrDB.htm file in the \Docs\1033 folder on the Microsoft Project installation CD, or in the C:\Program Files\Microsoft Office\Office10\1033 folder (1033 is the locale ID [LCID] for U.S. English, the folder for localized versions will vary; for example, the LCID for Japanese is 1041).

Modifying the Microsoft Project Web Access User Interface to Support a Customized E-mail Reminder Option

For managers to select the new e-mail reminder option, you need to make it available for selection in Microsoft Project Web Access. To add the new e-mail reminder option, find the Mgr_Notifications.asp file in the Notifications folder of Microsoft Project Server, and then add the following HTML code to the end of the <FORM name="idMgrNotificationsForm" METHOD="POST"> section:

  <DIV CLASS="sub_section_text">Important tasks</div>
    <DIV CLASS="SectionContents" STYLE="margin-left: 15;">
        <DIV ID="TMR_100000">
            <INPUT TYPE="CHECKBOX" ONCLICK="ValueChange()" CLASS="InputCheckbox" ID="T_100000_CHECK" NAME="T_100000_CHECK">Send e-mail alerts when an important task is slipped <%=Every_Input_HTML('T_100000')%> <%=Day_Input_HTML('T_100000')%>
        </DIV>
        <BR>
        <DIV ID="TMR_1000000_OPTION">
            <%=EmailOption_Input_HTML('T_100000')%>
        </DIV>
    </DIV>
    <BR>

Note   The value 100000 in the above example is the reminder ID (WRMND_TYPE_ID) that you created when you added the new e-mail reminder option to the MSP_WEB_REMINDER_TYPES table.

Adding Code to the Custom Reminder File on Microsoft Project Server

To use the custom e-mail reminder option in Microsoft Project Web Access, you need to add code to the custom functions in the Custom_Reminder.asp file stored in the Notifications\Include folder of Microsoft Project Server. The Custom_Reminders.asp file includes the following functions:

  • AddDefaultCustomReminderByID
  • SetCustomReminderFromDB
  • SaveCustomReminders
  • GetCustomCriteriaByID
AddDefaultCustomReminderByID

This function creates a new record in the MSP_WEB_REMINDERS table. Add the following code:

  case 100000:
    AddDefaultReminder(rsReminder, 100000, const_TaskTableID, '0,0');
    break;
SetCustomReminderFromDB

This function gets information from the MSP_WEB_REMINDERS table in the Microsoft Project Server database and translates this information so that the controls for the e-mail reminder can be set in the Microsoft Project Web Access user interface.

The parameters associated with this function are:

  • idCustomReminder is the ID for the reminder.
  • fEnabled indicates whether this reminder is enabled for the user.
  • iSendTo indicates who the reminder is sent to. There are three possible integer values:
    0 = send to self [project manager]
    1 = send to resource
    2 = send to both
  • sParams lists any user-saved parameters, for example: "1,2"
  • rsReminders is the reminder's record set.

Add the following code:

  case 100000:
    SetMgrReminder("T_100000", fEnabled, iSendTo, sParams);
    break;
SaveCustomReminders

This function is called in the SetSelfNotifications.asp and SetMgrNotifications.asp pages, located in the \Notifications folder of Microsoft Project Server, when a user saves her reminder settings. Add the following code:

  oPJQuery.Connect(true);

var rsCustomReminders = oPJQuery.OpenRecordset(const_PjQuery_GetMgrReminders, oPJSession.oUser.nUserID);
var fCheck, vParam1, vParam2, vSendTo;

var fCheck = Request.Form('T_100000_CHECK').Item;
var vParam1 = Number(Request.Form('T_100000_PARAM1').Item);
var vParam2 = Number(Request.Form('T_100000_PARAM2').Item);
vSendTo = Number(Request.Form('T_100000_OPTION').Item);
SaveMgrReminder(100000,rsCustomReminders, const_Type_3, fCheck, vSendTo, vParam1, vParam2);

oPJQuery.Disconnect();
GetCustomCriteriaByID

This function translates the parameters for the vPARAM1 and vPARAM2 properties set in the SaveCustomReminder function into meaningful criteria; for example: WDUE_ON < [today-1].

  case 100000:
    Criteria = "ASSN_FINISH_DATE <= [today] and ASSN_REM_WORK >0";
    break;
Validating the New Customized E-mail Reminder Option

After you complete the steps described above, you can use the new e-mail reminder option from the Set my e-mail notifications and reminders page on the Microsoft Project Web Access Home page. The reminder will be available the next time the notification and reminder service runs.