API: updateCustomFieldHierarchyValue
  • 3 Minutes to read
  • Dark
    Light

API: updateCustomFieldHierarchyValue

  • Dark
    Light

Article summary

  • Starting June 1, 2022, SmarterU will require all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
  • If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
  • Tags are required unless specified.

Description

The updateCustomFieldHierarchyValue adds, edits, or removes values from a hierarchical custom user field.

Who Has Access

The following users have access to the updateCustomFieldHierarchyValue:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>updateCustomFieldHierarchyValue</Method>
     
   <Parameters>   
      <CustomField>
         <ID></ID>
            - OR -
         <Name><![CDATA[]]></Name>

         <Values>
            <Value>
               <ValueAction></ValueAction>
               <ParentValueID></ParentValueID>
               <Value><![CDATA[]]></Value>
               <NewValue><![CDATA[]]></NewValue>
            </Value>
         </Values>
      </CustomField>
   </Parameters>
</SmarterU>

CustomField Tag Group

The CustomField tag group is a container for the custom fields you want to edit and their values.

<CustomField>
   <ID></ID>
      - OR -
   <Name><![CDATA[]]></Name>

   <Values>
      <Value>
         <ValueAction></ValueAction>
         <ParentValueID></ParentValueID>
         <Value><![CDATA[]]></Value>
         <NewValue><![CDATA[]]></NewValue>
      </Value>
   </Values>
</CustomField>

The CustomField tag may contain the following.

ID

The hierarchical custom field's system-generated identifier. This is the ID returned by the listCustomFields method. This tag is mutually exclusive with the Name tag.

Name

The hierarchical custom field's name. This tag is mutually exclusive with the ID tag.

Values

The Values tag is a container for the updates you want to make to a hierarchical custom user field. Refer to Values Tag Group

Values Tag Group

The Values tag group is a container for the updates you want to make to a hierarchical custom field. 

<Values>
   <Value>
      <ValueAction></ValueAction>
      <ParentValueID></ParentValueID>
      <Value><![CDATA[]]></Value>
      <NewValue><![CDATA[]]></NewValue>
   </Value>
</Values>

The Values tag may contain the following.

Value

The Value tag is a container for each change you want to make to a hierarchical custom field. Each change you want to make should be enclosed within a Value tag. 

The Value tag may contain the following.

TagDescription
ValueActionThe type of change you want to make to a hierarchical custom field. Acceptable values are:
  • Add - Add a value to a hierarchical custom field level. 
  • Remove - Remove a value from a hierarchical custom field level.
  • Update - Replace a value in a hierarchical custom field level. 
ParentValueIDThe system-generated identifier of the hierarchical custom field's parent. This is the ValueID returned by the getCustomFieldHierarchy method.

If ValueAction is set to Add and no ParentValueID is specified, the value will be added to the top level.
ValueIDIf ValueAction is set to Update, this is the system-generated ID of the hierarchical custom field that you want to update. This is the ValueID returned by the getCustomFieldHierarchy method.

If ValueAction is set to Remove and ParentValueID is not specified, this is a required tag. This is the system-generated ID of the hierarchical custom field that you want to remove. This is the ValueID returned by the getCustomFieldHierarchy method.
ValueIf ValueAction is set to Add, this is a required tag. This is the value to add to the hierarchical custom field.

If ValueAction is set to Remove and the ParentValueID is specified, this is the value to remove.
NewValueThis tag is required if ValueAction is set to Update. The updated value for a hierarchical custom field.  

Example API Calls

The examples below use the Location hierarchical custom field that has the following levels and values.

Diagram - Hiearchical Custom Field Levels and Values 20220802(2)

Adding a Value to a Level

The following example adds the city, Tampa, to the state, Florida.

<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Add</ValueAction>
      <ParentValueID>1200</ParentValueID>
      <Value><![CDATA[Tampa]]></Value>
   </Value>
</CustomField>

Adding a Value to the Top Level

The following example adds Canada to the Country level.

<CustomField>
   <Value>
      <ValueAction>Add</ValueAction>
      <Value><![CDATA[Canada]]></Value>
   </Value>
</CustomField>

Removing a Value from a Level

The following example removes the city, Orlando, from the state, Florida.

<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Remove</ValueAction>

      <ValueID>1210</ValueID>
         - OR - 
      <ParentValueID>1200</ParentValueID>
      <Value><![CDATA[Orlando]]></Value>

   </Value>
</CustomField>

Updating a Value

The following example replaces the city, Eugene, in the state, Oregon with Bend.

<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Update</ValueAction>

      <ValueID>1310</ValueID>
         - OR - 
      <ParentValueID>1300</ParentValueID>
      <Value><![CDATA[Eugene]]></Value>
      <NewValue><![CDATA[Bend]]></NewValue>

   </Value>
</CustomField>

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<SmarterU>
   <Result></Result>
   <Info>
      <ID></ID>
      <CustomField></CustomField>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>
</SmarterU>

The response may also contain the following. 

ID

The hierarchical custom field's system-generated identifier. 

Name

The hierarchical custom field's name

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <ID>1000</ID>
      <CustomField>Location</CustomField>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>
</SmarterU>

Error Codes

Error CodeMessage
UCFHV:01The ID provided is not valid.
UCFHV:02The name provided is not valid.
UCFHV:03The required permissions are not met to call the updateCustomFieldHierarchyValue method.
UCFHV:04The custom hierarchy field requested does not exist.
UCFHV:05The custom hierarchy field requested has no levels.
UCFHV:06The value action provided is not valid.
UCFHV:07The value ID provided is not valid.
UCFHV:08The parent value ID provided is not valid.
UCFHV:09The parent value requested does not exist.
UCFHV:10The value provided is not valid.
UCHFV:11The value already exists under the parent.
UCHFV:12The value requested does not exist.
UCHFV:13The new value provided is not valid.
UCHFV:14The new value already exists under the parent.

Was this article helpful?