Secure Access to Project Server Data Through the Project Data Service | Microsoft Office Project Server 2003 Unleashed

The Project Data Service (PDS) application programming interface (API) is another customization tool available to you. The PDS API is a component of a standard Project Server installation. You can create a client application that uses Simple Object Access Protocol (SOAP) to retrieve and set Project Server data without the need to directly access the Project Server database from your application.

TIP

SOAP is an XML-based protocol used to send messages between programs. This service is usually exposed over HTTP, but it generally can reside on top of any Internet protocol.

CAUTION

Updating the Project Server database directly could produce unwanted results. Various portfolio data is stored in different tables to allow efficient retrieval of the data for different clients such as Project Web Access (PWA) and Project Professional. Thorough testing should be conducted when updating the Project Server database directly in your customization application.

PDS methods allow you to programmatically log on to Project Server using the Project Server security model. You can then use PDS methods to access Project Server data using data access security consistent with Project Professional and PWA. Although the PDS API does not provide methods for all Project Server functionality, it does provide a way to perform many common tasks. In the compiled help module Project Data Service Reference for Microsoft Office Project Server 2003, available from the Project Server software development kit (SDK), the methods are broken down into the following categories:

Project methods
Enterprise project creation methods
Resource methods
Enterprise custom field methods
Timesheet methods
Version methods
Administrative methods
Project Server user maintenance methods
Miscellaneous methods

Because not all methods are discussed in this book, consult the Project Data Service Reference for Microsoft Office Project Server 2003 for details on all methods available in the PDS.

TIP

Accessing the Project Server database directly does not inherently provide you the same security model as Project Server. A combination of PDS and direct database access may be appropriate when data not accessible from the PDS is needed. In this case you could use the PDS to log on to Project Server, get necessary security access and details, and then directly make SQL requests from the database.

When to Use the PDS

The PDS can be useful in many situations. Although not a comprehensive list of uses for the PDS, the following is a starting point for customizations where the PDS would be practical:

Reporting You could use the PDS to extract the desired enterprise data and report the information in a custom reporting application. The ProjectCodeValues method of the PDS could be used multiple times to retrieve enterprise project fields and create a cross-project report on those fields.

PAGE 163.

PAGE 537.
Enterprise resource management The PDS provides methods to add, delete, update, and attain details for enterprise resources. If you have a list of resources stored external to Project Server, the ResourcesAdd method could be used to add them to the Enterprise Resource pool. You would first programmatically extract the resource information from its current location, and then you would call ResourcesAdd to subsequently add the resource to Project Server.
Enterprise project fields management The PDS enables you to insert, update, and remove enterprise fields for a given project. The ProjectCodeValuesUpdate method is useful for updating enterprise field values. You could develop a custom application to allow the viewing and updating of enterprise fields for multiple projects by combining the functionality of the ProjectCodeValues and the ProjectCodeValuesUpdate methods.
NOTE

Not all enterprise fields are available with the ProjectCodeValues and ProjectCodeValues Update methods, as you might expect. Enterprise fields with graphical indicators are not updated, nor are the work, flag, and duration enterprise fields.
Enterprise global fields management The global template for the enterprise fields can be altered using the EnterpriseCustomFieldsUpdate method and the OutlineCodeUpdateValues method. The PDS would then allow you to build a custom application for managing the enterprise global template. This could be useful if one or more of your enterprise fields depends on an outside source for its available values.
Timesheet management The PDS allows you to get and save timesheet information for a given user, as well as send updates to the project manager. The AssignmentsGet, AssignmentsSave, and AssignmentsProjectManagerUpdate methods could be used to make a custom timesheet management application, when your current business practices require recording time against assignments in an application other than PWA.

How to Use the PDS

This section describes how to use the PDS, now that you know what the PDS is, and examples of when to use it. Because the PDS is a secure mechanism for retrieving data from Project Server, before you can use any of its methods you must programmatically log on to Project Server. After you are logged on to Project Server, the methods of the PDS API are available to you. To use the PDS follow these steps:

1.	Log on to Project Server and collect the security cookie.
2.	Form the PDS request with Extensible Markup Language (XML).
3.	Send the request to the PDS and accept the XML-formatted response.
4.	Check for errors in the response.
5.	Use the data from the response.
6.	Repeat Steps 3 to 5 as necessary.

The simplest PDS method is the PDSInfo method. This method allows you to make sure that you are using the PDS correctly and return information about the PDS. The following example shows you how to use the PDS to call the PDSInfo method, using the preceding six steps.

NOTE

The PDS example is written in C#. Any language that allows you to use SOAP can be used to interact with the PDS API. See the documentation for the language of your choice to use the PDS in that language.

Log On to Project Server and Collect the Security Cookie

The Project Server security model allows you to log on in two different ways: by Windows integrated authentication and Project Server authentication. When using Windows integrated authentication, the security credentials of the user are not required when logging on to Project Server. The following declaration and assignment are used for Windows authentication:

 string sUrl; sUrl = "http://yourserver/projectserver/LgnIntAu.asp";

With Project Server authentication, the preceding line of code would be replaced with the following:

 sUrl = "http://yourserver/projectserver/LgnPSAu.asp"; sUrl += "?un=Administrator&pwd=";

TIP

Because the password when using Project Server authentication is sent as part of a URL string, you should check for reserved characters and replace them with their number representation. For example the # character would be replaced with %23 to allow the URL to properly send the string as a parameter.

After you form the proper URL, you then make the request:

 HttpWebRequest myReq = (HttpWebRequest)WebRequest.Create(realURL); CookieContainer conCookie = new CookieContainer(); myReq.CookieContainer = conCookie; myReq.Credentials = CredentialCache.DefaultCredentials; HttpWebResponse myRes = (HttpWebResponse)myReq.GetResponse(); XmlDocument XMLDoc = new XmlDocument(); XMLDoc.Load(myRes.GetResponseStream()); myRes.Close(); string sCookie;

The XMLDoc now holds the response from Project Server that looks similar to the following:

 <?xml version="1.0"?>    <Reply>       <HRESULT>0</HRESULT>       <Cookie>       <![CDATA[svc={D8D06337-9C12-466D-84BF-57767FEDF8AD}       &session={CCB39B94-A3D8-4C0B-AFA1-49604AF6C3D9}       &prxy={EFBA0018-337F-4A35-9454-E7E1155F92A4}       &org=projectserver]]>    </Cookie> </Reply>

Next, you parse the XMLDoc and put the cookie information into the sCookie string for use when making SOAP requests to the PDS.

Form the PDS Request

A PDS request is an XML string with the following form:

 <Request>     <MethodName>         <Parameter1>value</Parameter1>         <Parameter2>value</Parameter2>         ...         <ParameterN>value</ParameterN>     </MethodName> </Request>

In the example, the PDSInfo method does not have any parameters, so the request XML string is created like this:

 String sRequest; sRequest = "<Request>" +                "<PDSInfo/>" +            "</Request>";

With other methods of the PDS a more complex method of forming the request string may be required.

Send the Request to the PDS and Accept the Response

After the request string has been formed, you make the request to the PDS in the following manner:

 localhost.PDS wsPDS = new localhost.PDS(); wsPDS.Url = "http://yourserver/projectserver/PDS.wsdl"; wsPDS.Credentials = CredentialCache.DefaultCredentials; XmlDocument XmlDoc = new XmlDocument(); XmlDoc.LoadXml(sRequest); string sResponse; sResponse = wsPDS.SoapXMLRequest(sCookie, XmlDoc.InnerXml);

Notice the use of the security cookie in the SoapXMLRequest. Each time the SOAP request is made, the security cookie is used. If this security cookie is not present, the request fails.

Check for Errors in the Response

The response returned with a PDS method request is also formatted in XML. The template for the response takes this form:

 <Reply>     <HRESULT>0</HRESULT>     <STATUS>0</STATUS>     <UserName>Administrator</UserName>     <MethodName>         method-specific output     </MethodName> </Reply>

The HRESULT and STATUS values each have the value 0 when the method is called properly and no errors occur. The UserName value contains the name of the user who made the request.

At this point you would again parse the XML and check for the hrESULT and the STATUS values. The possible values and explanation of hrESULT and STATUS can be found in the "Error Codes" section of the Project Data Service Reference for Microsoft Office Project Server 2003.

The PDSInfo method returns an XML response similar to the following when successful:

 <Reply>    <HRESULT>0</HRESULT>    <STATUS>0</STATUS>    <UserName>Administrator</UserName>    <PDSInfo>       <ExeName>PDS</ExeName>       <CompanyName>Microsoft Corporation</CompanyName>       <FileDescription>Microsoft Project Data Service</FileDescription>       <Comments/>       <ProductName>Microsoft Project Server</ProductName>       <Title>PDS</Title>       <LegalCopyright>Copyright © 2000-2001 Microsoft          Corporation.</LegalCopyright>       <LegalTrademarks/>       <Major>1</Major>       <Minor>0</Minor>       <Revision>728</Revision>    </PDSInfo> </Reply>

Use the Data from the Response

After you verify that the request is successful, you then parse the XML from the method-specific output to extract the necessary data. In the example the results from the request are not parsed but simply are written to the console:

 Console.WriteLine("PDSInfo Results:"); Console.WriteLine(sResponse);

Repeat Steps 3 to 5 As Necessary

You can now repeat Steps 3 to 5 as many times as necessary for your customization application. You do not need to request a new security cookie each time a PDS method is called. You can simply use the same cookie, unless a different user is needed to make the request.

TIP

The Project 2003 SDK provides a sample application called the PDSTest. This application is useful for testing PDS methods without having to write any code. You simply input the XML request for a PDS method and the logon credentials. The PDSTest then makes the method call and returns the XML results. In this way, you can test the PDS methods and use the results for parsing algorithms and flow logic.

Limitations of the PDS

The PDS API is not a comprehensive interface to the Project Server data. Some of the functionality and usefulness of Project Server can be found only in the Project Professional and PWA interfaces. The PDS does, however, provide much of the essential functionality for a custom application. In the case that the PDS does not provide the necessary functionality for your application, PDS extensions can be created. A PDS extender allows you to use the same PDS interface but with customized methods for your particular situation. You can learn more about how to create a PDS extender in the "Writing a PDS Extender" section of the Project Data Service Reference for Microsoft Office Project Server 2003.

TIP

The Project 2003 SDK contains more examples of using the PDS. The SDK also includes an example of building a PDS extender. The Project Data Service Reference for Microsoft Office Project Server 2003 comes with the SDK as well.

PWA Web Parts

Provided with Project Server 2003 are six custom web parts that can access Project Server data when added to a Project Workspace site, or with a few modifications to a SharePoint Portal Server (SPS) site. Additionally, using URL options to modify the appearance of PWA pages, you can quickly create customized web parts for your Project Workspace or SPS site for your own custom pages. The six Project Server web parts are Project Timesheet, Project Center, Project Report, Project Manager Updates, Project Resource Assignments, and Project Portfolio Analyzer.

Refer to the Microsoft download site for help on the custom web parts and the assemblies for them. The article's name is "Project Server 2003 Web Parts and URL Options."

In addition to the Project Server web parts, you can create your own custom web parts to integrate Project Server with SPS. The possibilities for useful web parts are limitless.