Using the Project API with Required Enterprise Custom Fields

Chris Elwell from the Project Test team wanted me to share the following details around the Project API:

Summary

The Project API (the SOAP methods contained within project) enables the user to create and manage projects on Project Server without the need for the Project Professional client application. Project API functionality includes the ability to create, update, and delete Enterprise Custom Field data within a project; however, the API imposes some restrictions that are not intuitively obvious, especially when the server contains Required Custom Fields.

We’ll cover each one of the major methods within the Project API and discuss the main concerns related to their use with Enterprise Custom Fields. We won’t discuss every method within the Project API; rather, we’ll focus solely on commonly-used methods which have heavy integration with Enterprise Custom fields. Our discussion focuses on the behavior of regular Text fields; although other Custom Field types may impose additional restrictions, the fundamental concepts will remain largely the same.

QueueCreateProject

When calling QueueCreateProject, you must provide values for any required project custom fields. If the initial project data set contains any tasks, you must also supply values for any required task Custom Fields. However, the API does not require that you supply values for required resource Custom Fields if you have added local resources to your project. This behavior is consistent with Project Professional 2007.

Note that the project data set passed into QueueCreateProject is not required to contain a Project Summary Task. If the data set contains no Project Summary Task, one will be created automatically; however, in subsequent calls to QueueAddToProject, QueueUpdateProject, and so forth, you will have to provide any required Custom Field value s for this task.

QueueAddToProject

When calling QueueAddToProject, it is usually sufficient to add your tasks, resources, or assignments, add any applicable required Custom Field values, and then call GetChanges() on the data set. However, you should first verify that the project stored on the server already meets requirements.

Specifically, a Project Summary Task must have values for all required task Custom Fields before any modifications to the project can be processed successfully. Project Professional does not enforce this requirement, and Project Summary Tasks that were automatically generated by QueueCreateProject also do not necessarily have values for these fields. If you do not set values for all required Custom Fields on the Project Summary Task, calling QueueAddToProject will fail with a SOAP exception. This applies to any tasks you’ve added, as well.

QueueAddToProject expects that any “core” Project data must have the “Added” DataRowState. However, it does not enforce this requirement on any of the Custom Fields tables; rather, it uses DataRowState to determine whether the user intends to add, update, or delete values. For example, the only task changes permitted in QueueAddToProject are additions. However, you can modify an existing task Custom Field value, and a call to QueueAddToProject will update the corresponding data on the server.

Using DataRowState, QueueAddToProject will permit you to add, delete, and modify Custom Field values within a Project. You may not, however, put the project into a state where it is missing any required Custom Field values. As noted, the API will also not permit you to use QueueAddToProject to add data to a project that is already in such a state (missing Custom Field values for the Project Summary task, for example) unless you supply the missing data.

QueueUpdateProject

Similar to QueueAddToProject, this method strictly enforces that all changes to the “core” project data must have the “Modified” DataRowState. As long as you do not violate this restriction, though, you’re allowed to add, delete, or modify Custom Field values as you see fit, and these changes (as in QueueAddToProject) are applied based on their DataRowState. As with the QueueAddToProject method, this method will fail and emit a SOAP exception if the project is already missing required Custom Field data and the data set you’ve sent doesn’t supply the missing information.

QueueDeleteFromProject

This method simply takes an array of GUIDs containing entities you wish to delete from a project. When you delete one of the “core” entities (such as a task or resource) from a project, the related Custom Field values should be deleted automatically. However, using this method to directly delete Custom Field values has no effect. If you wish to delete a Custom Field value from a project, you must call the DataRow.Delete method on the row you wish to delete, then use GetChanges to produce a data set appropriate for use with QueueAddToProject or QueueUpdateProject.

Technorati Tags: Project,Project API,PSI