Resource Data Methods

  • Article

Description

The Service for Enterprise Data Maintenance (EDM) provides the resource data methods ResourcesUpdate and ResourcesDeactivate. These methods aggregate the Project Data Service (PDS) methods necessary to add, update, and delete resources from the Enterprise Resource Pool on Microsoft Office Project Server 2003. You could do the same work by calling the individual PDS methods. The Service for EDM provides an easier and higher-level API because it handles the necessary project and resource check-in, checkout, and status checks.

The resource data function includes support for resource outline codes. However, because the Service for EDM does not currently accept the UID parameter for a field column, it cannot recognize Enterprise Resource Multi-Value fields or value lists in resource custom fields.

Syntax

<Request>
   <ResourcesUpdate>
      <Resources>
         <Resource>
            <EUID></EUID>
            <Name></Name>
            <Phonetic></Phonetic>
            <Active></Active>
            <NTAccount></NTAccount>
            <EmailAddress></EmailAddress>
            <Type></Type>
            <IsGeneric></IsGeneric>
            <Initials></Initials>
            <Code></Code>
            <Group></Group>
            <WorkGroup></WorkGroup>
            <MaxUnits></MaxUnits>
            <CanLevel></CanLevel>
            <AccrueAt></AccrueAt>
            <StandardRate></StandardRate>
            <StandardRateFormat></StandardRateFormat>
            <OvertimeRate></OvertimeRate>
            <OvertimeRateFormat></OvertimeRateFormat>
            <CostPerUse></CostPerUse>
            <Columns>
               <Column>
                  <Name></Name>
                  <Value></Value>
               </Column>
            </Columns>
         </Resource>
      </Resources>
   </ResourcesUpdate>
   <ResourcesDeactivate>
      <Resources>
         <Resource>
            <EUID></EUID>
            <Name></Name>
         </Resource>
      </Resources>
   </ResourcesDeactivate>
</Request>

Parameters

In general, the resource data syntax combines the PDS methods ResourcesUpdate, ResourceCodeValuesUpdate, and ResourceDeactivate. See the topics of those PDS methods for parameter descriptions, with the following exceptions:

ResourcesUpdate

Optional. Has the same name as the PDS method, but uses the EUID parameter instead of ResourceUID. The EDM syntax also includes the optional Columns parameter for resource outline codes.

A request that includes ResourcesUpdate can update an existing resource or add a new resource. ResourcesUpdate must at least include the resource Name. All other resource parameters are optional.

When creating a new resource in the Enterprise Resource Pool the Active parameter is invalid and will be ignored. All new resources are active.

EUID

Optional. If the Enterprise Unique ID is specified, the resource is synchronized. If the EUID is invalid, the call fails. If no EUID is specified, the Service for EDM tries to match the Name.

Note   In the PDS ResourcesUpdate method, the EUID is the ResourceUID parameter.

Name

Required. If Name exists in the Enterprise Resource Pool and there is no EUID specified, the resource is synchronized in Project Server. If Name does not exist, the resource is added to the Enterprise Resource Pool.

Columns

Optional. Supports resource outline codes. Does not support Enterprise Resource Multi-Value fields or value lists in resource custom fields.

ResourcesDeactivate

Optional. The Service for EDM calls the PDS method ResourceDeactivate for each resource in the request.

Return Value

The reply structure depends on the verbosity level and the request data. See the Example section for a simple case. In general, the reply to a Service for EDM request shows a record of Conversations between the Service for EDM and the PDS.

AllSucceeded has a value of 0 (False) or 1 (True). One Conversation can include the record of one or more PDS requests and replies, and always ends with a Service for EDM <Summary> tag with STATUS and HRESULT for that conversation.

A general reply with Verbosity set to 2 shows all of the PDS requests and replies. If the Verbosity is set to 1, the reply shows only the failed PDS requests.

<Reply>
   <AllSucceeded></AllSucceeded>
   <Conversations>
      <Conversation>
         <Request></Request>
         <Reply></Reply>
         <Summary>
            <STATUS></STATUS>
            <HRESULT></HRESULT>
         </Summary>
      </Conversation>
      <Conversation>
         <Request></Request>
         <Reply></Reply>
         <Request></Request>
         <Reply></Reply>
            -- can be multiple PDS requests and replies --
         <Summary>
            <STATUS></STATUS>
            <HRESULT></HRESULT>
         </Summary>
      </Conversation>
   </Conversations>
</Reply>

Remarks

Multiple resources are valid in a single call.

Use the PDS method ResourceCodeValuesUpdate if it is necessary to change Enterprise Resource Multi-Value fields or value lists in resource custom fields.

Note The Service for EDM method ResourcesDeactivate does not currently accept the ServerPath parameter. If a resource has an account on a computer using Microsoft Windows SharePoint® Services, that account is not deleted; the resource retains access to Windows SharePoint Services.

To determine which PDS calls a specific Service for EDM request makes, set the verbosity level to 2 or 3 (see Configuring the Service for EDM).

The Service for EDM calls the PDS method ResourcesStatus to determine whether to add or update resources. It can then call the following PDS methods, depending on the request:

  • ResourcesCheck,****to validate the resource name, NT account, and other resource data

  • ProjectsCheckout, to check out the Enterprise Resource Pool project

  • ResourcesCheckout, to check out the specified resources (if the resources exist in the ResourcesUpdate block of the EDM request)

  • ResourcesAdd,****to add a new resource or resources to the Enterprise Resource Pool

  • ResourcesUpdate,****to update the resource core information (if the resources exist in the ResourcesUpdate block of the EDM request)

  • ResourceDeactivate, to deactivate (not delete) a resource in the Enterprise Resource Pool

  • ResourceCodeValues, to validate the value specified for the new resource (if required)

  • ResourceCodeValuesUpdate,****to create the values for the new resource (if required)

  • ResourcesCheckin,****to check in the resource

  • ProjectsCheckin, to check in the Enterprise Resource Pool Project

The Service for EDM ensures that each resource is a valid member of the Project Server Enterprise Resource Pool. If any synchronization fails in a call, then all synchronizations fail.

Note   If the resource name matches a resource account that is established only in Microsoft Office Project Web Access 2003, the Service for EDM ResourcesUpdate method fails. This is because the PDS method ResourcesCheck returns status code 2030, rsResourceWillBeMergedWithUserAccountOnImport.

Example

Following is a simple Service for EDM request to add a resource to the Enterprise Resource Pool. The user log on name is Administrator.

<Request>
   <ResourcesUpdate>
      <Resources>
         <Resource>
            <Name>EDM Tester</Name>
         </Resource>
      </Resources>
   </ResourcesUpdate>
</Request>

If the verbosity level is 2 (show successes, errors, and all PDS calls), the reply shows the following steps. Step numbers are also noted in the Reply XML text.

  1. Call ProjectsCheckout to check out the Enterprise Resource Pool project.

  2. Verify with ResourcesCheck that the proposed resource name has valid characters and is unique in Project Server.

  3. Call ResourcesStatus to check if the resource exists in the Enterprise Resource Pool. The ReplyStatus of 2000 means rsResourceNotFound.

  4. Because the resource does not exist, call ResourcesAdd to add it. The PDS reply contains the Name and ResourceUID (EUID) of the added resource.

  5. Call ResourceCodeValues to get the list of values applied to the resource.

  6. Call ProjectsCheckin to check in the Enterprise Resource Pool project.

<Reply>
   <AllSucceeded>1</AllSucceeded>
   <Conversations>
      <Conversation>
--1--    <Request>
            <ProjectsCheckout>
               <Project>
                  <ProjectType>3</ProjectType>
               </Project>
            </ProjectsCheckout>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
         </Reply>
         <Summary>
            <STATUS>0</STATUS>
            <HRESULT>0x0</HRESULT>
         </Summary>
      </Conversation>
      <Conversation>
--2--    <Request>
            <ResourcesCheck>
               <Resource>
                  <ResourceName>EDM Tester</ResourceName>
               </Resource>
            </ResourcesCheck>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
         </Reply>
--3--    <Request>
            <ResourcesStatus>
               <Resource>
                  <ResourceName>EDM Tester</ResourceName>
               </Resource>
            </ResourcesStatus>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
            <ResourcesStatus>
               <Count>1</Count>
               <ResourceStatus>
                  <ResourceName>EDM Tester</ResourceName>
                  <ReplyStatus>2000</ReplyStatus>
               </ResourceStatus>
            </ResourcesStatus>
         </Reply>
--4--    <Request>
            <ResourcesAdd>
               <Resources>
                  <Resource>
                     <Name>EDM Tester</Name>
                  </Resource>
               </Resources>
            </ResourcesAdd>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
            <ResourcesAdd>
               <Resources>
                  <Resource>
                     <Name>EDM Tester</Name>
                     <ResourceUID>3</ResourceUID>
                  </Resource>
               </Resources>
            </ResourcesAdd>
         </Reply>
--5--    <Request>
            <ResourceCodeValues>
               <ResourceName>EDM Tester</ResourceName>
               <ReturnStructures>1</ReturnStructures>
               <AutoCheckout>0</AutoCheckout>
            </ResourceCodeValues>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
            <ResourceCodeValues>
               <ResourceUID>3</ResourceUID>
               <ResourceName>EDM Tester</ResourceName>
               <ResourceCheckedOut>0</ResourceCheckedOut>
               <ResourceCheckedOutUser>Administrator</ResourceCheckedOutUser>
               <CurrencySymbol/>
               <CurrencyPosition>0</CurrencyPosition>
               <CurrencyDigits>2</CurrencyDigits>
               <Columns/>
            </ResourceCodeValues>
         </Reply>
         <Summary>
            <STATUS>0</STATUS>
            <HRESULT>0x0</HRESULT>
         </Summary>
      </Conversation>
      <Conversation>
--6--    <Request>
            <ProjectsCheckin>
               <Project>
                  <ProjectType>3</ProjectType>
               </Project>
            </ProjectsCheckin>
         </Request>
         <Reply>
            <HRESULT>0</HRESULT>
            <STATUS>0</STATUS>
            <UserName>Administrator</UserName>
         </Reply>
         <Summary>
            <STATUS>0</STATUS>
            <HRESULT>0x0</HRESULT>
         </Summary>
      </Conversation>
   </Conversations>
</Reply>