AssignmentsGet Method

Description

The PDS gets assignment data from Microsoft® Office Project Server 2003 for the specified resources, specified assignments, or for all resources or assignments accessible to the user, within an optional specified date range. Assignment data can include timephased data.

Permissions: Users can get resource assignments only if they have the permissions Integrate With External Timesheet Systems and View Resource Assignments for the requested resources.

Syntax

<Request>
    <AssignmentsGet>
        <AllResources></AllResources>
        <Resources>
            <Resource>
                <ResourceUID></ResourceUID>
                <ResourceName></ResourceName>
            </Resource>
                . . .
        </Resources>
        <AllAssignments></AllAssignments>
        <WUIDs>
            <WUID></WUID>
                . . .
        </WUIDs>
        <PeriodDateRange>
            <PeriodStartDate></PeriodStartDate>
            <PeriodEndDate></PeriodEndDate>
        </PeriodDateRange>
        <IncludeTimephasedData></IncludeTimephasedData>
        <AdminProject></AdminProject>
        <ApprovalStatus></ApprovalStatus>
        <LockedDownByManager></LockedDownByManager>
    </AssignmentsGet>
</Request>

Parameters

All parameters to AssignmentsGet are optional. Default values are used if parameters are not set.

If no parameters are specified, the method returns assignments within the Project Server date range for the currently logged-on user. Only non-timephased data is returned for each assignment, from both regular and admin projects of any approval status.

AllResources

Optional. Boolean specifying whether to return assignments for all resources to which the currently logged-on user has access. User access is via the object-level Project Server permission ViewResourceAssignments. Default is 0.

Resources (ResourceUID* or *ResourceName)

Optional. Each <Resource> block represents a specific resource for which assignments are to be returned (assuming the currently logged-on user has sufficient permissions). A resource can be specified by either ResourceUID or ResourceName, both of which are guaranteed to be unique in Project Server. If ResourceUID is set, ResourceName is ignored, even if set.

AllAssignments

Optional. Boolean specifying whether to return ALL Project Server assignments for the currently logged-on user. Default is 0.

WUID

Optional. Long value, representing the Web unique ID of the assignment to return from the Web assignments table.

PeriodDateRange (PeriodStartDate* and *PeriodEndDate)

Optional. String values, containing the earliest and latest dates in the range in which assignments are to be returned. Default: If PeriodDateRange is not set, the PDS uses the date range in Project Server.

The date format can be entered as YYYYMMDD or YYYYMMDDHHMMSS. If the hours, minutes, and seconds are included, they must be set to the exact day (for example, 20031021000000). The PDS rounds the year up or down to ensure that the date falls within the range 1984 to 2049, inclusive.

For a task with start Ts and finish Tf, and a date range starting at S and running to F, assignments are returned that satisfy any of the following conditions:

• Ts is >= S AND <= F [assignment start date falls within the date range]

• Tf is >= S AND <= F [assignment finish date falls within the date range]

• Ts is <= S AND Tf >= F [assignment “surrounds” the date range]

Essentially, an assignment is returned if any portion falls within the date range (including the outer limits of the range).

If PeriodDateRange is incorrectly set (incorrect or missing PeriodStartDate or PeriodEndDate), the PDS returns an error.

IncludeTimephasedData

Optional. Boolean specifying whether or not the PDS is to return timephased assignment fields. Default is 0.

AdminProject

Optional. Integer specifying whether the user would like to have assignments returned from projects of type regular, admin (non-working time), or both. Default is 2 (both types). Valid AdminProject values are as follows:

ApprovalStatus

Optional. Integer specifying the resource manager approval state of the assignments that the user would like to have returned.

Note   ApprovalStatus refers to the resource manager, NOT to the project manager. The database table MSP_WEB_WORK_APPROVAL is for resource manager approval. Project manager approval data is stored in MSP_WEB_TRANSACTIONS.

Only those assignments having at least one timephased data segment of the specified approval status will be returned. Default is 3 (all assignments).

LockedDownByManager

Optional. Boolean specifying whether or not to include the value of MSP_WEB_ASSIGMENTS.WASSN_LOCKDOWN_BY_MANAGER in the <LockedDownByManager> tag of the reply for each assignment returned. Default is 0. For more information, see Changes for Service Pack 1 (SP1) in the topic About Timesheet Methods. For an example using LockedDownByManager, see Example Request and Reply.

Request Priorities

In all cases, assignments returned are only those for which the currently logged-on user has access permission. The priority of request parameters is as follows:

1. If Resources is set (one or more resources specified), AllResources, WUIDs, and AllAssignments are ignored. All assignments are returned that fall within the specified date range (if set; otherwise the Project Server date range is used) for the resources specified from the projects of type specified by AdminProject, and with the approval status specified by ApprovalStatus.

2. If AllResources is set (and Resources is NOT set), WUIDs and AllAssignments are ignored. Assignments returned are those falling within the specified date range, for all the resources to which the currently logged-on user has permission, from the projects of type specified by AdminProject, and with at least one timephased data segment of the approval status specified by ApprovalStatus.

3. If WUIDs is set (one or more assignments specified), and Resources and AllResources are NOT set, the PDS ignores AllAssignments and PeriodDateRange and returns the specified assignments. The AdminProject and ApprovalStatus parameters are ignored if set.

4. If AllAssignments is set (and Resources, AllResources and WUIDs are NOT set), the PeriodDateRange is ignored. Assignments returned are those from the projects of type specified by AdminProject, and with at least one timephased data segment of the approval status specified by ApprovalStatus.

5. IncludeTimephaseData is respected regardless of any other parameters. If IncludeTimephaseData is set to 1, timephased data is included for every assignment returned.

6. If only IncludeTimephasedData is set, assignments returned are those within the Project Server date range, from both regular and admin projects of any approval status, and timephased data is included in the return.

7. If only PeriodDateRange is set, assignments returned are those within the specified date range, from both regular and admin projects of any approval status.

8. If only PeriodDateRange and IncludeTimephasedData are set, assignments returned are those within the specified date range, from both regular and admin projects of any approval status, and timephased data is included in the return.

Return Value

If the request is successful, AssignmentsGet returns a successful HRESULT and STATUS, the assignment data requested, and the date range used (PeriodStartDate and PeriodEndDate). The date range in the reply is the custom date range in the request or Project Server’s date range. If the request specified WUIDs or AllAssignments, a date range is not returned.

If the request has LockedDownByManager set to 1, the reply includes the <LockedDownByManager> tag with the value of MSP_WEB_ASSIGMENTS.WASSN_LOCKDOWN_BY_MANAGER for each assignment returned (Project Server 2003 Service Pack 1 or above only).

Status Codes

The status codes for all three methods of the timesheet API (AssignmentsGet, AssignmentsSave, and AssignmentsProjectManagerUpdate) are consistent with status codes for ResourcesStatus. The valid status codes for AssignmentsGet are:

<Reply>
    <HRESULT></HRESULT>
    <STATUS></STATUS>
    <UserName></UserName>
    <AssignmentsGet>
        <PeriodDateRange>
            <PeriodStartDate></PeriodStartDate>
            <PeriodEndDate></PeriodEndDate>
        </PeriodDateRange>
        <Assignments>
            <Assignment>
                <WUID></WUID>
                -- Assignment Data --
                    OR
                <ReplyStatus></ReplyStatus>
            </Assignment>
                . . .
        </Assignments>
    </AssignmentsGet>
</Reply>

-- Assignment Data –-
[non-timephased]
    <Work></Work>
    <RemainingWork></RemainingWork>
    <ActualWork></ActualWork>
    <PercentWorkComplete></PercentWorkComplete>
    <Start></Start>
    <Finish></Finish>
    <ProjectID></ProjectID>
    <ProjectName></ProjectName>
    <ProjectType></ProjectType>
    <TaskName></TaskName>
    <TaskUID></TaskUID>
    <ResourceName></ResourceName>
    <ResourceUID></ResourceUID>
    <CurrentTrackingMode></CurrentTrackingMode>
    <Comments></Comments>
    <TaskIsSummary></TaskIsSummary>
    <AssignedToSummary></AssignedToSummary>
    <TaskIsMilestone></TaskIsMilestone>
    <ParentAssignmentUID></ParentAssignmentUID>
    <ParentAssignmentName></ParentAssignmentName>
    <ProjectManagerName></ProjectManagerName>
    <UpdateStatus></UpdateStatus>
    <IsDeletedFromProj></IsDeletedFromProj>
    <AdminProject></AdminProject>
    <LockedDownByManager></LockedDownByManager>
[timephased]
    -- above, plus... --
    <TimephasedDataSegments>
        <TimephasedData>
            <Type></Type>
            <WUID></WUID>
            <Day></Day>
            <Value></Value>
            <ReadOnly></ReadOnly>
            <ApprovalStatus></ApprovalStatus>
            <Approver></Approver>
        </TimephasedData>
            . . .
    </TimephasedDataSegments>

Remarks

The PDS determines whether the user has a valid Project Server account. If WUIDs are specified, the PDS checks that the user has access permission to read those assignments.

No error code is returned for an assignment that has been deleted. This is consistent with ResourcesStatus, which simply returns the tag <IsActive> with a value of 0 for a resource that has been deactivated. AssignmentsGet returns the tag <IsDeletedFromProj> based on MSP_WEB_ASSIGNMENTS.WASSN_DELETED_IN_PROJ.

To respect “protected actual work” in Microsoft Office Project 2003, each TimephasedData segment in the reply contains the tag <ReadOnly> that indicates whether the segment can be edited. If the timephased data segment is closed, the ReadOnly value is 1; that is, the data cannot be edited.

If requested, timephased assignment data is returned even if the project is using a non-timephased tracking method. For example, if the project tracking mode is pjTrackingMethodPercentComplete, or pjTrackingMethodTotalAndRemaining rather than pjTrackingMethodSpecifyHours, a request with IncludeTimephasedData set to 1 returns the timephased data.

Example Request and Reply

A Project Server administrator sends the following AssignmentsGet request to the sample database installed with Project Server 2003 SP1. The administrator has previously sent the AssignmentsSave request shown in Example Request and Reply for Assignment Locking. In the sample database, ResourceUID 24 is Bradley Beck and WUID 578 is the Start trial material production task in the 100X DVD Drive project (ProjectID 7).

<Request>
   <AssignmentsGet>
      <Resources>
         <Resource>
            <ResourceUID>24</ResourceUID>
         </Resource>
      </Resources>
      <WUIDs>
         <WUID>578</WUID>
      </WUIDs>
      <LockedDownByManager>1</LockedDownByManager>
   </AssignmentsGet>
</Request>

Resources in an AssignmentsGet request takes precedence over WUIDs. The reply includes data for assignment WUIDs 529, 537, 538, 578, 579, and 580. The following example shows only assignment data for WUID 578.

Note   The request parameter ResourceUID is returned in the reply as ResourceEUID.

<Reply>
   <HRESULT>0</HRESULT>
   <STATUS>0</STATUS>
   <UserName>Administrator</UserName>
   <AssignmentsGet>
      <PeriodDateRange>
         <PeriodStartDate>20040910000000</PeriodStartDate>
         <PeriodEndDate>20040921000000</PeriodEndDate>
      </PeriodDateRange>
      <Assignments>
         . . . [WUIDs 529, 537, and 538 are summary tasks]
         <Assignment>
            <WUID>578</WUID>
            <Work>14400000</Work>
            <RemainingWork>14400000</RemainingWork>
            <ActualWork>0</ActualWork>
            <PercentWorkComplete>0</PercentWorkComplete>
            <ProjectID>7</ProjectID>
            <ProjectName>New 1000X DVD Drive</ProjectName>
            <ProjectType>2</ProjectType>
            <TaskName>Start trial material production</TaskName>
            <TaskUID>67</TaskUID>
            <ResourceName>Bradley Beck</ResourceName>
            <ResourceEUID>24</ResourceEUID>
            <CurrentTrackingMode>1</CurrentTrackingMode>
            <Comments></Comments>
            <TaskIsSummary>0</TaskIsSummary>
            <AssignedToSummary>0</AssignedToSummary>
            <TaskIsMilestone>0</TaskIsMilestone>
            <ParentAssignmentUID>538</ParentAssignmentUID>
            <ParentAssignmentName>Trial Product Manufacture</ParentAssignmentName>
            <IsDeletedFromProj>0</IsDeletedFromProj>
            <AdminProject>0</AdminProject>
            <ProjectManagerName>Steve Masters</ProjectManagerName>
            <UpdateStatus>0</UpdateStatus>
            <LockedDownByManager>1</LockedDownByManager>
            <Start>20040819080000</Start>
            <Finish>20040929170000</Finish>
         </Assignment>
         . . . [WUIDs 579 and 580]
      </Assignments>
   </AssignmentsGet>
</Reply>