Custom Field values in history

Value Access

Suppose we have a custom field with the name Test CF for user story. We can access historical values of this custom field via a special function called GetCustomValueString.

The query to API will look like this:

.../api/v2/userstoryhistory?select={value:GetCustomValueString("Test CF")}

.../api/v2/userhistories/?select=GetCustomValueString("Exitdate")&where=(CurrentUser.Fullname=%27Test%20user%27)

🚧

Values longer than 4000 characters

For values longer than 4000 characters function GetCustomValueString returns null. So it is not possible to read such values or filter by them in the history API. However history for such values is tracked, saved and available on a history tab of a particular entity.

IsCustomValueChanged function is the history API is returning correct value for history records with such values. So it is possible to know when such values were changed.

IsChanged Flag Access

Also, it is possible to access isChanged flag for the custom field. It determines if a custom field value for the record is different to a value from a previous history record for an entity. The access to the flag is done via special function IsCustomValueChanged.

Example of a query:

.../api/v2/userstoryhistory?select={name,isChanged:IsCustomValueChanged("Test CF")}

/api/v2/userhistories/?select={Exitdate:GetCustomValueString("Exitdate"),ischanged:IsCustomValueChanged("Exitdate")}&where=(CurrentUser.Fullname=%27Test%20User%27)

Filtering

Historical records can be filtered by either custom field value or it's IsChanged flag:

Example of a query with filtering:

.../api/v2/userstoryhistory?select={name,value:GetCustomValueString("Test CF"),isChanged:IsCustomValueChanged("Test CF")}&where=GetCustomValueString("Test CF")=="test value" AND IsCustomValueChanged("Test CF") == true

Type Conversion

Sometimes it is required to convert a custom field value to a specific data type:

• SafeConvert.ToDecimal
• SafeConvert.ToDateTime
• SafeConvert.ToBoolean
• SafeConvert.ToString

Example of a filter with type conversion:

.../api/v2/userstoryhistory?select={name,value:GetCustomValueString("Test boolean CF"),isChanged:IsCustomValueChanged("Test boolean CF")}&where=SafeConvert.ToBoolean(GetCustomValueString("Test boolean CF"))==true