(350).png){kind=logo}
API: updateCustomFieldHierarchyValue
- 3 Minutes to read
- Print
- DarkLight
API: updateCustomFieldHierarchyValue
- 3 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
- 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:
- Users with the Manage Account Settings account permission.
- Administrators and owners.
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.
| Tag | Description |
|---|---|
| ValueAction | The type of change you want to make to a hierarchical custom field. Acceptable values are:
|
| ParentValueID | The 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. |
| ValueID | If 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. |
| Value | If 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. |
| NewValue | This 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.
.png)
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 Code | Message |
|---|---|
| UCFHV:01 | The ID provided is not valid. |
| UCFHV:02 | The name provided is not valid. |
| UCFHV:03 | The required permissions are not met to call the updateCustomFieldHierarchyValue method. |
| UCFHV:04 | The custom hierarchy field requested does not exist. |
| UCFHV:05 | The custom hierarchy field requested has no levels. |
| UCFHV:06 | The value action provided is not valid. |
| UCFHV:07 | The value ID provided is not valid. |
| UCFHV:08 | The parent value ID provided is not valid. |
| UCFHV:09 | The parent value requested does not exist. |
| UCFHV:10 | The value provided is not valid. |
| UCHFV:11 | The value already exists under the parent. |
| UCHFV:12 | The value requested does not exist. |
| UCHFV:13 | The new value provided is not valid. |
| UCHFV:14 | The new value already exists under the parent. |
Was this article helpful?