Welcome!

ColdFusion Authors: Yakov Fain, Maureen O'Gara, Nancy Y. Nee, Tad Anderson, Daniel Kaar

Related Topics: ColdFusion

ColdFusion: Article

ProjectFusion: ColdFusion Project Server Integration

Manage tasks, resources, and projects

Most people are familiar with Microsoft Project - project management software that allows you to manage many aspects of projects including tasks, due dates, progress, and people assigned to specific tasks.

Microsoft Project Server is an enterprise storage product that facilitates sharing project plans created with Microsoft Project with other people in a company, especially other project managers. Project Server enables you to manage a workforce by tracking all projects in common and giving you a view of all projects that an individual may be assigned to. Chances are that any large organization will have more than one project manager and using a centralized storage point allows for better group management of projects. In this kind of environment, Project Server acts as the central repository and Microsoft Project acts as a client to access that information. Project Server also provides a Web interface for viewing the status of projects.

The principal (recommended) way to integrate with Microsoft Project is by using the integrated Project Data Service (PDS) that's included with Microsoft Project Server. PDS is a SOAP Web service that translates incoming requests and manages their entry into the system. The most common integration pieces are external user management, timesheet systems, and ticketing systems. The PDS exposes pieces of the puzzle that allow you to integrate with these external systems and to integrate all the parts of your organizational project systems.

The PDS will allow you to create projects, tasks, resources, as well as log time against projects and run administrative reports on information in the system. Granted, for most integration you'll want to use the Microsoft hooks into other Microsoft products. For example, Project Server boasts excellent integration with Microsoft's Outlook Exchange, Active Directory, and Sharepoint. If those are your only integration points, any work you would need to do is done by Microsoft, but if you need to work with a non-Microsoft product, read on.

Often times the largest integration obstacle is simply learning how a product works, and that can easily be the case with Microsoft Project. The initial learning curve of Microsoft Project may be steep but it's worth the hurdle to reach familiarization with the application before and during your implementation. You can retrieve a copy of the Microsoft Project Server API help files from this location: www.microsoft.com/downloads/details.aspx?FamilyID=4D2ABC8C-8BCA-4DB9-8753-178C0D3099C5&displaylang=en .

I'll now focus on the basics of the PDS and share some code that you can use in your organization to hook into Project Server.

Authentication
The first thing you have to do in any integration is authenticate with the other system. In Project Server land authentication is a three-part process: authenticate with Project Server, create the session, and authenticate with PDS Web services. If you're trying this on your local system, the best way to debug and observe the authentication steps is to turn on prompting for all cookies and turn off automatic forwarding in your Web browser.

To authenticate with Project Server:


 <cfhttp method="get"  url="http://#projectserver#/projectserver/lgnPSAu.asp"
   redirect="No" timeout="60">
    <cfhttpparam name="un" value="#pjUname#" type="url">
    <cfhttpparam name="pwd" value="#pjPwd#" type="url">
</cfhttp>

Next take the cookie from the Project Server login page and pass it to the session manager:


<cfhttp method="post" url="http://#projectserver#/projectserver/SesStart.asp?
ref=lgnpsau.asp&au=0" redirect="No" timeout="60">
  <cfhttpparam name="PjSessionID" value="#urldecode(PjSessionCookie)#" 
  type="Cookie">
</cfhttp>

Passing in the cookie to Project Server instantiates the session on Project Server and initiates the security system.


<cfhttp method="post"  url="http://#projectserver#/projectserver/lgnpsau.asp?err=0"
 redirect="No" timeout="60">
   <cfhttpparam name="PjSessionID" value="#urldecode(PjSessionCookie)#" type="Cookie">
</cfhttp>

After the third cfhttp call, you'll receive an XML session cookie to use with Web services. Each and every Web service request must be accompanied with the XML session cookie provided in the last step. This cookie serves to associate your session with the system and Project Server uses this to manage the security and show you the correct projects that your username has access to. To make things easier, create an object and function to send the cookie and the XML request to Project Server.


<cfobject webservice="http://sjn-msp-02/projectserver/pds.wsdl" name="pdshandle">

  // Function to make it easier to send requests to the web service
    function pdsSend(myxml) {
       var returnedxml = "";
        returnedxml = xmlparse(pdshandle.soapxmlrequest(sessioncookie,m
		yxml));
        return returnedxml;
   }

From here you just have to send SOAP requests to the Project Server to manage whatever project you're working on. The first step is to create a project using the PDS <CreateProject> method:


 initialProject = pdsSend("<Request><ProjectCreate><AutoPublish>1</AutoPublish>
 <Project>
<ProjectName>#projectname#</ProjectName><Title>MY Test ColdFusion
 Project</Title><Company>eBay</Company><StartDate>#dateformat(now(),'yyyymmdd')#
 </StartDate></Project></ProjectCreate></Request>");

You can use this method to fully create a project and tasks, if you know all of the details about the project, such as tasks, resources, and assignments. For this example, though, project creation is broken down into each respective method call to show a wider variety of methods associated with the PDS. This example creates only one project but the PDS allows you to create multiple projects in one request. A large number of PDS methods allow you to create or modify several items in one request, which can be very convenient; however, if one item fails, all other items will fail as well.

Replies from the PDS Web service always come back in the same format: an XML response with an hresult and status node. A status code of 0 means that your request was successful; anything greater than a 0 means that something went wrong and the request failed. Figure 1 shows a <CFDUMP> of the resultant XML that is returned by PDS.

Next, check out the project you just created using the Web service call <ProjectsCheckout> to add tasks, resources, and assignments to it.


projectcheckout = pdsSend("<Request><ProjectsCheckout><Project>
<ProjectID>#projectID#
</ProjectID>
</Project><Project><ProjectID>1</ProjectID></Project>
</ProjectsCheckout>
</Request>");

In the <ProjectsCheckout> Web service call, there are two projects being checked out: the project you just created from the PDS system and the ID for the global resources project. To add resources or users to Project Server, it's necessary to check out the global project because the resources will also be added to the global project. In the default configuration, the global project should have an ID of 1 and the name of resglobal, but this may be different for your configuration. It helps to keep in mind that within Project Server, users are a type of resource.

Once the global resource project is checked out, create a resource by calling the <ResourcesAdd> method.


resourceinfo = pdsSend("<Request><ResourcesAdd><Resources><Resource>
<Name>#resourcename#</Name></Resource></Resources></ResourcesAdd></Request>");

The default type of resource created is the "work" type, meaning a person. When a work resource is created with this PDS method, it automatically creates a Project Server Web access login for the resource as well. PDS returns the enterprise resource ID or Enterprise User ID (EUID) of the user that is created. The EUID is needed for successive method calls and it must be parsed out.

Although the resource has been added to Project Server, it still needs to be added to the project that was just created in order to assign the resource to a task. Using <ProjectResourcesCreate> you can add one or several resources to the project.


ProjResource = pdsSend("<Request><ProjectResourcesCreate><AutoPublish>1</AutoPublish>
<ProjectID>#projectID#</ProjectID><Resources><Resource><EUID>#resourceUID#
</EUID></Resource></Resources></ProjectResourcesCreate></Request>");

At this point there is a little bit of a problem. The resource was added to Project Server and an EUID was created, but unfortunately the EUID can't be used in the project for assignments. For resources in Project Server there are three IDs to choose from when trying to assign a resource to a specific task in a project. Resources have an enterprise resource ID or EUID (one that corresponds to the resource ID of the resource global project), a project resource Unique ID (UID), and a Resource ID.

To assign the resource to the task, you need to find the UID for the resource. You can accomplish this by making another request to get the details for the project using the <ProjectData> method and then taking the EUID received after adding the resource to Project Server and matching it with the EUID that's returned with the project data. The <ProjectData> method returns a complete resource object that includes the EUID and the UID for that particular project.


projectdata =  pdsSend("<Request><ProjectData><ProjectID>#projectID#</ProjectID>
<ReturnUIDs>1</ReturnUIDs></ProjectData></Request>");

Sound confusing? It helps to think of Project Server organizing everything into projects. When a resource is added to a project, it creates a Unique ID for that project. The EUID corresponds to the Unique ID for the resource in the global project.

There's one other thing that you need the project data for: to find out what the next Task ID should be. If you have installed the latest service pack from Microsoft for Project Server, you won't need to do this step. For previous versions of Project Server you'll need to find out what the next Task ID is and include it with the Project ID in the task creation method <ProjectTasksCreate>.


Taskxml = pdsSend("<Request><ProjectTasksCreate><AutoPublish>1</AutoPublish>
<ProjectID>#ProjectID#</ProjectID><Tasks><Task><Name>#taskname#</Name>
<ID>#projectTaskID#</ID><Finish>#dateformat(taskenddate,'yyyymmdd')
##timeformat(taskenddate,'HHmmss')#</Finish><Start>#dateformat(taskstartdate,'yyyymmdd')
##timeformat(taskstartdate,'HHmmss')#</Start></Task></Tasks>
</ProjectTasksCreate></Request>");

Once the task has been added to the project, assign a resource to the task using <ProjectAssignmentsCreate>.


ProjAssign = pdsSend("<Request><ProjectAssignmentsCreate><AutoPublish>1</AutoPublish>
<ProjectID>#ProjectID#</ProjectID><Assignments><Assignment>
<TaskID>#projectTaskID#</TaskID><ResourceID>#ProjectResourceID#</ResourceID>
<Units>100</Units><Finish>#dateformat(taskenddate,'yyyymmdd')
##timeformat(taskenddate,'HHmmss')#</Finish><Start>#dateformat(taskstartdate,'yyyymmdd')
##timeformat(taskstartdate,'HHmmss')#</Start></Assignment></Assignments>
</ProjectAssignmentsCreate></Request>");

A resource can only be assigned to a task once. However, several resources can be assigned to complete a task. Assignments have their own start dates and end dates as well, because specific assignments can be less than the duration of the task. To finish it off, check the project back in and voilà, you've created your own project in Project Server!


projectcheckin = pdsSend("<Request><ProjectsCheckin><Project>
<ProjectID>#projectID#
</ProjectID>
</Project><Project><ProjectID>1</ProjectID></Project>
</ProjectsCheckin>
</Request>");

Conclusion
Once all of the above steps have been completed, you have a project in which you can manage tasks, resources, and projects. Using the Web service calls discussed in this article, you can do anything from tracking the status of projects, to managing resources and resource availability on an enterprise scale with your custom applications. Integrating with Project Server using ColdFusion's built-in processing tools is a great way to connect your enterprise applications to Microsoft's project management tools. If you're interested in doing more with Project Server, you'll find more information at these Web sites:

  • The official developer's network that includes tools and information for dealing with Microsoft Project including developer guides and helpful information about integrating with Microsoft Project Server and Microsoft Project: http://msdn.microsoft.com/project
  • Microsoft Project Users Group is an independent Web site that features Microsoft Project and project management resources for those interested in finding out more about how other project management professionals are doing things in the real world: www.mpug.org

More Stories By John Hirschi

Jon Hirschi is a Senior Web Developer at eBay Inc. specializing in content and knowledge management systems. He has been using ColdFusion since version 4.0.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.