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)

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