Working with Custom Fields

Those are the different types of custom fiels which are used in the examples for this article:

895895

Select all Custom fields

/api/v2/userstories?where=(id=6366)&select={name,customvalues}

{  
   "items":[  
      {  
         "name":"Cleanup Sample Data link",
         "customValues":{  
            "customFields":[  
               { "name":"Cost", "type":"Money", "value":123.0 },
               { "name":"External ID", "type":"Number", "value":35679.0 },
               { "name":"Browser", "type":"MultipleSelectionList", "value":"Chrome" },
               { "name":"External reference", "type":"Text", "value":"US-6366" },
               { "name":"External link", "type":"TemplatedURL", "value":"6366" },
               {  
                  "name":"External Doc",
                  "type":"URL",
                  "value":{  
                     "url":"https://dev.targetprocess.com/v1.0/docs/custom-fields",
                     "label":"Guide article"
                  }
               },
               { "name":"Acceptance Criteria", "type":"RichText", "value":"<div>Everything should work perfectly</div>" },
               { "name":"Class", "type":"DropDown", "value":"B" },
               { "name":"Billed", "type":"CheckBox", "value":true },
               { "name":"Billing Date", "type":"Date", "value":null },
               {  
                  "name":"Hot fix",
                  "type":"Entity",
                  "value":{  
                     "id":2338,
                     "name":"Summer Summit US 2015",
                     "kind":"Release"
                  }
               },
               { "name":"Next story", "type":"Text", "value":"6387 userstory,3527 userstory" },
               { "name":"Expense", "type":"Number", "value":1476.0000 }
            ]
         }
      }
   ]
}

Select one or several custom fields

/api/v2/userstories?where=(id=6366)&select={name,Billed,Class,ExternalLink,Cost,ExternalDoc,Expense,BillingDate,Nextstory}

📘

All the names of the custom fields should be used without spaces

{
  "items": [
    {
      "name": "Cleanup Sample Data link",
      "billed": true,
      "class": "B",
      "externalLink": "6366",
      "cost": 123.0,
      "externalDoc": {
        "label": "Guide article",
        "uri": "https://dev.targetprocess.com/v1.0/docs/custom-fields"
      },
      "expense": 1476.0000,
      "nextstory": "6387 userstory,3527 userstory"
    }
  ]
}

If there is no such custom field defined for the entity, you will get BadRequest error:

{
  "Status": "BadRequest",
  "Message": "Property 'DueDate' does not exist in 'UserStory'.",
  "Type": "Presentational",
  "Details": {
    "Items": [
      {
        "Type": "Simple",
        "Message": {
          "Token": "Property '{property}' does not exist in '{type}'.",
          "Data": {
            "property": "DueDate",
            "type": "UserStory"
          },
          "Value": "Property 'DueDate' does not exist in 'UserStory'."
        }
      }
    ]
  },
  "ErrorId": "674cbbd7-2192-47ac-b08f-8541f3ad179c"
}

🚧

It is also possible to get the value of one custom field value from CustomValues collection:
select={class:CustomValues["Class"]}
select={class:CustomValues.Text("Class")}
This approach is considered deprecated.

Filter by Custom Fields

&where=(Cost>10)
&where=(Browser="Safari")

Field typeUsageExamples
Money
Number
As any other number fieldCost>10
ExternalID!=null
Text
RichText
DropDown
As any text fieldExternalreference!=null
AcceptanceCriteria.Contains("perfectly")
Class="B"
MultipleSelectionListAs a text field, which consists of all the selected options combines into one string separated by comma- to show items where ONLY this option is selected:
Browser="Safari"
- to show items where this option is selected
Browser.Contains("Safari")
CheckBoxAs any other boolean fieldBilled=true
Billed=false
DateAs any other date fieldBillingDate!=null
BillingDate>Today
BillingDate<Today.AddDays(5)
BillingDate>DateTime.Parse("2018-10-31")
Template URLAs a text field, without the template part (value only)Externallink!=null
Externallink="6366-df"
URLIt only possible to check if the value is setExternalDoc!=null
ExternalDoc=null
EntityAs a number field, which is ID of the entityHotfix!=null
Hotfix=null
Hotfix.Id=2338
MultipleEntitiesIt only possible to check if the value is setNextstory!=null
Nextstory=null
Calculated*Depending on the result:
- as a Number
- as a Date
- as a Text
Expense>0
Expense=null
Expense!=null

🚧

*When possible, it's recommended to use Metrics instead of Calculated Custom Fields

Order by Custom Fields

&orderby=Cost
&orderbydesc=ExternalID