The PDS updates assignment data for the specified assignments in Microsoft® Office Project Server 2003. Assignment data can include timephased data that covers the valid period of the assignment. AssignmentsSave also updates the non-timephased work fields (Work, ActualWork, RemainingWork, and PercentWorkComplete), according to the assignment tracking mode.
Permissions: The current user of an external timesheet system can save an assignment under the following conditions. These conditions satisfy the Project Server 2003 features for protecting and adjusting actual work values (“protect actuals” and “adjust actuals”):
The user has the permission Integrate With External Timesheet Systems.
This is a new permission in Project Server 2003.
If the assignment belongs to the user and falls in an open period, the
PDS saves the assignment but does NOT log a transaction in
If the assignment belongs to the user and falls in a closed-out period,
the user must have the Adjust Actuals permission, or the PDS returns an
error. The PDS saves the assignment and logs a new transaction in
If the assignment belongs to a resource for which the user has Adjust Actuals
permission, the PDS saves the assignment regardless of whether it falls in a
closed-out period. The PDS also logs a new transaction in
- If the assignment belongs to a resource for which the user does not have Adjust Actuals permission, the PDS returns an error.
The AssignmentsSave request is essentially the same as that of the AssignmentsGet reply, only with fewer fields. A user would typically run AssignmentsGet, and then apply a transform to the XML reply to remove fields that aren’t in the syntax for the <Assignment> block (and apply any other transformation or formatting desired). The user would then load that modified reply in an external timesheet application, modify the fields as required, and send the updated XML back as input to AssignmentsSave.
<Request> <AssignmentsSave> <Assignments> <Assignment> <WUID></WUID> <Comments></Comments> -- Assignment Data – <UpdateProjectManager></UpdateProjectManager> <LockedDownByManager></LockedDownByManager> </Assignment> . . . </Assignments> </AssignmentsSave> </Request> -- Assignment Data –- [non-timephased] <RemainingWork></RemainingWork> <ActualWork></ActualWork> <PercentWorkComplete></PercentWorkComplete> [timephased] <TimephasedDataSegments> <TimephasedData> <Type></Type> <WUID></WUID> <Day></Day> <Value></Value> </TimephasedData> . . . </TimephasedDataSegments>
Required. Specifies the Web unique ID of the assignment to update.
Optional. String value representing comments for each assignment being updated.
Optional. Boolean value indicating whether the project manager is to be updated with the saved assignment edit. UpdateProjectManager enables the save and update operations to occur in one AssignmentsSave call on a per-assignment basis, so that a separate call to AssignmentsProjectManagerUpdate is not necessary.
Optional. Boolean, sets the value of MSP_WEB_ASSIGMENTS.WASSN_LOCKDOWN_BY_MANAGER for the assignment specified. Default is 0. For more information, see Changes for Service Pack 1 (SP1) in the topic About Timesheet Methods. For an example request and reply using LockedDownByManager, see Example Request and Reply for Assignment Locking.
[Timephased assignment data]
Optional. See the remarks for timephased data.
[Non-timephased assignment data]
Optional. See the remarks for non-timephased data.
If the request is successful, AssignmentsSave returns a successful HRESULT and STATUS and a specific ReplyStatus for each assignment update that failed. A save is successful if that assignment WUID is not in the reply.
Note AssignmentsSave is different than most PDS methods in this respect: One failure does not invalidate the entire call. Each saved assignment is its own transaction; that is, it passes or fails independently of other assignments.
Status codes in AssignmentsSave are consistent with ResourcesStatus.
<Reply> <HRESULT></HRESULT> <STATUS></STATUS> <UserName></UserName> <AssignmentsSave> <Assignments> <Assignment> <WUID></WUID> <ReplyStatus></ReplyStatus> </Assignment> . . . </Assignments> </AssignmentsSave> </Reply>
The global status value in the <STATUS> tag is always rsSuccess (that is, 0). AssignmentsSave can return one of the following status codes for a specific assignment, if saving the data for that WUID fails:
|rsSecurityAccessDenied = 50||The user does not have permission to make this request. This can occur because of incorrect permission or because the user is trying to lock a summary task when some sub-tasks are unlocked (Project Server 2003 SP1).|
|rsAssignmentNotFound = 120||The assignment with the specified WUID does not exist (bad WUID specified in request).|
|rsAssignmentDeleted = 121||The assignment with the specified WUID has been deleted from the server.|
|rsAssignmentWrongTrackingMethod = 122||Actuals are reported in a method other than the locked-down reporting method.|
|rsAssignmentTimephasedDataClosedOut = 123||You attempted to update TimphasedData in a closed-out period for this assignment. The assignment edit was not saved.|
|rsAssignmentDateNotExactDay = 125||Assignment contains at least one timephased data segment where Day contains a time portion. Dates may be entered as YYYYMMDD or YYYYMMDDHHMMSS. The dates provided for timephased data segments in AssignmentsSave must be exact days (20021028 or 20021028000000, for example). If date-time values are included, the last six digits in the date-time must be zero.|
|rsAssignmentTimephasedDataSegmentMultiplesInvalid = 126||TimephasedDataSegments contain at least 1 duplicate pair of TimephasedData nodes (where Type and UID are identical).|
|rsAssignmentWorkTypeInvalid = 127||Only assignments of type 1 (“Actual Work”) and 2 (“Overtime Actual Work”) can be saved. Assignments of type 0 (“Scheduled Work”) or any invalid value cannot be saved.|
|rsAssignmentNotificationsURLNotSetup = 128||There is no URL available for assignment notifications.|
|rsAssignmentMaxHoursPerDayExceeded = 129||If the current tracking mode is 1 (Hours of Work Done Per Time Period), the work reported must be less than the maximum set by the project administrator. The maximum applies to work fields individually (ActualWork and OvertimeActualWork), not the sum of work fields.|
|rsAssignmentLockedDownByManager = 130||The assignment is already locked. The current value of MSP_WEB_ASSIGNMENTS.WASSN_LOCKDOWN_BY_MANAGER is not zero for the assignment (Project Server 2003, Service Pack 1 or later).|
A Project Server administrator sends the following request twice in succession to the sample database installed with Project Server 2003 SP1.
<Request> <AssignmentsSave> <Assignments> <Assignment> <WUID>578</WUID> <LockedDownByManager>1</LockedDownByManager> </Assignment> </Assignments> </AssignmentsSave> </Request>
The first request receives the following reply.
<Reply> <HRESULT>0</HRESULT> <STATUS>0</STATUS> <UserName>Administrator</UserName> </Reply>
The second identical request receives ReplyStatus 130 because the assignment is already locked.
<Reply> <HRESULT>0</HRESULT> <STATUS>0</STATUS> <UserName>Administrator</UserName> <AssignmentsSave> <Assignments> <Assignment> <WUID>578</WUID> <ReplyStatus>130</ReplyStatus> </Assignment> </Assignments> </AssignmentsSave> </Reply>
Note If you try to lock a summary task where some sub-tasks are unlocked, AssignmentsSave returns ReplyStatus 50 (rsSecurityAccessDenied) for the summary task. All sub-tasks must be locked before you can lock a summary task.
The PDS determines whether the user has a valid Project Server account. The PDS also checks that the user has permission to edit each assignment specified by a WUID.
Timephased Assignment Data
The following notes apply to updates of timephased data:
For timephased assignment data, only those assignments that have TimephasedData
segments with Type set to 1 (“Actual Work”) or 2 (“Overtime Actual
Work”) are updated. If Type is set to 0 (“Scheduled Work”) or any other
value, an error is returned.
ALL fields in the TimephasedData segment must be set in order for the
PDS to handle the edit. It is not necessary to specify ReadOnly for each
segment, since the PDS checks “protected actuals” when attempting the edit.
The time unit for the <Value> tag is minutes/1000. For example, a value
of 8 hours is specified as <Value>480000</Value>.
It is not necessary for timephased data segments to cover the entire
assignment. For example, if an assignment spans 5 days, and the update request
includes only two TimephasedData segments, the PDS tries to update only
the assignment within the specified date sub range (the 2 days of the 5-day
total assignment duration; timephased data in the other 3 segments remains
untouched). All specified segments must be updated in order for the assignment
update to be successful. Otherwise, the PDS returns an error status code for
The PDS converts the XML timephased data segments into consolidated records in
the MSP_WEB_WORK table.
The PDS writes only the timephased data that falls within the allowed date
window (respecting “protected actual work”). The PDS returns an error code if
the request includes timephased data outside the allowable date window.
When the PDS updates timephased data, it also updates the four non-timephased
work fields (Work, ActualWork, RemainingWork, and PercentWorkComplete).
- ApprovalStatus and Approver are read-only fields set by Project Web Access; an error results if they are included in a request with timephased data.
Non-timephased Assignment Data
Given one or two non-timephased work fields, AssignmentsSave calculates the remaining non-timephased work fields for an assignment based on the assignment tracking mode.
Note The PDS ensures that the reported non-timephased fields map to the assignment tracking mode. Any other fields specified within the <Assignment> block result in a generic PDS error (rsNodeNameInvalid). The exceptions are that WUID, UpdateProjectManager, and Comments are always accepted.
In the following table the mode value is the database field WASSN_CURRENT_TRACKING_MODE. The PDS returns an error if no work fields are reported for an assignment, or if a work field is reported other than those in the fields available for that tracking mode.
|Tracking mode||Mode value||Available non-timephased fields|
|Hours of Work Done Per Time Period||1||RemainingWork |
ActualWork (sum of timephased segments)
|Percentage of Work completed||2||PercentWorkComplete |
|Actual Work Done and Work Remaining||3||ActualWork |
Note that the PDS performs the update regardless of the assignment tracking mode if only RemainingWork is specified.
You can specify one or both of the non-timephased work fields available for tracking modes 1, 2, or 3. If you specify only one non-timephased work field, the result is the same as in Microsoft Office Project Web Access 2003. Project Web Access does not allow the simultaneous editing of two or more non-timephased work fields. If you specify two fields, the result may differ from Project Web Access. You can check the calculations with the following formulas.
The four non-timephased work fields are related as follows:
P = 100 * A / (A + R) = 100 * A / T
where P = PercentWorkComplete, A = ActualWork, R = RemainingWork, T = TotalWork
In tracking mode 2, if only RemainingWork is specified, the PDS gets TotalWork for that assignment from Project Server to calculate ActualWork and PercentWorkComplete:
A = T – R P = 100 * (T - R) / T
If both PercentWorkComplete and RemainingWork are specified, the PDS computes the other two non-timephased work fields (TotalWork and ActualWork):
T = R / (1 - P / 100) A = (P * T) / 100
If only PercentWorkComplete is specified, the PDS gets TotalWork for that assignment from Project Server to calculate RemainingWork, and then calculates ActualWork as shown previously:
R = T – (T * P / 100)
Examples for Non-timephased Data
For an 8h task, if PercentWorkComplete is 50% and RemainingWork is
6h, then the task actually takes 12h (TotalWork is 12h).
Use the following values in the formulas to help illustrate the concepts:
Non-timephased work field Example value PercentWorkComplete P = 40% ActualWork A = 20h RemainingWork R = 30h TotalWork T = 50h
If a project manager changes the tracking mode after an assignment is imported to an external timesheet system, the PDS returns status code 122 (rsAssignmentWrongTrackingMethod) when it tries to save, since the external system is still using the previous tracking mode.