Project Server Events

Article
05/05/2014

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The Microsoft Office Project Server 2007 Eventing service provides a mechanism to extend Project Server by adding new business logic. Project Server raises pre-events and post-events when there are changes in business object data. When you associate an event handler with an event, Project Server executes the event handler when that particular event occurs. Windows SharePoint Services 3.0 stores the list of registered Project Server event handlers.

In earlier versions of Project Server, the only way to invoke custom code based on events was to use SQL Server triggers. To write triggers, you need an intimate knowledge of Project Server internals, and triggers can adversely affect system performance. As a result, partners and ISVs often have to write code for the earlier Project Server versions that replaces or circumvents Project Server functionality.

Server-side events provide the "hooks" that allow third-party developers to extend the Project Server platform with new functionality. Custom processes can include additional validation routines, data processing, notification services, and initiating and sustaining workflows. Server-side events make Project Server a viable platform for integration with line-of-business (LOB) applications and for custom solutions in enterprise project management.

Note
Because Microsoft Office Project Professional 2007 and Project Web Access sometimes call private PSI methods in the PWA and WinProj Web services, they do not always trigger the same events that the public PSI methods do. When you develop event handlers, test whether actions in Project Professional and Project Web Access, as well as in third-party applications that use the PSI, trigger event handlers as you expect.

Because Microsoft Office Project Professional 2007 and Project Web Access sometimes call private PSI methods in the PWA and WinProj Web services, they do not always trigger the same events that the public PSI methods do. When you develop event handlers, test whether actions in Project Professional and Project Web Access, as well as in third-party applications that use the PSI, trigger event handlers as you expect.

Eventing Architecture

The Project Server Architecture and Programmability topic describes the overall architecture of the Project platform and introduces Project Server events. The Project Server eventing architecture includes the following features:

The Eventing service is part of the core Shared Services Provider (SSP) application.
Business objects in the Project Server middle tier register events with the Event Manager in the Eventing service.
The Event Manager handles loading and execution of event handlers.
Project Web Access includes an event catalog that shows the Project Server events that are available and provides the user interface to register event handlers.
Project Web Access maintains event handlers in the associated Windows SharePoint Services 3.0 configuration database at the Project Web Access site level. The event catalog stores associations of Project Server events and event handlers.
You can have independent custom event handlers for each Project Web Access site that is hosted on the same SSP.

Note
Direct access to the SharePoint configuration database is not supported. Use Project Web Access (http://ServerName/ProjectServerName/_layouts/pwa/Admin/Events.aspx) or the PSI WebSvcEvents.Events methods to manage event handler associations.

Figure 1 shows the Project Server Eventing and Queuing services, which by default are started automatically.

Figure 1. Project Server services

Project Server services

Event Sources

An event source is typically a business object in the Project Server middle tier. Business objects (Project Server entities) are represented by Microsoft .NET Framework 2.0 classes. An event definition in a business object uses a delegate class to maintain a collection of methods that are called when the event occurs. The events are defined in terms of the related delegate.

Figure 2 shows the sequence of processes involved in managing and raising events.

Project Server creates an instance of a business object. The business object (event source) registers its events with the Event Manager.
The Event Manager queries the event catalog for associated events and event handlers.
If event handlers are available, the Event Manager creates an instance of the event receiver for the business object.
The event receiver is bound to the event source. Whenever the business object raises an event, it triggers the event receiver, which then runs the event handler.

Figure 2. Eventing architecture in Project Server

Eventing architecture in Project Server

Microsoft Office Project Professional 2007, Project Web Access, and third-party applications can raise server-side events when they interact with Project Server. Applications interact with Project Server by using the Project Server Interface (PSI). PSI calls invoke business objects, which are the event sources.

Event Catalog

The event catalog contains the registered events and event handler associations. If an event has an associated event handler, then the event catalog contains the following information:

Event source type: case-sensitive, fully qualified class name of the event type.
Event handler assembly: the strong name of the event handler assembly file that exists in the global assembly cache or bin directory
Event handler type: case-sensitive, fully qualified name of the event handler class in the event handler assembly.
Event handler method: case-sensitive name of the event handler method.

The event catalog is part of the Windows SharePoint Services configuration database. When a change occurs in the event catalog, Windows SharePoint Services refreshes the in-memory catalog on the application server. This means that you can add new event handlers and remove or deactivate existing event handlers without restarting the Project Server computer.

Important
The event catalog refresh is not immediate. There can be a latency of up to five minutes to refresh the in-memory event catalog. If the event catalog does not refresh, check whether the Windows SharePoint Services Timer service on the Project Web Access server is working properly.

Pre-Events and Post-Events

There are two types of events: pre-events and post-events. Business objects raise pre-events before saving data to the database. Event handlers can cancel an operation that raises a pre-event. Post-events cannot be canceled; business objects raise post-events after saving data changes in the database.

Project Web Access shows a list of events in the event catalog for each business entity. Figure 3 shows that you can expand the business entities such as LookupTable, Project, and Reporting to see their events.

Figure 3. Server Events page in Project Web Access

Server Events page in Project Web Access

For example, Project Publishing is a pre-event. You can stop a project from being published if an event handler determines that certain requirements are not met in your custom business rules for publishing projects. Project Published is a post-event and cannot be canceled; therefore, you cannot use Project Published to stop a project from being published. However, your Published event handler can start a workflow after a project is published.

For a list of all Project Server events, see PSEventID.

Event Handlers

Event handlers for Project Server are class library assemblies built on the .NET Framework 2.0. When you develop an event handler, you create a class that inherits from an event receiver class such as CubeAdminEventReceiver or ProjectEventReceiver. The base event receiver classes are all in the Microsoft.Office.Project.Server.Events namespace, which is in the Microsoft.Office.Project.Server.Events.Receivers.dll assembly installed on the Project Server computer.

If a Shared Service Provider hosts two or more Project Web Access sites, then you can have different custom event handlers for each site. Event handlers can run either synchronously or asynchronously using the .NET Framework threading services. Synchronous handlers execute on the same thread as the calling code. The calling method waits until the event handler returns control. Asynchronous event handlers are queued on a separate thread pool.

For more information about asynchronous programming, see Asynchronous Programming Overview in the MSDN Library.

Note
The Windows SharePoint Services 3.0 configuration database stores event handler information for each Project Web Access instance. Because direct access to the Windows SharePoint Services 3.0 configuration database is not supported, you should use the Events methods in the PSI to programmatically manage event handlers.

For information about developing, registering, and debugging a simple event handler, see How to: Write and Debug a Project Server Event Handler. For an example that changes e-mail using the NotificationsSending event, see How to: Customize E-Mail for Project Server Notifications.

Multiple Event Handlers

You can add more than one event handler to a Project Server event. When you register an event handler assembly and class using Project Web Access, you set the order of execution for that event handler. The order can be from 1 to 999.

Event Handler Failure

If an event handler fails when it is one of a series registered for a single event, the result depends on whether the event is a pre-event or post-event.

Pre-event If an event handler fails, the rest of the event handlers registered for the same event are not executed. The pre-event is effectively canceled.
Post-event If an event handler fails, the remaining event handlers registered for the same event are executed.

Event Data

Event handlers run in a separate application domain. An event source passes data when it calls the event handler. For example, an event handler for the OnPublishing pre-event overrides the Project object's base method for the event as follows.

public override void OnPublishing(PSContextInfo contextInfo, ProjectPrePublishEventArgs e)
    {
        base.OnPublishing(contextInfo, e);
        // implement business rules
        e.cancel = false;
    }

All events pass contextInfo, which includes the user's ID, name, and other data for authorization checks. Some events include additional data in the e parameter, such as a DataSet, a project ID, or other arguments in the PSI call that triggered the event. Some events consume data modified by an event handler; other events disregard modified data.

Note
To use a DataSet object in an event handler, you must set a reference to the Microsoft.Office.Project.Schema.dll assembly. The Microsoft.Office.Project.Server.Schema namespace includes the necessary class definitions such as CustomFieldDataSet. For the location of the schema assembly and a code example of an event handler that uses a DataSet object, see Using Datasets in Event Handlers in Getting Started with a New Platform for Developers.

To use a DataSet object in an event handler, you must set a reference to the Microsoft.Office.Project.Schema.dll assembly. The Microsoft.Office.Project.Server.Schema namespace includes the necessary class definitions such as CustomFieldDataSet. For the location of the schema assembly and a code example of an event handler that uses a DataSet object, see Using Datasets in Event Handlers in Getting Started with a New Platform for Developers.

The Microsoft.Office.Project.Server.Eventsnamespace includes event receiver classes along with the pre-event and post-event argument classes and event handler delegates. The event class descriptions show which events read changes in the event arguments and the properties that are available. The event arguments parameter is an object that is passed by reference. Therefore, even though the event handler returns void, the event source gets any changes the handler makes to the event arguments object. To find out what data are in the pre- and post-event arguments, check the properties in the event arguments classes. For example, the ProjectPublishing pre-event arguments include the all of the properties in the PreEventArgs, ProjectPreEventArgs, and ProjectPrePublishEventArgs classes.

Figure 4. Passing data between an event source and an event handler

Passing data between an event source and an event

Following is the general sequence of processes for an event handler:

Call a PSI method. The PSI method is an API for a Project Server business object, such as Project. For example, the Project.QueuePublish method includes projectUid as one of the arguments.
The business object (the event source) raises an event. For example, the QueuePublish method raises the ProjectPublishing event and determines if there are registered event handlers for that event.
The event source passes the PSContextInfo and event argument objects by reference to the registered event handler. For example, the Microsoft.Office.Project.Server.Events.ProjectPrePublishEventArgs object includes the ProjectGuid, ProjectName, and WssUrl properties. The ProjectPreEventArgs object adds the IsWorkingStore and ProjectDataSet properties, and all pre-events add the Cancel and CancelReason properties in the PreEventArgs object.
The event handler processes the custom business rules, and then it can call other processes and modify the event arguments.
If the event is a pre-event, the event handler determines whether the process should be canceled. If so, set the Cancel property to true in the event handler.
The event source checks the value of the Cancel property (if it is from a pre-event handler). If the pre-event is not canceled, the event source continues with the modified event arguments.

Project Server Events

Eventing Architecture

Event Sources

Event Catalog

Pre-Events and Post-Events

Event Handlers

Multiple Event Handlers

Event Handler Failure

Event Data

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources