Project Server Programmability
Applies to: Office 2010 | Project 2010 | Project Server 2010 | SharePoint Server 2010
In this article
Project Server and SharePoint Server
General PSI Features
Project Server Events
Project Scheduling on the Server
About Accessing the Project Server Databases
Microsoft Project Server 2010 is designed to support high levels of programmer productivity by building on Microsoft SharePoint Server 2010 and the Microsoft .NET Framework 3.5. Developers can extend the Project Web App user interface with Web Parts developed with Microsoft ASP.NET 3.5, define workflows using Windows Workflow Foundation, and enforce business rules using Project Server events and the Web services of the Project Server Interface (PSI).
This article describes the general programmability features of Project Server, in the following sections:
Project Server and SharePoint Server
Customization of Project Web App
Workflow Engine
General PSI Features
Types of APIs
Porting Applications Built for Project Server 2003
Porting Applications Built for Project Server 2007
Project Versions
Project Server Events
Project Scheduling on the Server
About Accessing the Project Server Databases
Project Server and SharePoint Server
Project Web App is built upon SharePoint Server 2010, and uses master pages and Web Parts to make it easier to build custom Project Web App solutions. SharePoint Server 2010 also provides core infrastructure services for Project Server such as administration, security, the reporting center using Excel services, and common workflow activities. Microsoft SharePoint Foundation 2010 hosts the Windows Workflow Foundation run-time engine.
Project Server 2010 integrates deeply with SharePoint Server 2010 as the platform for project collaboration, reporting, site administration, and workflow management. The project sites include specialized SharePoint lists for tracking issues, risks, project deliverables, and the team calendar, along with the document library and team discussions. Project Server 2010 provides flexibility for team collaboration; for example, you can locate project sites anywhere within the SharePoint server farm where Project Server is installed. To use other core services of SharePoint Server 2010, such as Excel Services and Enterprise Search, an administrator needs to enable and configure the services.
Project Server 2010 installation also provisions the Project Service Application in the SharePoint Web Services site, which includes the local ASMX Web services and Windows Communication Foundation (WCF) services for the PSI. Service applications in SharePoint Foundation 2010 replace the Shared Service Provider in Windows SharePoint Services 3.0. The change enables third-party developers to create custom service applications using the Service Application Framework. In addition to the Project Service Application, other examples of service applications include SharePoint Search and SharePoint Document Management. For more information, see the SharePoint Server 2010 SDK.
The Project Service Application is a logical service provider that handles one or more instances of Project Web App. Project Server provisioning creates a specific Project Web App site within a Web application. Project Web App contains the Project portal pages (Project Center, Resource Center, Report Center, and so on). For an illustration of the Microsoft Internet Information Services (IIS) view of the Project Service Application for a typical installation, see Overview of WCF and the PSI.
Customization of Project Web App
The Site Settings page in Project Web App (https://ServerName/ProjectServerName/_layouts/settings.aspx) enables changing the look and feel, site theme, adding custom Web Parts, and modifying or creating master pages for project site.
You can add Web Parts and use the built-in Web Part editing functionality in Project Web App pages that enable the use of Web Parts. However, customization of the ASPX pages themselves is not supported. Customization of the code in Project Web App pages can cause problems with Project Server updates and service packs.
Note
Project Web App is a SharePoint application. However, customization of the code in Project Web App master pages using Microsoft SharePoint Designer 2010 is not supported. You can customize the master pages of project sites.
The Site Actions menu in Project Web App is in part a generic menu for SharePoint applications. The Edit in SharePoint Designer command is not supported on Project Web App pages.
Workflow Engine
Windows Workflow Foundation (WF) is a Microsoft .NET Framework 3.0 technology. The WF run-time engine hosted in SharePoint Foundation 2010 is the workflow engine for SharePoint Server 2010 and is also part of the core Project Server platform.
Integrated workflow solutions help to automate an organization's business processes and can provide tracking, auditing, and alerts. Examples of workflow solutions include change management and demand management systems, specialized timesheet applications, and integration with other LOB applications such as customer relationship management.
SharePoint Foundation 2010 builds on the WF platform introduced in Windows SharePoint Services 3.0, and adds the following features:
New workflow activities, which are the building blocks of all workflows.
Pluggable workflow services enable workflows to interact with external sources.
New workflow pre- and post-events. For example, one workflow can call another workflow and wait for it to finish or respond to an error.
Workflow event receivers can be registered with a specific SharePoint site, list, or content type, to limit the scope.
WF provides an extensible workflow run-time engine that enables partners, ISVs, and customers to build custom business workflow solutions (workflows) on Project Server. Project Server adds workflow activity and integration classes in the Microsoft.Office.Project.Server.Workflow namespace. Developers can create custom workflows using Microsoft Visual Studio 2010.
Note
Microsoft SharePoint Designer cannot create Project Server workflows. To develop Project Server workflows, you must use Visual Studio 2010 on a computer that has Project Server installed. See Developing Project Server Workflows.
For more information about SharePoint workflows, see Building Block: Workflows in the SharePoint Foundation 2010 SDK.
General PSI Features
The Project Server Interface (PSI) enables all client applications, including Project Professional 2010, Project Web App, and back-end LOB applications, to access Project Server data. The PSI is built and programmed with the Microsoft .NET Framework 3.5 and provides all of its advantages, such as ease of development, security, error handling, and garbage collection.
Types of APIs
All of the PSI is accessed through ASMX Web services or WCF services. In Project Server 2010, ASMX is based on WCF. Each PSI service typically contains a base class with "CRUD" methods that create, read, update, and delete items within that class. Items are specified by related DataSet classes. For example, the CustomFields service contains the CustomFields class with methods such as CreateCustomFields. Data for one or more enterprise custom fields are specified in the CustomFieldDataSet.
The PSI contains three general kinds of APIs:
Generic APIs that expose the Project Server functionality with an emphasis on ease of use and organization for third-party developers. These APIs are well-documented. There are 22 generic services in the PSI, with base classes such as Project, PortfolioAnalyses, and TimeSheet. In addition, the LoginForms service provides generic methods for programmatic Project Server logon and logoff using Forms authentication.
Project-specific APIs that are geared for performance or special purposes such as upgrading from Project Server 2007 and synchronizing with Microsoft Exchange Server. The Project-specific APIs may combine or batch multiple API calls. The Authentication, ExchangeSync, P12Upgrade, PWA, and View services are designed specifically for use by Project Web App and Project Professional.
APIs that are limited to use only by Project Professional. The WinProj class includes methods with parameters that can contain large amounts of binary data.
Project Web App and Project Professional use the generic PSI services as well as the limited and Project-specific APIs.
Note
The Authentication, ExchangeSync, P12Upgrade, PWA, View, and WinProj services are not documented or supported for third-party development. These interfaces can change in service packs or later versions of Project Server.
The PSI is factored to match the business objects. That is, each PSI method is associated with a business object such as Calendar or Resource. The PSI is the interface to the business objects. Because the business layer provides reusable business logic components, different applications that interact with Project Server data use the same business logic. The PSI helps to solve the problems in Project Server 2003, where developers sometimes had to re-implement Project Server business logic in PDS extensions.
Each PSI method is implemented with a separate interface that interacts with the client by using strongly typed data. For example, the QueueCreateProject method in the Project service accepts the dataset parameter of type ProjectDataSet. The ProjectDataSet class is derived from the DataSet type. Type checking in the .NET Framework and Intellisense completion in Visual Studio help to reduce errors in development with the PSI.
Project Server 2010 uses exception handling of the .NET Framework. All errors are logged in the server, at the top of the PSI stack. Some errors send a simple report to the client, such as a SoapException object that is recorded in the application event log, and some errors also record a detailed report on the server in the Unified Logging Service (ULS) trace logs.
The PSI is also extensible. You can add a .NET assembly with its own Web service that provides new functionality, uses the same Project Server security infrastructure, and calls other PSI methods or inherits from PSI classes. A PSI extension also needs to provide the business logic and database access needed for the new functionality.
For an introduction to the detailed reference for PSI namespaces, classes, methods, properties, events, and related assemblies, see PSI Reference Overview.
Porting Applications Built for Project Server 2003
In Project Server 2003, much data and functionality is available only with Project Professional 2003 or by direct database access. The PSI, introduced in Project Server 2007, removes much of that restriction. Unlike the Project Data Service (PDS) in Project Server 2003, the PSI provides a comprehensive interface to business objects in Project Server.
Applications developed for the Project Data Service (PDS) in Project Server 2003 are not compatible with Project Server 2010. The PSI provides functional parity for the PDS, but does not match PDS methods or parameters. To port a PDS application to Project Server 2010, you must do the following:
Set a WCF reference or set an ASMX reference to each PSI service you need. For applications that do not need to run on the Project Server computer, you can set an ASMX reference through the Project Web App URL. For example, to use the Resource service, set a reference to https://ServerName/ProjectServerName/_vti_bin/psi/resource.asmx?wsdl.
For all new applications, and for applications that use impersonation or middleware components that run only on the Project Server computer you should use a WCF service reference. For more information, see Prerequisites for WCF-Based Code Samples.
Change all PDS calls to PSI calls
Change the processing of PDS XML requests and replies to processing of the PSI DataSet objects and other parameters.
The PSI does not support PDS extensions that were built for Project Server 2003, because those extensions usually use direct database access. For more information about PDS compatibility and guidelines for porting PDS extensions, see PDS Parity in PSI Web Services.
Porting Applications Built for Project Server 2007
The PSI in Project Server 2010 is a superset of the PSI object model in Project Server 2007. Most applications built for Project Server 2007 continue to work in Project Server 2010. However, applications that use impersonation, or middleware components that run on the Project Server computer, need some changes. For more information, see Migration and Compatibility of Custom Solutions in Overview of WCF and the PSI.
Project Versions
Project Server 2003 used project name extensions for different versions of a project. To keep track of project versions in Project Server 2010, you can do following:
Create a Version custom field and lookup table, available through the CustomFields and LookupTable PSI Web services, to access project level metadata.
Use task-level publishing flags and project-level availability settings to control the impact of a project on the organization.
Project Server Events
In Project Server 2003 and earlier versions, SQL Server triggers are the only way to invoke custom code based on events. Triggers require knowledge of Project Server internal processes, and can reduce system performance. Project Server 2010 provides public events that enable development of custom processes such as adding and enforcing business rules, validation, data processing, notification services, and workflow. Server-side events greatly increase the value of Project Server as a development platform.
The Project Server eventing platform includes the Project Server Eventing Service and a Project Web App administration page for viewing a list of events and registering application event handlers. With the Project Server eventing platform, developers can:
Extend Project Server functionality with custom event handlers and associate them with events raised by Project Server.
Send data to other applications or receive data from applications using event handlers.
Cancel a Project Server process, with a pre-event handler that implements custom business logic.
Associate multiple event handlers with an event, and determine the sequence of execution.
Invoke workflows and send or receive messages from a workflow.
Client applications can raise server-side events when they interact with Project Server 2010. Clients can interact with Project Server through the PSI and through the workflow platform in SharePoint Foundation 2010. PSI calls invoke business objects that act as event sources. Third-party developers can also override base abstract classes for event handlers. The assembly needs to make only the class name, not the method name, available to the Project Server eventing platform. The implementation class also enables type checking when registering an event handler and during run time.
Project Server does not provide transactions across an event. To help insulate the core Project Server process from badly written event receivers, all event receivers run in a different application domain than Project Server. Event handler crashes do not affect the Project Server process. It is the developer's responsibility to manage exceptions, perform cleanup, and maintain data consistency if an exception occurs.
Project Scheduling on the Server
In general, Project Server scheduling works the same way as scheduling in Project Professional. However, there are a few differences and limitations in server-side scheduling.
Changing the active status of a task The Project Server scheduling engine can show inconsistent start or finish times when you use the QueueUpdateProject method to change the active status of a task, if there are multiple changes in the ProjectDataSet object for the dataset parameter. If the TASK_IS_ACTIVE property is the only change in the dataset parameter of QueueUpdateProject, you can update the project.
For more information about inactive tasks and Project Server scheduling, see the blog articles, Introducing Inactive Tasks in Project 2010 and Project Server 2010: Scheduling on the Web, the PSI and Project Professional. For a comparison of scheduling in Project Professional 2010 and Project Web App, see Web-Based Schedule Management Comparison.
Earned value not calculated The scheduling engine on Project Server does not calculate the earned value fields: ACWP, BAC, BCWP, BCWS, CPI, CV, CV%, EAC, SPI, SV, SV%, TCPI, VAC, Duration Variance, Start Variance, Finish Variance, Cost Variance, and Work Variance. If a project has values for these fields and the project is updated on the server, the field values do not change. However, you can duplicate some of the earned value fields by using custom fields, such as the variance fields. The Project Server scheduling engine does update custom fields.
Single project scheduling only Project Server schedules only the current project, when changes are made through task status updates, changing projects with the PSI, or with Project Web App. If the current project has links to other projects, subprojects, or master projects, the linked projects are not changed.
You can handle the server-side scheduling limitations in the following ways:
Open projects in Project Professional and save them back to Project Server.
In reports, do not include fields that are not updated by Project Server.
Add a note in reports about data that may be stale.
There are flags in the Reporting database and the cubes that allow you to detect when some project data is not updated. For information, see the MSP_EpmProject table in the Reporting database schema reference (ProjectServer_ReportingDB.chm in the Project 2010 SDK download).
ProjectWbsIsStale Indicates whether the work breakdown structure (task outline hierarchy) is stale.
ProjectEarnedValueIsStale Indicates the earned value fields are stale.
ProjectRollupsAreStale Indicates that a subproject is updated in the Draft database, but the master project is not updated. The rolled-up values from the subproject are stale.
ProjectHierarchyNotSynchronized The master project is not synchronized with its children. That happens when the child projects are published explicitly, not as part of the master project publishing.
ProjectCalculationsAreStale Project Professional saved a project without calculating the schedule (that is, the calculation mode is set to Manual on the Schedule tab in the Project Options dialog box).
ProjectGhostTaskAreStale Similar to ProjectHierarchyNotSynchronized, but warns on cross-project link data. It is possible that no master project exists, but the project data on one side of the link is newer than on the other side.
Following are the other differences between the way scheduling works in Project Server and in Project Professional:
Roll-down of actuals Project Server 2010 and Project Professional 2010 both roll down actual values for material resource assignments to the material resources. In contrast, Project Server 2007 rolls down actuals for material resource assignments to work resources.
Summary tasks Summary tasks are generally read-only on Project Server. For example, assignments for summary tasks cannot be created, and percent completion cannot be modified. However, Project Server does support editing the dates and duration of manually scheduled summary tasks.
Actuals on Project Server are not added automatically to a summary task assignment, because that would bypass the approval process in Project Server. In Project Professional, when you add actuals to a subtask, the actuals are also added for an assignment for the summary task. The difference in behavior can be confusing for a user.
Project Server deletes actuals on a summary task assignment if the subtask duration shortens or the finish date is changed. Project Professional 2010 changes the roll down of actuals and addition of actuals to summary task assignments to match the behavior of Project Server.
Warning
Although Project Professional can do it, we recommend that you do not make assignments on summary tasks.
Inactive tasks Project Server cannot deactivate or reactivate tasks.
Outline numbers Project Server does not calculate task outline numbers.
WBS values Project Server does not update work breakdown structure values.
Resource overallocation Project Server does not correctly calculate values for the overallocated flag.
About Accessing the Project Server Databases
Developers are strongly discouraged from directly accessing the Draft, Published, or Archive Project Server database through Microsoft SQL Server queries. Making direct changes in the Project Server database tables can damage referential integrity and interfere with database access through the Project Server Queuing Service.
Important
There is nothing to actively prevent 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 won't be able to help!
Applications that directly access the Draft, Published, or Archive database also are dependent on the database schemas, which can change in service packs or later versions of Project Server 2010. Furthermore, applications that directly access the databases lose the built-in Project Server security, common business logic, tracking, audits, error checking, reporting, workflow, and other features. You would likely need to rewrite such an application for Project Server 2010 updates.
For all of these reasons, Project Professional and Project Web App do not make direct calls to the Draft, Published, or Archive database; neither should any other application that integrates with Project Server.
Note
In Office Project Server 2007, you can create custom global and category permissions by modifying security tables in the Published database. The Walkthrough: Creating and Using Custom Project Server Permissions article is the only SDK example where an exception is made for changing the Published database. In Project Server 2010, that process for creating custom permissions is obsolete. As an alternative, you can create custom permissions by using claims augmentation. For more information, see Claims Provider.
The Draft, Published, and Archive database schemas are not documented. You can use the Reporting database to help generate reports, and the Reporting database schema is documented in the Project 2010 SDK download. You can also extend the Reporting database to include external data for integrated reporting solutions.
See Also
Concepts
Project Server 2010 Architecture
What the PSI Does and Does Not Do
Workflow and Demand Management
Other Resources
Developing Project Server Workflows
Project Programming References
PDS Parity in PSI Web Services
Introducing Inactive Tasks in Project 2010
Project Server 2010: Scheduling on the Web, the PSI and Project Professional