Get allowed values of user data attribute through API request (v.22)


The algorithm for determining the allowed values of user data attribute (aka "Custom property") is pretty complicated. It involves a filtering, cascade values, accessing other entity types, etc. For a long time, it has been tough for external apps to reliably obtain a list of allowed values for any user data attribute.

In v.22 this changes - there is a new API request specifically for that purpose.


Defining allowed values

User defined data attributes in can be set up to provide two types of allowed values:

1. Through the entity CustomPropertyAllowedValues

It defines individual property value entries for a specific custom property.


2. Through the attribute AllowedValuesEntityName

The attribute defines the entity which entries are the allowed values for the custom property. Only entities that provide Code and Name data members are supported. The Code of the entity is the Value of the custom property value, the Name of the entity is the Description and the Id is the ValueId. For example the Code attribute for entity Products is PartNumber and the Name attribute is Name, so a product with Id=7a2fab03-f715-4de4-ae14-0112e05b8fd9, PartNumber=001 and Name='Milk chocolate' is represented by CustomPropertyValue


"Value": "001",

"Description": { "EN": "Milc chocolate"},

"ValueId": "7a2fab03-f715-4de4-ae14-0112e05b8fd9"


The new API

In v.22, the Domain API provides a method, called GetAllowedCustomPropertyValues. This method is defined for each entity and returns a list of allowed property values for a given custom property.


Here is a link to the method in the documentation (The link is for entity Customers but this method is available for all entities):


The method returns a list of allowed values for the specified custom property for the given entity object. If the allowed values entity supports ordering by Code the the result is ordered by CustomPropertyValue.Value ascending. If ordering is not supported the result is not ordered. The parameter orderByDescription provides a way to order the result by CustomPropertyValue.Desctiption but the ordering is done only if supported (most of the entities do not support ordering by Name).

Note that the result is filtered by the filter specified in AllowedValuesFilterXml and also the parent values for the entity object of parent custom property defined in AllowedValuesParentEntity.



The example below gets the allowed values for custom property CustomProperty_TRD of SalesOrder with Id=7a2fab03-f715-4de4-ae14-0112e05b8fd9. The parameters skip and top are used to limit the count of returned values. The parameter customPropertyCode receives the Code of the desired custom property which in this case is 'TRD' (Link to testdb):



Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk