AssignmentsSave Method

Article
09/12/2006

Description

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 MSP_WEB_WORK_ADJUSTED.
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 MSP_WEB_WORK_ADJUSTED.
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 MSP_WEB_WORK_ADJUSTED.
If the assignment belongs to a resource for which the user does not have Adjust Actuals permission, the PDS returns an error.

Recommended Use

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.

Syntax

<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>

Parameters

WUID

Required. Specifies the Web unique ID of the assignment to update.

Comments

Optional. String value representing comments for each assignment being updated.

UpdateProjectManager

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.

LockedDownByManager

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.

Return Value

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

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:

ReplyStatusEnum Value	Description
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).

Example Request and Reply for Assignment Locking

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.

Remarks

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 that assignment.
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 RemainingWork
Actual Work Done and Work Remaining	3	ActualWork RemainingWork

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

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.

Share via