EnterpriseFieldUpdate Method

Description

The Service for Enterprise Data Maintenance (EDM) provides the EnterpriseFieldUpdate method to synchronize custom field value lists between a Line of Business (LOB) application and Microsoft Office Project Server 2003. The EnterpriseFieldUpdate method adds and updates enterprise outline codes and other enterprise custom fields that contain value lists in the Enterprise Global template.

Syntax

The XML structure of an OutlineCode list is hierarchical; that is, a Nodes element can contain one or more Node elements, and Nodes can also contain a child Nodes element. A CustomFields list is flat; that is, a custom field ValueList contains one or more ValueItem elements, it does not contain a child ValueList element.

<Request>
   <EnterpriseFieldUpdate>
      <OutlineCode>
         <UID></UID>
         <Name></Name>
         <Warpable></Warpable>
         <SelectLeafOnly></SelectLeafOnly>
         <SelectionRequired></SelectionRequired>
         <Nodes>
            <Node>
               <Description/>
               <UID></UID>
               <Value></Value>
               <Nodes>
                  <Node>
                     <Description/>
                     <UID></UID>
                     <Value></Value>
                  </Node>
                  <Node>
                     <Description/>
                     <UID></UID>
                     <Value></Value>
                  </Node>
               </Nodes>
            </Node>
         </Nodes>
         <Masks>
            <Mask>
               <Level></Level>
               <Type></Type>
               <Length></Length>
               <Separator></Separator>
            </Mask>
         </Masks>
      </OutlineCode>
      <CustomFields>
         <CustomField>
            <FieldID></FieldID>
            <FieldName></FieldName>
            <SelectionRequired></SelectionRequired>
            <Default></Default>
            <ValuelistInUse></ValuelistInUse>
            <ValuelistSortOrder></ValuelistSortOrder>
            <ValueList>
               <ValueItem>
                  <Value></Value>
                  <Description></Description>
                  <Phonetic></Phonetic>
               </ValueItem>
               <ValueItem>
                  <Value></Value>
                  <Description></Description>
                  </Phonetic></Phonetic>
               </ValueItem>
            </ValueList>
         </CustomField>
      </ CustomFields>
   </EnterpriseFieldUpdate>
</Request>

Parameters

In general, the EnterpriseFieldUpdate method combines the PDS methods EnterpriseOutlineCodesHierarchical, EnterpriseOutlineCodeUpdate, and EnterpriseCustomFieldsUpdate. See the topics of those PDS methods for parameter descriptions, with the following additions and exceptions:

OutlineCode

Optional. Calls EnterpriseOutlineCodeUpdate with the OutlineCode block.

Warpable

Optional. Valid parameter values in the request are 0 (False) and 1 (True). These are the same values in the PDS method EnterpriseOutlineCodeUpdate. If Warpable is in the reply, the values can be 0 (False) or 32 (True), as in the PDS method EnterpriseOutlineCodesHierarchical. (The value representing True can be 1 if Warpable was previously set by the PDS, or 32 if set by Project Professional.)

UID

Optional. If an outline code UID is included, the Service for EDM updates the matching outline code in the Enterprise Global template.

If a UID is not included, the Service for EDM matches the outline code hierarchy based on values of the parent and children. The following table shows examples.

The Service for EDM also matches outline codes based on patterns of children, to check for parent updates.

CustomFields

Optional. Valid parameters are the same as in the PDS EnterpriseCustomFieldsUpdate method.

Return Value

The reply structure depends on the verbosity level and the request data. 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. Set the verbosity to 3 to show details of merging outline codes in addition to all PDS requests and replies.

<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

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

Conversion values for FieldID and outline code UID are listed in Field ID Values for Enterprise Custom Fields.

The Service for EDM first determines whether the Enterprise Global template is checked out and the user has access permission. It then calls the following PDS methods, depending on the request:

EnterpriseOutlineCodesHierarchical gets the current outline code list in hierarchical format (if required).

The Service for EDM determines from the previous call whether updates need to be made. If so, it calls the following PDS methods:

ProjectsCheckout checks out the Enterprise Global template.

EnterpriseOutlineCodeUpdate makes the requested enterprise outline code changes (if any changes are needed).

EnterpriseCustomFieldsUpdate updates the value lists for non-outline code fields (if required).

ProjectsCheckin checks in the Enterprise Global template.

Any inconsistencies or failures result in failure of the entire call.