Project Server Programmability

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.

Microsoft Office Project Server 2007 is designed to support high levels of programmer productivity by taking advantage of Microsoft .NET Framework, Microsoft Office SharePoint Server 2007 components, and Windows SharePoint Services 3.0. Developers can extend the Project Web Access user interface with Web Parts developed with Microsoft ASP.NET 2.0, define automatic 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 Windows SharePoint Services

Workflow Engine

General PSI Features

PDS Compatibility

Usage Scenarios for the PSI

What the PSI Does Not Do

Project Scheduling on the Server

About Accessing the Project Server Databases

Project Server Events

Project Server and Windows SharePoint Services

Project Web Access is built upon Windows SharePoint Services 3.0, and uses master pages and Web Parts to make it easier to build custom Project Web Access solutions. Windows SharePoint Services 3.0 also provides core infrastructure services for Project Server such as administration, security, and the Windows Workflow Foundation run-time engine.

Project Server 2003 uses Windows SharePoint Services 2.0 to save lists of issues and risks, and to manage the document library that is associated with each project Web site. Project Server 2007 integrates much more deeply with Windows SharePoint Services 3.0 as the platform for project collaboration. Project collaboration includes specialized lists for issue and risk tracking and the new project Deliverables feature, along with the document library and the ability to convert SharePoint task lists to Proposals and Operations projects. Project Server 2007 provides more flexibility for team collaboration; for example, you can locate project workspaces anywhere within the SharePoint server farm where Project Server is installed.

Project Server 2007 installation also installs and provisions Windows SharePoint Services 3.0 and the other core services of Office SharePoint Server 2007, such as Enterprise Search and administration. Project Server is a shared service that is associated with a Web application instance. The Project shared service is a logical service provider across all Windows SharePoint Services 3.0 servers that handle one or more instances of Project Server 2007. Project Server provisioning creates a specific Web site within a Web application instance that contains the Project portal pages (Timesheet Center, Project Center, and so on). For an illustration of the Microsoft Internet Information Services (IIS) view of the shared service, application pools, and Web application instance for a typical installation, see Finding the PSI Web Services.

The Shared Service Provider uses a separate application pool in IIS. When both Project Server and Office SharePoint Server 2007 are installed, the Office SharePoint Server 2007 Web services virtual Web site includes the following shared services:

• Excel Calculation Services (installed with Office SharePoint Server 2007)

• PSI (the Project Server Interface is the Project Server shared service)

• Enterprise Search (installed with either Project Server or Office SharePoint Server 2007)

The Project Server shared service is a wrapper that groups the middle-tier business logic and the databases for a particular instance of Project Server. If a server farm contains two shared resource application pools, there are two instances of the Project Server shared service. A Project Server shared service is fundamentally a management and scale boundary with the advantages of easier management and greater scalability. For example, a team can create a workspace around related projects that contains aggregations of list data from the projects and Project Web Parts that look across projects. PSI methods in Project Server can also create Project workspaces cross-farm to improve performance when accessing project documents over a WAN.

Workflow Engine

The Windows Workflow Foundation run-time engine hosted in Windows SharePoint Services 3.0 is the workflow engine for Office SharePoint Server 2007 and is also part of the core Project Server platform.

Windows Workflow Foundation is a Microsoft .NET Framework 3.0 technology; Windows SharePoint Services 3.0 implements several provider components for the hosting environment. Windows Workflow Foundation provides an extensible workflow run-time engine that enables partners, ISVs, and customers to build custom business workflow solutions (workflows) on Project Server and Office SharePoint Server 2007. The Office SharePoint Server 2007 product includes some sample workflows for document management, such as the Enterprise Content Management (ECM) review workflow. If Office SharePoint Server 2007 is available, Project Server enables the Project Proposal approval workflow. System administrators and developers can create additional workflows using Microsoft Office SharePoint Designer 2007 or Microsoft Visual Studio 2005.

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 proposal management systems, specialized timesheet applications, and integration with other LOB applications such as customer relationship management. Customers can customize Project Server workflows to support their business requirements.

For more information about Office SharePoint Server 2007, see Integration with Office SharePoint Server 2007. For more information about workflow solutions, see Developer Introduction to Workflows for Windows SharePoint Services 3.0 and SharePoint Server 2007 and the Enterprise Content Management Starter Kit provided in the Office SharePoint Server 2007 SDK.

General PSI Features

The Project Server Interface (PSI) enables all client applications, including Project Professional 2007, Project Web Access, and back-end LOB applications, to access Project Server data. The PSI is built and programmed with the Microsoft .NET Framework 2.0 and provides all of its advantages, such as ease of development, security, error handling, and garbage collection.

In Project Server 2003, much data and functionality is available only with Project Professional 2003 or by direct database access. The PSI 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 2007, such as Project, Resource, Calendar, Custom Field, Security, and Timesheet.

Types of APIs

All of the PSI is accessed through Web services. Each PSI Web service typically contains a base class with several to many methods plus related DataSet classes. 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 18 generic Web services in the PSI, with base classes such as Project, Calendar, and Resource. In addition, the LoginForms and LoginWindows Web services provide generic methods for programmatic Project Server logon and logoff.

• Project-specific APIs that are geared for performance and usually target Project Web Access features. They may combine or batch multiple API calls. The project-specific APIs are available through the Shared Service Provider URL, but have only the public methods documented. The Authentication, PWA, and View classes are designed for specific Project Web Access and Project Professional use.

• 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. Only the public methods of these APIs are documented.

Project Web Access and Project Professional use the generic PSI Web services as well as the limited and Project-specific APIs. For descriptions of the PSI Web services, see Namespaces in the PSI.

Note
The Authentication, PWA, View, and WinProj Web services are not 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 Web method is associated with a business object such as Calendar, OutlineCode, 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 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 Web service accepts the parameter dataset of type ProjectDataSet. The ProjectDataSet class is derived from the DataSet type. Development with the PSI is easier than with the PDS because of type checking in the .NET Framework and IntelliSense completion in Visual Studio.

Project Server 2007 uses exception handling of the .NET Framework. All errors are logged in the server, at the top of the PSI stack. Some errors are reported to the client and some are reported only on the server. Some errors send a simple report to the client, such as a SoapException object, and also record a detailed report on the server.

Unlike the PDS in Project Server 2003, you do not need to extend the PSI to access Project Server data because the PSI already encompasses the Project Server functionality needed for client development. You can add a .NET assembly with its own Web service that provides new functionality and calls other PSI methods or inherits from PSI classes. A new assembly also needs to provide the business logic and database access needed for the new functionality.

For more information about how to develop with the PSI and use the DataSet types, see Working with the PSI and DataSets. For an introduction to the detailed reference for PSI namespaces, classes, methods, properties, events, and related assemblies, see PSI Reference Overview.

PDS Compatibility

To port an application from Project Server 2003 to Project Server 2007, you must set a Web reference to each PSI Web service you need and change all PDS calls to PSI calls. You must also change the processing of XML requests to and replies from the PDS to processing of the PSI DataSet objects and other parameters.

The PSI supports all PDS methods that apply to Project Server 2007. The PSI includes the SoapXMLRequest interface that supports applications built using the PDS. 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.

Project Versions

Project Server 2007 introduces functionality that replaces project versions. You can use the following in Project Server:

• Create a Version custom field and lookup table, available through the CustomFields and LookupTable PSI Web services, to access project level metadata.

• Task level publishing flags and project-level availability settings to control the impact of a project on the organization.

Usage Scenarios for the PSI

The PSI is designed to complement the capabilities of Project Professional, rather than provide a server-based alternative for all Project Professional functions. Following are some usage scenarios that the PSI supports for server-side projects and calculations.

• Project proposals   Create placeholder projects during project initiation and use project custom fields to tag the project with information needed for the initiation and approval process. Add tasks to identify project phases for key milestones or deliverables. When approved, project proposals can evolve into full-scale projects that are managed with Project Professional.

• Maintenance projects   Create placeholder projects to use with resource plans. Reserve or book time against resources for maintenance work or base business. Maintenance projects generally do not have tasks.

• Financial projects   Create projects for time capture through the timesheet for integration with a financial system. Create a hierarchy of financial codes that reflect the cost breakdown structure of the financial system. These projects do not require scheduling or status updates.

• Integrate with project accounting systems   Capture the resource costs and expenses associated with projects to feed financial and billing systems and for budget comparison purposes. Synchronize tasks, resources, and assignments between the systems. Capture timesheet data in one system to feed the other (which timesheet is used depends on needs of the organization or of individual projects).

• Integrate with work or task management systems   Synchronize tasks and assignments between Project Server and systems such as Microsoft Visual Studio Team System (VSTS). The 2005 version of VSTS integrates with Project Standard or Project Professional, but integration with Project Server requires developing components using the PSI. For more information about VSTS, see Visual Studio 2005 Team System: Overview.

• Process updates from team members   For projects that are not actively managed, automatically update projects on the server with progress and other changes from project team members. Projects can be updated and republished without a project manager reviewing the results or making adjustments to the plan.

What the PSI Does Not Do

The PSI helps developers integrate Project Server with other applications, as described in the previous section. However, there are some things the PSI does not do. The following sections include actions that require Project Professional 2007.

Local Data

• Manipulating data in local projects (.mpp files). For example, defining cost rate tables or availability contours for local resources.

• Defining or editing local base calendars or resource calendars, including calendar exceptions.

• Defining local custom fields. However, the PSI does support editing local custom field values on tasks, resources, and assignments.

Enterprise Data

• Checking out or editing the Enterprise Global Template. The Enterprise Global data in Project Server 2007 is a set of binary data tables in the Published database, not a project template as in earlier versions of Project Server.

• Defining or editing enterprise calendars. The Calendar methods manage only calendar exceptions.

Master Projects and Cross-Project Links

• Creating master projects and inserting subprojects.

• Scheduling a critical path across a master project.

• Creating cross-project links.

Resources

• Requesting or performing resource leveling.

• Changing the resource on an assignment. However, you can use the PSI to delete the assignment and create a new one.

• Deleting or replacing a resource that has actual work accepted (actuals).

• Changing a resource type between Work, Material, and Cost.

• Creating or editing resource calendars.

• When adding a resource to a task, the PSI does not automatically redistribute work the way Project Professional does. It is up to the developer to choose and explicitly set the work distribution on the assignments.

Cost Resources

• Editing, creating, or deleting cost resources and assignments using the Project Web service. The Resource Web service methods can create cost resources but cannot edit them.

Work Contours

• Editing timephased data.

  Note
  The UpdateStatus method in the Statusing Web service can edit timephased actuals on assignments after the project manager updates and publishes the assignment data.

• Setting or changing the assignment contour type (such as flat, back-loaded, or front-loaded).

Baselines and Earned Value

• Saving a baseline or editing baseline data.

• Setting a progress date.

• Calculating variance and earned value.

Interactive Scheduling

• Supporting interactive scheduling. Because Project Server does interactions asynchronously, interactive scheduling should be done with Project Professional.

WBS

• Defining a work breakdown structure (WBS) code mask.

Tasks

• Changing the task type (fixed work, duration, or units).

• Changing whether a task is effort-driven.

• Changing task fixed-cost accrual.

• Changing the content of TASK_NOTES. The PSI can read only the text part of the task notes which are .rtf binary data. However, you can edit assignment notes (ASSN_NOTES), which are text data. The Reporting database does not include task or assignment notes.

• Creating or editing recurring tasks.

• Assigning or changing the task calendar on existing tasks.

• Creating a new task with a task calendar.

• Changing the value of TASK_IGNORES_RES_CAL (task ignores resource calendar).

Summary Tasks

• Editing summary task fields that are normally rolled up from the subtask. Server-side projects always roll up summary information, instead of setting information on the summary task and pushing it down to the subtasks. You can edit only the following on summary tasks:

  • Task dependencies

  • Non-formula custom fields

  • TASK_NAME

  • TASK_OUTLINE_LEVEL

  • TASK_IS_MARKED

  • TASK_CONSTRAINT_TYPE

  • TASK_CONSTRAINT_DATE

  • TASK_PRIORITY

  • TASK_DEADLINE

  • TASK_FIXED_COST

  • TASK_FIXED_COST_ACCRUAL (set the value only when creating the task)

  • TASK_WBS

• Creating or changing assignments on summary tasks.

  Note
  We recommend that you do not make assignments on summary tasks with Project Professional or any other method. For more information, see Project Scheduling on the Server.

For the project summary task, the PSI limitations are the same as for Project Professional. The PSI can edit budget assignments—including cost budgets.

Project-level Calculation Options

• Changing a project type between Schedule From Start (SFS) and Schedule From Finish (SFF). The PSI can create a project as either SFS or SFF, but once created it can be changed only in Project Professional.

• Changing the project base calendar (CAL_UID) after project creation.

• Changing options for calculations. You can use the PSI to set the following calculation options when the project is created, but changing the options requires Project Professional (on the Tools menu, click Options, and then click the Calculation tab).

  • PROJ_OPT_CALC_ACT_COSTS

  • PROJ_OPT_CRITICAL_SLACK_LIMIT

  • PROJ_OPT_HONOR_CONSTRAINTS

  • PROJ_OPT_MOVE_ACTUAL_IF_LATER

  • PROJ_OPT_MOVE_ACTUAL_TO_STATUS

  • PROJ_OPT_MOVE_REMAINING_IF_EARLIER

  • PROJ_OPT_MOVE_REMAINING_TO_STATUS

  • PROJ_OPT_MULT_CRITICAL_PATHS

  • PROJ_OPT_SPLIT_IN_PROGRESS

  • PROJ_OPT_SPREAD_ACT_COSTS

  • PROJ_OPT_SPREAD_PCT_COMP

  • PROJ_OPT_TASK_UPDATES_RES

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.

• **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 Access. 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.

• Do not report the fields that are not updated by Project Server scheduling.

• Note in the reports 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 2007 SDK download).

• 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 Calculation tab in the 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 rolls down actual work values for material resource assignments to the work resources. Project Professional rolls down actuals for material resource assignments to material resources.

• **Assignments on summary tasks   **Actuals on the 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 Project Professional 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. A future version of Project Professional will change the roll down of actuals and addition of actuals to summary task assignments to match the behavior of Project Server.

Note
We recommend that you do not make assignments on summary tasks.

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 2007. 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 2007 updates.

For all of these reasons, Project Professional and Project Web Access do not make direct calls to the Draft, Published, or Archive database; neither should any other application that integrates with Project Server.

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 2007 SDK download. You can also extend the Reporting database to include external data for integrated reporting solutions.

For more information about the Reporting database, see Using the Reporting Database.

Project Server Events

In earlier versions of Project Server, 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 2007 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 Access 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 2007. Clients interact with Project Server exclusively through the PSI, and 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. For more information about the eventing model, see Project Server Events.

See Also

Tasks

How to: Write and Debug a Project Server Event Handler

Concepts

Working with the PSI and DataSets

Finding the PSI Web Services

Integration with Office SharePoint Server 2007

Namespaces in the PSI

Internal PSI Web Services

Project Server Events

Other Resources

PDS Parity in PSI Web Services

Project Programming References

Using the Reporting Database

Windows Workflow Foundation Developer Center

Developer Introduction to Workflows for Windows SharePoint Services 3.0 and SharePoint Server 2007

SharePoint Server 2007 SDK: Software Development Kit and Enterprise Content Management Starter Kit

.NET Framework 3.0 Downloads

Visual Studio 2005 extensions for .NET Framework 3.0 (Windows Workflow Foundation)

Windows Workflow Foundation