Events for the RDB
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 Report Data Service (RDS) manages data transfer to the Reporting database (RDB) in Microsoft Office Project Server 2007. The RDS event model (the collection of Reporting events in Project Web Access) is the only way for third-party developers to extend the Project Server data model. This article groups the Reporting events by object type, and suggests appropriate uses for each event.
You can use Reporting events to react when Project Server data is created, updated, or deleted. Following are examples of actions that can be triggered by Reporting events:
Maintaining a cache of project data as it changes.
Obtaining additional data from other systems.
Passing project data to other systems.
Maintaining custom data views.
Extending project data security.
Automating reports on data changes.
Notifying subscribers with custom notifications.
To see the list of Reporting events in Project Web Access, click Server-Side Event Handler Configuration in the Operational Policies section of the Server Settings page (http://ServerName/ProjectServerName/_layouts/pwa/admin/admin.aspx). Events are listed by the event source, such as Admin, CubeAdmin, CustomFields, Project, and Reporting. Except for Reporting, event sources correspond to the major Project Server Interface (PSI) classes. As explained in PSI Methods for the RDB, there is no need for a Reporting PSI Web service.
For a list of all events, see PSEventID. For general information about events, see Project Server Events.
Designing Reporting Event Handlers
It is important to understand the behavior of Reporting events and the effects of making changes in the RDB when you are designing and developing event handlers.
Post-events All Reporting events are post-events. You cannot use post-events to cancel data arrival. If business logic must be enforced to prevent incorrect data (incorrectly coded, over budget, overdue, and so forth), then the logic should be placed in a pre-event where the action can be canceled.
Data stability Data stability in the RDB is not guaranteed by default, even when data access is taking place entirely within the context of the event. For example with the ReportingProjectChanged event, you can assume that there will be no other simultaneous ReportingProjectChanged events on the same project. However, it is possible that other events such as ReportingResourceDeleted, ReportingLookupTableChanged, and ReportingCustomFieldsDeleted can fire in parallel and create metadata operations in the RDB that update the same project data. If data stability is important, we recommend that you use Microsoft SQL Server 2005 with the Snapshot or Read Committed with Snapshot Isolation modes within the event code.
Blocking the queue The Reporting database is designed to help make access to relational data easier within server-side event code. Although you can make callbacks into the PSI, your event code should never wait for the result of a change. Events are fired synchronously; a wait blocks further activity on the correlation and ties up one of the limited number of Project Server queue threads.
Data changes Event code should never directly change data that arrives from the Published database. If data changes, then later synchronization messages can fail and lead to problems in the operational system. A failed message can block further activity on the object until the issue is resolved. If the event code needs to make data changes as a result of its validation, it should call back into the PSI.
Reporting Events
Reporting event names are organized by the object to which they apply.
Custom Fields and Lookup Tables
Reporting events for custom fields and lookup tables include the following:
ReportingCustomFieldChanged
ReportingCustomFieldCreated
ReportingCustomFieldDeleted
ReportingLookupTableChanged
ReportingLookupTableCreated
ReportingLookupTableDeleted
The custom field and lookup table Reporting events enable tracking of custom field and associated lookup table data. Lookup table data is stored in MSP_EpmLookupTable in the RDB. When a lookup table is used in a multivalue custom field, then the association data is stored in MSP_EpmCustomFieldAssociation. Association data represents the many:many relationship.
The RDB views that end with _UserView conceal the structure of the metadata tables from the query user. That is, you can make simple queries of the user views to access data for generating reports. You don't need to create complicated joins to get commonly used data from the user views.
.gif "Note") Note |
|---|
As an event code developer, remember that the user views can be out of date within the events if custom fields are being created, changed, or deleted. Rather than accessing data in the user views, you should directly access the other data tables through the metadata. |
The custom field data extensibility model is used to classify projects, tasks, assignments, and resources with additional data that can be used for a variety of business processes, such as the following:
Stage gating, where a project stage cannot be initiated or closed until certain actions occur, such as management approval.
Managing project proposals
Assigning costs to business areas
| Note |
|---|
In the current Project Server 2007 release, the RDS does not include timesheet custom fields. |
The server-side event model allows new uses for custom fields. You can use event code to enforce specific relationships. For example, all “Green” projects must have a location of “South”). The event code can replace large hierarchical custom fields that combine different lookup tables (such as South.Green or North.Blue).
The RDB can also store additional information relating to a specific code or code relationship. Additional information can often add value to business reports but is not needed for everyday project management.
Fiscal Periods
There are two Reporting events for fiscal periods.
ReportingFiscalPeriodChanged
ReportingFiscalPeriodDeleted
The MSP_TimeByDay table in the RDB contains data for the two time hierarchies supported by the Project Analysis cubes. By default, the fiscal time hierarchy is empty until you customize it in Project Web Access. For an example, see the Fiscal Periods page (http://ServerName/ProjectServerName/_layouts/pwa/Admin/FiscalPeriod.aspx).
Fiscal dates (FiscalYear, FiscalQuarter, FiscalPeriodName) reflect corporate dates rather than calendar dates. The fiscal period Reporting events enable extensions to adapt cached data to fiscal period changes.
Projects and Resource Plans
Reporting events for projects and resource plans include the following:
ReportingProjectChanged
ReportingProjectCreated
ReportingProjectDeleted
The project Reporting events occur when projects are published. Custom event handlers enable the following types of applications.
Communication of project data changes with external systems.
Maintenance of additional data related to a project that is not owned by or held in the operational system. An application can use the data to generate additional OLAP cubes or custom cubes, or simply enhance the reports that are run against the RDB.
Signaling of changes in resource plan data. Through the ReportingProjectChanged event, resource plan data arrives as nonbudget resource assignment data for the project’s summary task.
Windows SharePoint Services Data
Reporting events for Windows SharePoint Services data include the following:
ReportingProjectWorkspaceChanged
ReportingProjectWorkspaceCreated
ReportingProjectWorkspaceDeleted
The three lists that are associated with each project workspace are the following, by default:
Issues
Risks
Deliverables
The lists are synchronized with the RDB whenever a project is published or by explicit invocation of the QueueSynchronizeProjectWorkspace method. The RDB does not replicate list customizations, such as the addition of a column to the Project Issues list. The project workspace Reporting events enable replication of customized lists.
Note
Direct database access to the SharePoint schema is not currently supported and should be avoided. You can use the rich SharePoint object model as well as a security context for administrative access to project workspace Web sites. You can also use the SharePoint Web services.
Resources and Calendar Data
Reporting events for resources and calendar data include the following:
ReportingResourceCapacitiesChanged
ReportingResourceCapacityTimeRangeChanged
ReportingResourceChanged
ReportingResourceCreated
ReportingResourceDeleted
Resources have three sets of attributes:
Core data (name, account number, and so forth)
Custom field data (such as Location or RBS value)
Capacity (calendar) data
The resource Reporting events enable changes to resources to be handled. The ReportingResourceChanged event flags changes in the resource core data and custom field data. The ReportingResourceCapacitiesChanged event flags resource calendar changes. For example, you can create an extension of the RDB to include Human Resources (HR) data for reporting, where the HR data is not needed elsewhere in Project Server.
| Note |
|---|
You can also use the AdminAdSync events for creating RDB extensions. |
Event handler code can consume the ReportingResourceCapacityTimeRangeChanged event to manage the amount of historic capacity data that is retained in the RDB.
Timesheet Data
Reporting events for timesheet data include the following:
ReportingTimesheetAdjusted
ReportingTimesheetClassCreated
ReportingTimesheetDeleted
ReportingTimesheetPeriodChanged
ReportingTimesheetPeriodCreated
ReportingTimesheetPeriodDeleted
ReportingTimesheetSaved
ReportingTimesheetStatusChanged
The timesheet system is a key addition to Project Server 2007. The RDB can be an important source of timesheet data for third-party applications. Although timesheet messages are processed on a separate queue from other messages, the queue is transparent to event developers.
In its lifecycle, each timesheet goes through one or more of the states shown in Figure 1. The TimeSheetCreated and TimeSheetDeleted events are not shown on the diagram. A timesheet is created before time is entered into the timesheet; timesheet deletion removes the timesheet data from the system. The RDB contains only timesheets that have been opened and saved. Most timesheet data arrives in the RDB after the ReportingTimesheetSaved and TimeSheetSubmitted events.
Figure 1. Timesheet state changes
.gif "Timesheet state changes")
Timesheets maintain their own copies of Project, Task, and Resource names to retain timesheet fidelity over time. This metadata is collected when the timesheet is saved.
In addition to the ReportingTimesheetSaved and ReportingTimesheetAdjusted events, which occur when timesheet data arrives, there are several metadata events. ReportingTimesheetClassCreated can be used to obtain external data related to the timesheet line classes. For example, information such as class owners, budgets, and other cost data can be used for extended financial reporting by using timesheet data.
Timesheet periods represent the time reporting periods that govern each timesheet. The timesheet period Reporting events can be used to validate the expected minimum and maximum number of hours in each timesheet, which is beneficial for exception reporting.
The ReportingTimesheetSaved messages capture changes in the state of a saved timesheet (Figure 1).
Changes in Reporting Views
ReportingUserViewChanged is the Reporting event for changes in the UserView tables.
SQL Server limits any one view to 1024 columns. The ReportingUserViewChanged event becomes relevant when the number of custom fields exceeds the number of columns that you can return in the *_UserView view definitions. You can use the ReportingUserViewChanged event to generate additional views. You can also modify the default views to swap in or swap out columns.
You can use the ReportingUserViewChanged event to manage changes to data replication schemes. For example, where Project Server data is being replicated into a central reporting system, the replication scheme can be synchronized with the changing view structure.
Other Downstream Events
Following are additional events that are downstream of (occur after) the Reporting events.
CubeAdminCubeBuilding
CubeAdminCubeBuilt
CubeAdminCubeProcessed
The Cube Build Service fires these events each time the Project Server 2007 Data Analysis cubes are built. Report developers can run multiple reports within the CubeAdmin events against an unchanging set of project and resource data in the Reporting database. The queue service does not process any RDS messages between the CubeAdminCubeBuilding and CubeAdminCubeProcessed events. An alternate method of obtaining a transactionally consistent view of the Reporting database is to use the SQL Server 2005 Snapshot Isolation Level within the report suite.
For more information about the CubeAdmin events, see CubeAdminEventReceiver.