Custom Field values in history

Edit online

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)
Warning:

For values longer than 4000 characters function GetCustomValueString returns null.

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 in the history API is returning correct value for history records with such values. That makes it possible to know when such values were changed.

IsChanged Flag Access

The function IsCustomValueChanged determines if a custom field value for the record is different to a value from a previous history record for an entity.

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