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}

Note: 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"
}

Warning: 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
Money Number	As any other number field	Cost > 10 ExternalID!=null
Text RichText DropDown	As any text field
MultipleSelectionList	As a text field, which consists of all the selected options combines into one string separated by comma
CheckBox	As any other boolean field
Date	As any other date field
Template URL	As a text field, without the template part (value only)
URL	It only possible to check if the value is set
Entity	As a number field, which is ID of the entity
MultipleEntities	It only possible to check if the value is set
Calculated*	Depending on the result:- as a Number- as a Date - as a Text

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

Order by Custom Fields

&orderby=Cost &orderbydesc=ExternalID