Working with Custom Fields

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

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 type	Usage	Examples
Money Number	As any other number field	Cost>10 ExternalID!=null
Text RichText DropDown	As any text field	Externalreference!=null AcceptanceCriteria.Contains("perfectly") Class="B"
MultipleSelectionList	As 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")
CheckBox	As any other boolean field	Billed=true Billed=false
Date	As any other date field	BillingDate!=null BillingDate>Today BillingDate<Today.AddDays(5) BillingDate>DateTime.Parse("2018-10-31")
Template URL	As a text field, without the template part (value only)	Externallink!=null Externallink="6366-df"
URL	It only possible to check if the value is set	ExternalDoc!=null ExternalDoc=null
Entity	As a number field, which is ID of the entity	Hotfix!=null Hotfix=null Hotfix.Id=2338
MultipleEntities	It only possible to check if the value is set	Nextstory!=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