The RefStringField type is used to represent certain string-valued reference fields whose value must be selected from a predefined set of options. Typically, system fields and other fields with a fixed set of options are represented as RefStringField objects.
RefStringField objects contain the following properties:
-
Value - The internal string value of the field. The Value must be used when setting the value of the field in a Create or Update request.\
-
DisplayValue - The display value of the field.\
Basic Read Request
The following example illustrates the syntax for a request for the default value of a RefStringField in a Read method call.
Request
{
"Status":1
}
Response
{
"Status":"57998"
}
Detailed Read Request
The following example illustrates the syntax for a request for all properties of a RefStringField in a Read method call.
Request
{
"Status":{
"Value":1,
"DisplayValue":1
}
}
Response
{
"Status":{
"Value":"57998",
"DisplayValue":"Assigned"
}
}
Basic Create/Update Request
The following example illustrates the syntax for including a RefStringField in a Create or Update method call using the sub-properties of the
Request
{
"Status":"57998"
}
Response
{
"Status":"57998"
}
Detailed Create/Update Request
The following example illustrates the syntax for including a RefStringField in a Create or Update method call.
Note that, when including sub-properties of the object in a Create/Update request, only the default property, in this case the Value, is used. All other properties are ignored, and should only be included in the request if you want them to appear in the response.
Request
{
"Status":{
"Value":"57998",
"DisplayValue":"Assigned"
}
}
Response
{
"Status":{
"Value":"57998",
"DisplayValue":"Assigned"
}
}
Common Pitfalls
The following are some examples that illustrate incorrect syntax for including RefStringField in requests.
Invalid Create/Update Request - Integer-Valued Value
The default Value property of a RefStringField is a string, and numeric types are not valid, even if the Value in question is a string representation of an integer, as is often the case. In the example below, the call will fail because the Value is passed as an integer.
{
"Status":{
"Value":57998
}
}
Invalid Create/Update Request - Table Value
RefStringField fields are single-valued fields, and do not support using array syntax for setting or retrieving the field value. This is in contrast to EnumField fields which, while their values must also be selected from a set of options, are table- or multi-valued fields and use the array syntax. In the example below, the call will fail because the value of the field is passed as an array of objects, instead of as a single object or value.
{
"Status":[
{
"Value":57998
}
]
}
Invalid Create/Update Request - Missing Value
When setting the value for a RefStringField, you must use the Value of the value that you want to set. Passing only the DisplayValue will result in the value not being set correctly. In the example below, the call will fail because the Value is missing from the request.
{
"Status":{
"DisplayValue":"Abandoned"
}
}
Invalid Create/Update Request - Mismatched Value and DisplayValue
When setting the value for a RefStringField in a Create or Update request, only the Value property of the field is observed. In the example below, a DisplayValue is passed that does not match the supplied Value. This request will succeed; however it may have unintended effects, as the value of the field will be set to the value passed as the Value (in this case "57998", which is the Value for the "Assigned" value), and not the "DisplayValue".
{
"Status":{
"Value":"57998",
"DisplayValue":"Abandoned"
}
}
Invalid Create/Update Request - Deprecated Syntax
In previous version of the API, the default property for RefStringField objects was the Key. When setting the value for a RefStringField it is still possible to use the Key to set or to retrieve the value of the field; however, this syntax is deprecated and should no longer be used.
{
"Status":{
"Key":"57998"
}
}