Project Server 2007: Getting Started with a New Platform for Developers

  • Article

Summary: Explore Microsoft Office Project Server 2007 functionality that uses a completely new platform built on Microsoft .NET Framework 3.0 and Windows SharePoint Services 3.0. Use the Project Server Interface (PSI) and Project Server events to extend and integrate Project Server with other applications. Extend Project Web Access, now a Windows SharePoint Services 3.0 site. Learn about the new Reporting database and Cube Build Service. (23 printed pages)

Jim Corbin, Microsoft Corporation

August 2007

Applies to: Microsoft Office Project Professional 2007, Microsoft Office Project Server 2007, Microsoft Office SharePoint Server 2007, Microsoft Windows SharePoint Services 3.0, Microsoft Visual Studio 2005, Microsoft SQL Server 2000 SP4, Microsoft SQL Server 2005 SP1

Contents

  • Introduction to Project Server 2007

  • Project Documentation – Where to Find What You Need

  • Using VBA

  • Project Server Architecture

    • Accessing Project Server Data

    • Caching, Queuing, Events, and Server-side Scheduling

  • Integration with Windows SharePoint Services

    • SimpleUI URL Options

    • Project Workspaces

    • Workflow

  • Project Server Interface

    • Datasets

    • Impersonation and Extensions for the PSI

    • Comparison with the PDS

  • Project Server Events

    • Using Datasets in Event Handlers

  • EPM Reporting

    • Reporting Database and the Report Data Service

    • Cube Build Service

  • Checking Errors

  • Conclusion

  • Additional Resources

Introduction to Project Server 2007

Microsoft Office Project Server 2007, the third major release of Project Server, is an entirely new platform for developers. To the question, "What's new in Project Server 2007?" the answer is, "Everything!" That is, everything about Project Server development is new, for very good reasons that are explained in this article. The features that help make Project Server the premiere enterprise project management (EPM) system improve on the great features of earlier versions. Project Server 2007 is built upon the productive, feature-rich code framework and the set of application services in Microsoft .NET Framework 3.0 and Windows SharePoint Services 3.0. Project Server 2007 achieves the following goals for programmability:

  • Great extensibility   Project Server 2007 addresses the key areas for extension of features for EPM and integration with 2007 Microsoft Office system products, partner solutions, and line-of-business (LOB) applications.

  • Development platform   The Project Server Interface (PSI) set of Web services, Project Server Eventing service, Project Server Queuing service, server-side scheduling engine, and common Windows SharePoint Services Features such as workflow and custom lists, create a complete development platform.

  • Low barrier to entry   Developers familiar with Microsoft Visual Studio, standard Web Parts in Windows SharePoint Services, or Microsoft SQL Server Reporting Services can quickly take advantage of related functionality of the Project Server development platform, without learning the proprietary XML-based interface of earlier versions.

  • Improved developer productivity   The PSI Web services use Microsoft ADO.NET 2.0 typed DataSet objects. Microsoft IntelliSense in Visual Studio immediately shows the methods, parameters, and fields available in a code statement. Using the PSI, you no longer need to program directly against the Project Server databases to access data such as timephased task information.

  • Firewall friendly   All client applications, including Microsoft Office Project Professional 2007, communicate with Project Server through the PSI Web services using the HTTP and SOAP protocols. You can work easily and securely with Project Server by using a separate Project Web Access server in a perimeter network for access across the Internet.

Project Server 2007 offers many advantages and improvements. This article introduces you to the platform programmability and refers to in-depth conceptual and "how to" articles in the Project 2007 SDK.

Project Documentation – Where to Find What You Need

There are four major avenues of Project documentation, each of which is designed to reach a different audience. Because you are reading this article, you are probably a developer. However, you will at times also need end-user, administrator, support or Knowledge Base (KB) information, and other Project downloads. You can also install the Microsoft Office Interactive Developer Map to help find documentation for all of the 2007 Microsoft Office System products and technologies.

Developer Documentation

Following are the main parts of the Microsoft Office Project 2007 SDK:

  • The Project Developer Portal includes links to the main parts of the Project 2007 SDK as well as developer information for earlier versions. The Project 2007 Resource Center page in the portal includes links to new articles and Webcasts for Project 2007. The Project Community page includes links to Project blogs, newsgroups, and other information about Project partners and Microsoft Most Valued Professionals (MVPs).

  • The online Welcome to the Microsoft Office Project 2007 SDK includes current conceptual, how-to, and walkthrough topics, as well as reference topics for the PSI Web services and related datasets and Project Server programming libraries. On each page of the online SDK you can find a Community Content section where you can post comments, short code samples, or correct errors in the page. Community Content is a WIKI for MSDN; for developer community discussions and help with questions, you can use the Project Developer newsgroup.

  • The Project 2007 SDK download includes the complete SDK with a searchable HTML Help file, source code for sample applications, database references, and XML schema references.

  • The Project VBA reference and help topics are online in the Project 2007 Developer Reference and also offline in Visual Basic Help when you are working in the Visual Basic Editor. You can access updated help topics for VBA if you click the Connection Status menu in the bottom right of the Project Help window and then click Show content from Office Online. For example, the VBA object model maps (such as the Application and Projects Object Map) are available only through online help.

  • The Technical Articles section of the online Project 2007 SDK currently has only one article—this one. Future versions of the SDK will contain additional articles.

The Project 2007 SDK is currently available only in English.

Administrator (IT) Documentation

The place to look for information about Project installation, migration, and administration is on Microsoft TechNet:

End-User Documentation

Context-sensitive help is available within Project Standard and Project Professional. As with VBA Help, to get updated content, click the Connection Status menu in the bottom right of the Project Help window, and then click Show content from Office Online. When you are using Project Web Access, for context-sensitive help, click the Help icon in the upper right corner of the page.

For online access to all current Project Help topics, see the following:

Support Documentation and KB Articles

The Microsoft Customer Service and Support (CSS) team maintains the Knowledge Base (KB) with many how-to and troubleshooting articles for Project 2007.

NoteNote

For a list of topic categories for the KB articles, along with links to the search and RSS feed pages, see Microsoft Office Project 2007 (http://support.microsoft.com/ph/11381).

All new KB articles are immediately machine-translated to Japanese, French, Spanish, and German. Currently, 81 KB articles are localized (hand-translated) into major languages. The CSS team created 79 KB articles and updated an additional 114 of 418 legacy KB articles for the release of Project 2007.

The Project 2007 support page includes a link for e-mail, online, or phone support from Microsoft.

You can ask questions and find answers to many questions in the newsgroups. To access the newsgroups through your browser, see MSDN Newsgroups (http://msdn.microsoft.com/newsgroups/). You can also access the newsgroups using Windows Mail (in Windows Vista) or Outlook Express (in Microsoft Windows XP). Following are the three public newsgroups for Project:

  • microsoft.public.project

  • microsoft.public.project.developer

  • microsoft.public.project.server

Downloads

You can find all downloads for Project by searching the Microsoft Download Center.

To find all Project 2007 downloads:

  1. Go to Microsoft Download Center, click the arrow next to the magnifying glass next to the search box, and then click Advanced Download Search.

  2. In the Keywords box, type Project 2007.

  3. In the Product/Technology box, select Microsoft Project.

  4. Keep the Category and Release Date boxes set to All.

  5. In the Sort Results By list box, select the sorting option you prefer.

  6. Click Go.

To extend the search to include other products, keep the Project 2007 keywords and set the Product/Technology list box to All. For example, you can then find the Microsoft Office Visio 2007 WBS Modeler.

Documentation for Other Office Products and Technologies

You can integrate Project 2007 with other 2007 Microsoft Office System products to create a wide variety of Office Business Applications. To easily find developer and other documentation for those products, install the Microsoft Office Interactive Developer Map.

Figure 1 shows the main page of Microsoft Office Interactive Developer Map application. The Interactive Developer Map includes relationships of all of the Microsoft Office client and server applications, Windows SharePoint Services 3.0 features, and related development tools and services. After you install the Interactive Developer Map, you can click any item to see a page for that product or feature with links to online documentation.

Figure 1. Microsoft Office Interactive Developer Map

Microsoft Office Interactived Developer Map

Using VBA

Although this article focuses on Project Server 2007, the Visual Basic for Applications object model in Project Standard and Project Professional is very widely used. You can use VBA to automate the Project desktop clients with simple macros as well as integrate Project with the other 2007 Microsoft Office system applications to create comprehensive business solutions.

Macros and custom toolbars To deploy a macro to a group of Project Professional users, you can copy the macro to the enterprise global template in Project Server. You can then create a custom toolbar, copy that to the enterprise global, and reference any required files in the macro by using a SharePoint site. For more information and an example, see Changes for Custom Project Guides.

Automating Project using Visual Studio Microsoft Visual Studio 2005 Tools for the Microsoft Office system - Second Edition (VSTO 2005 SE) and the Project 2007 primary interop assembly provide advantages for developing more complex, secure, and scalable solutions that automate the Project 2007 desktop clients and other Microsoft Office applications. The next release of Visual Studio 2008 Professional Edition includes templates for developing application-level add-ins for Project 2003 and Project 2007 (the Project Standard and Project Professional versions). Visual Studio 2008 with Visual Studio Tools for Office 3.0 and ClickOnce publishing greatly simplifies developing, testing, and deploying advanced solutions that include the Project desktop client.

For an overview of changes for VBA developers in Project 2007, see VBA Object Model Changes. For more information about Visual Studio Tools for Office, see the Office Development with Visual Studio Developer Portal on MSDN. For a detailed example of a Project 2007 add-in developed with Visual Studio 2008, see Importing Project 2007 Tasks from Excel Using a Managed Code Add-In.

Project Server Architecture

The architecture of Project Server 2007 is multitiered. The presentation tier includes Project Web Access, Project Professional 2007, and third-party client applications. The application services tier includes the PSI Web services, the business logic, and Windows SharePoint Services 3.0. The data tier includes the Data Access Layer (DAL) components and multiple SQL Server databases. Figure 2 shows a simplified view of the Project Server architecture.

Figure 2. Project Server 2007 architecture

Project Server 2007 architecture

Project Server supports multiple virtual sites of Project Web Access. You can install one or more instances of Project Web Access on the same computer as the Project Server core components, or on separate computers within the same SharePoint server farm. Each instance of Project Web Access uses the same core Project Server and other shared services, but separate databases. For example, the following two Project Web Access virtual sites require a total of eight Project Server databases and share the configuration and content databases of Windows SharePoint Services.

  • http://ServerName/ProjectServer/

  • http://ServerName/Sample/

In the previous examples, ProjectServer and Sample are names of the Project Web Access virtual sites. Each Project Web Access virtual site has its own independent list of authorized users stored in the Windows SharePoint Services content database. Project Server databases no longer store user logon information. The ProjectServer site, for example, uses the databases named ProjectServerDraft, ProjectServerPublished, ProjectServerArchive, and ProjectServerReporting. The Sample site uses the independent databases named SampleDraft, SamplePublished, SampleArchive, and SampleReporting. You can install the databases on different computers running Microsoft SQL Server 2000 SP4, Microsoft SQL Server 2005 SP1, or a later version.

Project Web Access is now built with ASP.NET 2.0 and uses compiled assemblies that interact with Project Server through the PSI. Developers do not have access to the code behind the Web Parts and ASPX pages in Project Web Access, as they did with earlier versions that used ASP pages. However, you can access the Windows SharePoint Services object model and create your own Web Parts that interact with Project Server Web Parts. The code in your extensions is not exposed to other developers.

Project Web Access uses Windows SharePoint Services for authentication and as a Web server. For more information about how Project Web Access works with the PSI when it is installed on a separate computer, see Project Server Architecture in the Project 2007 SDK.

Accessing Project Server Data

Project Professional 2007 and all third-party applications communicate with Project Server 2007 only through the PSI. In earlier versions of Project Server, Project Professional used ODBC for direct access to most Project Server databases. ODBC cannot be used through most corporate firewalls. Project Server 2007 eliminates the need for direct database access, except for the Reporting database. The Reporting database can be installed on a computer running SQL Server, separate from the other Project Server databases.

Eliminating direct database access solves many programming problems in addition to the problem of access through firewalls. For example, when Project Professional and a third-party application both access an earlier version Project Server database, they can use different business logic and damage the referential integrity of database tables.

Important noteImportant

Nothing actively prevents you from using direct programmatic database access to update data. You should be aware that the Project Professional cache, the Publishing database, and the Reporting database all rely on a cache synchronization protocol that can be disrupted by direct data editing. If you damage your Project Server databases or corrupt Project Professional client-side caches by using direct access to change data, be warned that product support will not be able to help.

The PSI is the interface between your application and the Business Object layer. Business objects in Project Server are the components that include the rules for how logical entities such as Project, Task, Resource, and Assignment can be changed and how they interact with each other and with the other Project Server components. Each logical entity can span multiple database tables. Because all client applications go through the PSI and use the same business logic, Project Server maintains the correct relationships between the business objects. The business objects do not directly interact with the Project Server databases; they call the DAL, which handles transactions with the correct database tables.

Caching, Queuing, Events, and Server-side Scheduling

The local cache in Project Professional 2007, along with the Project Server Queuing service, enables offline work and reduces the time needed to open and save projects. When a project manager reconnects after working offline, Project Professional sends a message to the Project Server Queue and saves only the changed data. The Project Server Queue handles saving the data asynchronously, and the project manager can exit Project Professional or get back to work.

The Project Server Eventing service is the key to extending Project Server functionality. Developers can create event handlers and register them programmatically with methods in the Events Web service or through Project Web Access. Each major business object (CustomFields, CubeAdmin, LookupTable, Project, Reporting, Security, TimeSheet, and so forth) includes multiple events that you can see on the Project Web Access Events page (http://ServerName/ProjectServerName/_layouts/pwa/admin/Events.aspx). Event handlers provide "hooks" for adding new functionality, customizing existing functionality, and integrating with other applications. For some examples, see Project Server Events in this article.

Earlier versions of Project Server did not have a scheduling engine. When a team member reported a different amount of time than what was scheduled for a task, for example, the project manager had to open the project in Project Professional to reschedule the task and its dependents. Project Server 2007 can now reschedule tasks. For example, you can implement a custom timesheet system and Project Server can reschedule projects without requiring the data to make a round trip through Project Professional.

NoteNote

The public methods in the PSI support the most common and useful requirements for managing server-side projects and integration with other applications. The PSI does not address all of the functionality of Project Professional or Project Web Access.

For more information, see Project Server Architecture in the Microsoft Office Project 2007 SDK. For information about what you can and cannot do with the PSI, see Project Server Programmability.

Integration with Windows SharePoint Services

Project Server 2007 requires Windows SharePoint Services 3.0. Windows SharePoint Services handles user authentication and is the foundation for all Project Web Access features including site administration, Project Server Web Parts such as Project Center and My Tasks, and project workspaces that include lists of issues, risks, deliverables, and related documents.

NoteNote

Although Windows SharePoint Services handles both Windows and Forms authentication for Project Server users, the Security business object in Project Server (with programmatic access through the PSI Security Web service) handles permissions and user authorization. For more information, see the Project Server Security Primer.

Project Web Access and Windows SharePoint Services 3.0 are built with the .NET Framework 3.0 and use ASP.NET 2.0 for Web page development. You can develop Web Parts for Project Web Access just as you can for other SharePoint sites, because Project Web Access is a SharePoint site (cheers)!

Microsoft Office Project Server 2003 included six Project Server Web Parts that you could use only with Windows SharePoint Services 2.0 sites. You could change Project Web Access views into Web Parts, but you could not modify a Project Web Access ASP page with Web Parts. Project Server 2007 includes 25 general and specialized Project Server Web Parts, and you can easily make more, such as Web Parts from SQL Server Reporting Services or custom Web Parts that communicate with other Project Server Web Parts. For more information about custom Web Parts, see Project Server Web Parts.

NoteNote

You can add Project Server 2007 Web Parts to other SharePoint sites if they are within the same server farm as Project Server. Project Server 2007 does not need to provision the SharePoint sites.

Project Web Access also supports legacy Windows SharePoint Services 2.0 Web Parts, .ascx custom controls, and other extensibility features of ASP.NET 2.0. We recommend that you build ASP.NET 2.0 Web Parts where possible, for compatibility with both Windows SharePoint Services 3.0 and other ASP.NET 2.0 applications that are not hosted by Windows SharePoint Services.

You can add Web Parts to Project Web Access pages that include the Edit Page option in the Site Actions menu. Some pages, such as Proposals and Activities and the Server Settings pages, are designed for specific functionality and do not allow you to edit the page. However, Project Web Access administrators can use the Quick Launch link on the Server Settings page to add sections and links to custom pages on the Quick Launch. Figure 3 shows how easy it is to add Web Parts to editable Project Web Access pages. Simply click Edit Page on the Site Actions menu, and then click Add a Web Part in the page section you want.

Figure 3. Adding a Web Part in the edit mode of a Project Web Access page

Adding a Web Part in the edit mode

Windows SharePoint Services 3.0 uses master pages to control the look and feel of Web pages within a site. You can change the master pages for Project Web Access to incorporate your organization's branding and terminology. You can modify master pages with Microsoft Office SharePoint Designer 2007 and then add them to the Master Page Gallery (click Site Settings on the Site Actions menu). Your custom Web Parts can call PSI methods or third-party applications.

SimpleUI URL Options

Project Web Access pages still implement SimpleUI URL options to hide or show various parts of the page, although these options are reduced. In Project Server 2007, the SimpleUI setting is persisted as a cookie on the local user's computer. SimpleUI applies globally to the Project Web Access pages, but not to other Windows SharePoint Services sites that do not have Project Server provisioning. For example, the following URL removes the Project Web Access top link bar and breadcrumb bar:

http://ServerName/ProjectServer/default.aspx?SimpleUI=5

Now all the pages have the same elements removed, and you no longer see the SimpleUI option in other pages. To temporarily return to the default view for the current page, add ?SimpleUI=0 to any Project Web Access URL. To persist the default view on all pages, add ?SimpleUI=16. Unlike the 256 combinations of SimpleUI in earlier versions, Project Server 2007 uses only 32 bitmask combinations (0 through 31). For more information about URL options and developing custom Web Parts, see Project Server Web Parts in the Microsoft Office Project 2007 SDK.

Project Workspaces

When you create and publish a project, by default you also create a project workspace site for team collaboration. For example, the default workspace site for a project named My Test Project is the following:

http://ServerName/My%20Test%20Project/default.aspx

You can specify other servers running Windows SharePoint Services or project site names within the same farm when you use Project Professional or the PSI to create and publish projects. Project workspaces can include lists of documents, issues, risks, and project deliverables. Deliverables are a new feature in Project Server 2007. A project manager can publish tasks or milestones as a list of deliverables, and other project managers can subscribe to that list to get notifications of changes in dates. Publishing or subscribing to deliverables does not affect task scheduling on either project, but serves as a way to improve collaboration between projects.

A deliverable list is an example of a specialized SharePoint list. The Microsoft Windows SharePoint Services 3.0 SDK provides examples of how to develop custom lists. For more information, see the SharePoint Server Developer Center.

For more information about customizing project workspaces, see Extending the Project Workspace Template.

Workflow

The Windows Workflow Foundation (WF) is a Windows–based platform component that is hosted by Windows SharePoint Services 3.0. WF is a development framework, not a server or application, which provides a common workflow technology for Microsoft products, ISVs, and customer solutions. Workflows can run in any application or server—including, of course, Project Server 2007.

The WF download includes extensions to Microsoft Visual Studio 2005 for Workflow project types and a visual designer for graphical and code-based authoring. Windows SharePoint Services 3.0 also includes simple workflows that you can configure using Office SharePoint Designer 2007.

For more information about WF, see . NET Framework Developer Centerand the Visual Studio 2005 extensions for .NET Framework 3.0 (Windows Workflow Foundation) download. For more information about Project Server 2007 integration, see the following articles in the Microsoft Office Project 2007 SDK: Project Server Programmability and Integration with Office SharePoint Server 2007.

NoteNote

The current released version of WF is part of the .NET Framework 3.0. Future versions of Visual Studio will include several templates that make it easier to create workflows. For more information, see Visual Studio Developer Center.

Project Server Interface

The PSI is a set of 19 public Web services. The LoginWindows and LoginForms Web services are used to log on Project Server through the Project Web Access URL. The other 17 Web services correspond to Project Server business objects (that is, logical entities such as Project and Resource). The PSI has a Project Web service for the Project entity, a Resource Web service for the Resource entity, a TimeSheet Web service for the TimeSheet entity, and so forth. Each PSI Web service includes one or more DataSet objects that handle data for that entity. Most PSI Web methods either use a DataSet parameter or return a DataSet object. For example, the QueueCreateProject method in the Project Web service sends a message to the Project Server Queue to create a project in the Draft database with the data specified in the ProjectDataSet parameter. The jobUid parameter allows you to track and manage the job in the queue by using methods of the QueueSystem Web service.

public void QueueCreateProject(Guid jobUid, ProjectDataSet dataset, 
   bool validateOnly);

The ReadProject method reads the specified project in a specified database and returns a ProjectDataSet object. All entities are identified in Project Server by a GUID.

public ProjectDataSet ReadProject(Guid projectUid, 
   DataStoreEnum dataStore);

You specify a Web reference to the PSI Web description file by using a subdirectory in the Project Web Access virtual Web site. For example, use the following URL to reference the Project Web service, where ProjectWebAccessName is the name of the Project Web Access virtual site.

http://ServerName/ProjectWebAccessName/_vti_bin/PSI/Project.asmx

In Visual Studio 2005, after you type a namespace for the Web reference, the wsdl.exe utility generates the Microsoft Visual C# or Microsoft Visual Basic 2005 files that compile to a Web service proxy assembly for your application. You use the Web service by creating an instance of the class and any DataSet objects you need. For example, if you set a reference to the Project Web service and name it WebSvcProject, the following code gets information about a specific project in the Published database. The last statement in the SaveProjectInfoToXml method uses the inherited WriteXml method to serialize the ProjectDataSet to an XML file.

using System;
namespace Demo
{
  public partial class Info
  {
    . . .
    // Initialize a Project object that contains the PSI Web methods.
    public static WebSvcProject.Project proj = new 
       Demo.WebSvcProject.Project();

    // Not shown here: log on to Project Server, then set user 
    // credentials, logon cookie, and URL for the Project object.

    public SaveProjectInfoToXml(Guid projectUid, string filePathName)
    {
      WebSvcProject.ProjectDataSet dsProject = 
         new Demo.WebSvcProject.ProjectDataSet();
      dsProject = proj.ReadProject(projectUid, 
         Demo.WebSvcProject.DataStoreEnum.PublishedStore);
      dsProject.WriteXml(filePathName);
    }
  }
}
NoteNote

In most cases, you do not need to serialize a DataSet object to a file because it stays in memory within the application. The example shows that ProjectDataSet is a first-class object that inherits methods, properties, and events from the base DataSet class.

For a complete sample application using the PSI, see How to: Log on to Project Server Programmatically in the Microsoft Office Project 2007 SDK.

Datasets

Every PSI Web service includes the DataSet classes it needs that correspond to information in the business entities used by the Web methods. A DataSet object is essentially an in-memory relational database. Each DataSet object contains one or more DataTable objects that contain DataRow objects, and each DataRow includes one or more properties (data fields) as well as methods. For example, the ProjectDataSet class includes classes such as AssignmentDataTable, DependencyDataTable, ProjectCustomFieldsDataTable, ProjectDataTable, and TaskDataTable. The ProjectDataSet class also includes the classes AssignmentRow, DependencyRow, ProjectCustomFieldsRow, ProjectRow, and TaskRow.

There are many advantages to using datasets with the PSI, as follows:

  • ADO.NET 2.0 datasets have improved performance with binary data over the network.

  • Developers who have experience with ADO.NET already know how to program datasets.

  • Data is in a relational model with tables, rows, and relationships.

  • Datasets have type safety: an incorrect type does not compile.

  • IntelliSense for datasets provides design-time validation.

  • Datasets include methods to easily serialize and deserialize the data to support offline scenarios such as mobile devices and development using unmanaged code.

For example, if you create and publish a test project that contains nothing but a name (no tasks, resources, custom fields, or other data), the WriteXml method in the previous sample code serializes the ProjectDataSet object to a file with the following content.

<?xml version="1.0" standalone="yes"?>
<ProjectDataSet xmlns="http://tempuri.org/ProjectDataSet.xsd">
  <Project>
    <PROJ_UID>3b91f68b-de5a-4dcf-8a42-78bfea542e52</PROJ_UID>
    <PROJ_NAME>Test Project 1</PROJ_NAME>
    <PROJ_TYPE>0</PROJ_TYPE>
  </Project>
</ProjectDataSet>

To create or update a ProjectDataSet object for use with a PSI method such as QueueCreateProject or QueueUpdateProject, you can programmatically assign data to fields in the ProjectDataSet.ProjectRow, or deserialize XML data in a file or stream from another device or system by using the ProjectDataSet.ReadXml method.

The PSI and datasets provide a flexible and efficient development environment for Project Server 2007. For a detailed introduction to using the PSI and datasets, and for an explanation of how to use the Class Library and Web Service Reference and related assemblies, see Project Server Interface (PSI) Overview in the Microsoft Office Project 2007 SDK. For information about an extensive sample application that uses the PSI, see Using the ProjTool Test Application. The Project 2007 SDK download includes the ProjTool source code.

Impersonation and Extensions for the PSI

Each PSI Web service has two URLs, as follows.

  • A virtual URL through Project Web Access is accessible to applications running on external computers. For example, the virtual URL of the Project Web service is http://ServerName/PWAName/_vti_bin/psi/project.asmx. When an application user calls a PSI method through the virtual URL, the call is restricted by the user's Project Server permissions, just as they are in Project Web Access.

  • A local URL is accessible only to applications or components running on Project Server. Applications that use the local URL can run with impersonation. The local URL is provided through a Shared Services Provider (SSP) in Windows SharePoint Services. For example, if the Office Server Web Services port is 56737 and contains an SSP named SharedServices1 that hosts Project Web Access, then the local URL for direct access to the Project Web service is http://ServerName:56737/SharedServices1/psi/project.asmx.

A component that integrates Project Server with an LOB application typically requires elevated privileges for creating projects or it must impersonate a user for updating timesheets. The Project 2007 SDK download includes three sample applications that use impersonation: a simple console application, a Web application, and a Windows application named ProjTool. For more information, see Using Impersonation in Project Server.

You can extend the PSI itself with additional Web services. Methods in custom PSI Web services can call other PSI methods, for example, to check user authorization, use impersonation for specific jobs, consolidate multiple PSI calls on the server to save network traffic, and add new functionality to Project Server. For a simple Web service example named HelloWorldPSI that also calls the ReadResource PSI method, see Walkthrough: Creating a PSI Extension. The URLs of the PSI extension work just like any PSI Web service; for example, http://ServerName/PWAName/_vti_bin/psi/helloworldpsi.asmx is the virtual URL through Project Web Access and http://ServerName:56737/SharedServices1/psi/helloworldpsi.asmx is the local URL for direct calls through the SSP using impersonation.

Comparison with the PDS

In earlier versions of Project Server, many third-party applications used the Project Data Service (PDS) to read and update Project Server data. Probably just as many additional applications programmed directly to the single Project Server database because the PDS provided only about 80 percent of the functionality needed for writing Project Server extensions or integrating with external applications. The PDS did have some advantages over direct database access: it had built-in support for Project Server security and it was the supported Project Server API. However, to get functionality the PDS did not support, developers had to write PDS extensions that usually used direct database access.

The PDS in Project Server 2003 has 67 methods, including the four methods of the Service for Enterprise Data Maintenance, which aggregates several PDS methods. By comparison, the PSI in Project Server 2007 has about 300 public methods. With the PSI and datasets, you do not need to directly access the Draft, Published, or Archive database; in fact, except for the Reporting database, you are very strongly urged to refrain from direct database access.

There is no 1:1 relationship between PDS and PSI methods. For example, the single PSI method ReadProject returns a ProjectDataSet object that includes data equivalent to all of the following PDS methods: ProjectsStatus, ProjectsVersion, ProjectCodeValues, and ProjectData. Some PDS methods have no PSI equivalent, such as ProjectsAccess and ResourcesAccess; Project 2007 security is based on the .NET Framework 2.0 security model and uses Windows SharePoint Services authentication.

NoteNote

In most cases, applications written for earlier Project Server versions cannot be ported directly to Project Server 2007, but require re-architecting to use the PSI.

The advantages of the new Project Server platform going forward bring many fresh opportunities for customization, extension, and integration that were not feasible with the PDS in earlier versions.

The PDS Parity in PSI Web Services section in the Microsoft Office Project 2007 SDK includes several articles and a table of PSI methods equivalent to PDS–based code, along with examples. For information about security categories, templates, groups, and permissions, see the Project Server Security Primer.

Project Server Events

Every Project Server 2007 business entity (Project, Task, Assignment, CustomField, Timesheet, and so forth) includes events. Project Server implements more than 160 events, including both pre-event and post-event types. Pre-events occur before Project Server saves data to the database. Pre-events can cancel the operation and are synchronous. That is, an application that uses a pre-event cannot continue until the event handler is finished. Post-events cannot be canceled (the data is already saved), and can be asynchronous or synchronous. Applications can subscribe to events such as the Project Publishing pre-event or the Project Published post-event and run one or more associated event handlers. When you register the event handler in Project Web Access, you can specify the order in which Project Server runs multiple event handlers for one event.

Pre-events enable developers to add constraints, custom data validation, or business rule checks. For example, a corporate project management office (PMO) might require that all enterprise project text custom fields for certain projects have a two-letter prefix. A CustomField Changing pre-event handler could implement the business rule.

Post-events are the main way to integrate Project Server with an LOB application, such as an accounting system. For example, there are 14 TimeSheet events including Submitting, Submitted, Recalling, and Recalled. The Submitting and Recalling events are pre-events. You can create event handlers that check your organization's business rules before a timesheet is submitted to the database, and cancel the submission if the rules are not met. The Submitted and Recalled events are post-events. After a project manager submits timesheet data, a Timesheet Submitted post-event handler could send the weekly data to an accounting system.

When you create a class for a Project Server event handler, it inherits from an event receiver base class in the Microsoft.Office.Project.Server.Events.dll assembly. Event receiver classes include ProjectEventReceiver, CustomFieldsEventReceiver, and so forth. You can create one or more event handler methods in your class. Each event handler method overrides an event handler in the base class. For example, a CustomFieldsEvents class can include the OnCreating and OnCreated methods. The following code includes two event receiver classes with several event handlers.

using System;
using System.Diagnostics;
using System.Data;
using System.Xml;
using Microsoft.Office.Project.Server.Events;
using PSLibrary = Microsoft.Office.Project.Server.Library;

namespace TestEventHandlers
{
    public class ProjectEvents : ProjectEventReceiver
    {
        public override void OnPublishing(
            PSLibrary.PSContextInfo contextInfo, 
            ProjectPrePublishEventArgs e)
        {
            . . .
        }
    }
    public class CustomFieldsEvents : CustomFieldsEventReceiver
    {
        public override void OnCreating(
            PSLibrary.PSContextInfo contextInfo, 
            CustomFieldsPreEventArgs e)
        {
            . . .
        }

        public override void OnCreated(
            PSLibrary.PSContextInfo contextInfo, 
            CustomFieldsPostEventArgs e)
        {
            . . .
        }
    }
}

Event handler methods include context information such as the user name and GUID, language, and Project Web Access site GUID. The pre-event arguments parameter includes the Cancel property along with other information about the entity or event. For example, ProjectPrePublishEventArgs for the ProjectOnPublishing event handler includes the project name, GUID, and the SharePoint site URL for the project workspace. The post-event arguments parameter does not include the Cancel property.

Using Datasets in Event Handlers

The event arguments parameter in both pre-event and post-event handlers can include a DataSet for the entity, if the related PSI method uses a DataSet object. For example, the event arguments parameter for the CustomField OnCreated event handler includes CustomFieldInformation of type CustomFieldDataSet.

NoteNote

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.

You can copy the schema assembly from C:\WINDOWS\assembly\GAC_MSIL\Microsoft.Office.Project.Schema\12.0.0.0_71e9bce111e9429c, if you first run the following command.

regsvr32 /u C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727\shfusion.dll

After you copy the schema assembly, run the regsvr32.exe command without the /u option to reregister shfusion.dll and show the default assembly view in Windows Explorer. The following code shows a simple post-event handler that uses CustomFieldInformation for the custom field Created event. In the expression e.CustomFieldInformation.CustomFields.Rows[0]["MD_PROP_NAME"].ToString(), CustomFields is a DataTable object in CustomFieldInformation—which itself is of type CustomFieldDataSet. The table has only one row (Rows[0]), which contains data for the just-created custom field. For a list of properties in a custom field row, see CustomFieldDataSet.CustomFieldsRow Properties in the Microsoft Office Project 2007 SDK.

public override void OnCreated(
    PSLibrary.PSContextInfo contextInfo, 
    CustomFieldsPostEventArgs e)
{
    // Create an EventLog instance and assign its source.
    EventLog myLog = new EventLog();
    myLog.Source = "Custom Field OnCreated Event Handler";

    // Get information from the event arguments, and 
    // write an entry to the Application event log. 
    string userName = contextInfo.UserName.ToString();

    string cfName = e.CustomFieldInformation.CustomFields.Rows[0]["MD_PROP_NAME"].ToString();
    byte cfTypeEnum = (byte)e.CustomFieldInformation.CustomFields.Rows[0]["MD_PROP_TYPE_ENUM"];
    Guid cfUid = (Guid)e.CustomFieldInformation.CustomFields.Rows[0]["MD_PROP_UID"];

    string[] cfTypes = Enum.GetNames(typeof(PSLibrary.CustomField.Type));

    string cfType = "";
    int index = 0;

    foreach (int i in Enum.GetValues(typeof(PSLibrary.CustomField.Type)))
    {
        if (i == Convert.ToInt32(cfTypeEnum))
        {
            cfType = cfTypes[index];
            break;
        }
        index++;
    }

    int eventId = 3652;
    string logEntry;

    logEntry = "User: " + userName +
        "\nCustom Field Name: " + cfName +
        "\nGUID: " + cfUid.ToString() + 
        "\nType: " + cfType +
        "\nThe custom field has been created.";

    myLog.WriteEntry(logEntry, EventLogEntryType.Information, eventId);
}

If you compile and register the event handler and then create a resource custom field named Test Res Duration of type Duration, you can see the following Application event in the Event Viewer for the Project Server computer.

Figure 4. Using CustomFieldInformation to show properties in an event handler

Using CustomFieldInformation to show properties

Datasets in event handlers are for read-only use. For example, you cannot modify the CustomFieldDataSet to change the name of a custom field within the OnCreating event handler. However, you can trap the event, get the properties you need, cancel creation of the custom field, and then use the CreateCustomFields method in the CustomFields Web service to create a custom field with the correct name.

For more information, see Project Server Events. For an example that includes instructions for registering event handlers, see How to: Write and Debug a Project Server Event Handler.

EPM Reporting

The desktop clients Project Professional 2007 and Project Standard 2007 include major improvements in creating reports from local Project files, using the Visual Reports feature with Microsoft Office Visio 2007 and Microsoft Office Excel 2003 or Excel 2007. On the server side, the platform for EPM reporting is a major upgrade in Project Server 2007 that supports the Microsoft Business Intelligence (BI) framework. The purpose of the BI framework is to help provide timely and relevant business insight to all employees. The reporting infrastructure in Project Server includes the Reporting database (RDB), the Report Data Service (RDS), and the Cube Build Service (CBS).

Reporting Database and the Report Data Service

The default RDB tables and views are designed to be read-only for generating reports from essentially all project data. There are three core RDB schemas:

  • EPM data

  • Timesheet data

  • Collaboration data (issues, risks, and deliverables on SharePoint sites)

The RDB is updated in near real time (within a few minutes) from changes in the Published database. The RDB tables are de-normalized to make it relatively easy to create reports by using SQL Server Reporting Services.

The RDS handles updates to the RDB with a queue and can manage multithreaded update operations from multiple servers. Users can likely see changed data in Project Web Access before it arrives in a report from the RDB. The RDS includes post-events for data updates, so you can manage the reporting cache and update reports after the necessary data is present.

Views in the RDB include both OLAP and user views, for example, resource data is available in MSP_EpmResource_OlapView and in MSP_EpmResource_UserView. The OLAP views are designed for use by the Cube Build Service in generating the OLAP cubes. The user views generally include more fields than the OLAP views and are designed for creating reports. Sample queries in the Project Server Report Pack use tables as well as user views.

You can add tables and views to the RDB that include external data and use the RDS to manage updates of custom tables and views. The Project 2007 SDK includes examples of how to create and manage reports using the Business Intelligence Development Studio for Microsoft SQL Server Reporting Services (SSRS) 2005.

The SDK download includes the Report Pack with seven sample SSRS reports, the Reporting database schema reference (pj12_Reporting.chm), and Visio diagrams of the EPM, timesheet, and SharePoint collaboration schemas. For more information about the RDB and the Report Pack, see Using the Reporting Database.

Cube Build Service

The CBS creates multiple OLAP cubes from Project Server and related Windows SharePoint Services data. Project Web Access includes much-improved management of SQL Server Analysis Services cubes, supports customization of the cubes, and has a centralized location for Reporting Services reports that use the OLAP cubes or the RDB. You can add enterprise custom fields as new dimensions or measures, and add calculated measures to the cubes, all through Project Web Access.

In addition to Project Web Access administration, the CBS has extensive event and trace logging and the PSI CubeAdmin Web service enables programmatic management and scheduling of cube building. The OLAP database for Project Server 2007 includes 14 default cubes (rather than the one cube in earlier versions):

  • Project non-timephased

  • Task non-timephased

  • Assignment non-timephased, Assignment timephased

  • Resource non-timephased, Resource timephased

  • Timesheet, EPM Timesheet

  • Windows SharePoint Services cubes: Risks, Issues, and Deliverables

In addition, there are three virtual cubes that combine data:

  • Combine the Assignment timephased, Resource timephased, and EPM Timesheet cubes

  • Combine data from the Project non-timephased cube with data from the Windows SharePoint Services cubes (Risks, Issues, Deliverables)

  • Portfolio Analyzer cube, combines the Assignment timephased and Resource timephased cubes for backward compatibility with reports in earlier versions

You can build the default OLAP cubes by using incremental data changes to allow greater frequency and shorter duration of updates. Views of cube data are available in Project Server Web Parts. You can create additional views and custom Web Parts that combine Project Server and external data. For example, you can use Excel 2007 with improved PivotTable reports and conditional formatting; and, if your Project Server farm includes Microsoft Office SharePoint Server 2007, you can publish the Excel workbooks or spreadsheets to Excel Services for thin rendering on any Windows SharePoint Services site. For more information about the OLAP cubes and how to extend them, see Cube Build Service.

Office SharePoint Server 2007 includes a centralized Report Center with rich collaboration capabilities. Team members can easily create Key Performance Indicators (KPIs) that monitor data trends. Administrators or developers can use the Business Scorecard Manager to create scorecard elements, views, and roles and publish updates of Project Server data to Microsoft Office PerformancePoint Server 2007.

For an example that shows how to extend the Portfolio Analyzer cube, see How to: Calculate Resource Availability in OLAP Cubes. For information about how to add custom fields as dimensions or measures in cubes, see Custom Fields and OLAP Cubes in Local and Enterprise Custom Fields.

For more information about the Microsoft Business Intelligence suite and where to get a trial version of the Business Scorecard Manager, see Business Intelligence.

Checking Errors

When you are developing solutions for Project Server, you can check two main areas for configuration and run-time errors: the application event log and Unified Logging Service (ULS) trace logs.

  • **Application event log   **On the Start menu on the Project Server computer, click Run, and then type eventvwr. In the left pane of the Event Viewer window, click Application to see the events logged by Project Server, Windows SharePoint Services, ASP.NET, SQL Server, custom event handlers, and other applications. The Project Server event sources include ProjectQueueService and pjevtsvc.

  • ULS   The Unified Logging Service (ULS) trace logs can be more detailed than the application event log. You can configure a ULS trace log to record specific or all categories and levels of activities in Project Server and Windows SharePoint Services. To view the trace logs, you can use Notepad or another text editor, Microsoft Office Excel, or the Log Viewer add-in feature for Windows SharePoint Services. The Log Viewer add-in is available from CodePlex SharePoint 2007 Features.

    To configure the ULS trace log for a specific Project category:

    1. Open the SharePoint 3.0 Central Administration application, click Operations, and then click Diagnostic logging in the Logging and Reporting section.

    2. In the Event Throttling section, select a specific category such as Project Server - Server-Side Events. If you select Project Server - General, all 25 Project categories are logged.

    3. Select the Verbose level for the least critical event to report in the trace log.

      Caution noteCaution

      Because trace logs can be large in size, run verbose logging only when you need it. If you are reporting events on a production server, select only a specific category to keep the size of the log manageable. To turn off all logging, select the empty category and None for the trace log least critical event. To record relatively few events, select High or Monitorable.

    4. Use the default path for the trace logs, for example, C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\LOGS\. If you use the Log Viewer add-in for Windows SharePoint Services, it looks for trace logs in the default path.

    5. Set the maximum number of log files to maintain. The default number of log files is 96.

    6. Set the number of minutes to use a log file. The default number of minutes is 30. That is, ULS tracing creates a new log file after 30 minutes. Log files include the date and time in the file name, for example, SERVERNAME -20070424-1612.log.

    To use the Log Viewer add-in:

    1. Download and install the Log Viewer feature from CodePlex SharePoint 2007 Features. For the list of downloads, see the Releases tab. The release notes include installation instructions.

    2. The Log Viewer is a global feature. After it is installed, click Operations on the Central Administration page, and then click View Unified Logging Service in the Utilities section.

    3. On the Unified Logging Service (ULS) Logs page (Figure 5), select a file to view, and then select the Project Server category. This category shows all of the specific categories such as Project Server Queue, Project Server Server-Side Events, Project Server Reporting, and so forth.

    4. To see all events in the ULS log, don't make a selection. The trace severity drop-down list is blank by default. If you select Verbose, the log shows only the verbose level events.

    5. Click Go.

    Figure 5. Log Viewer add-in showing a ULS log for Project

    Log Viewer add-in for SharePoint showing ULS log

    NoteNote

    For information about adding custom events to the ULS logs, see Trace Logs.

Conclusion

Microsoft Office Project Server 2007 is a state-of-the-art platform based on the latest programming and software collaboration frameworks—the .NET Framework and Windows SharePoint Services—which will be the basis of Microsoft Office Project and other Microsoft software programs for many years to come. The Project Server platform makes it easier to develop extensions and integrate with a wide variety of other applications.

The Project Server Interface (PSI) replaces the PDS of earlier Project Server versions. The PSI and related datasets eliminate the need to directly access the three core Project Server databases (Draft, Published, and Archive). Project Server events are the key to extending Project Server and integrating with LOB applications. Event handlers can start workflows, workflows can make PSI calls, and other event handlers can send messages to workflows.

Project Server reporting and OLAP cubes are part of the extensible Project platform and provide customers and partners many opportunities to improve project management, communication, and business decisions in organizations.

Additional Resources

For more information, see the following additional resources. These resources include duplicates of SDK topic references and external links found in this document: