Knowledge Base

 View Only

Clearing Pick List and Multi-Select Fields with the REST API

By Abby Embree posted 05-23-2017 15:39


Pick Lists and multi-select fields, like all other Jama Software item types, can be updated via the REST API. Updating an item via the REST API is done by sending a PUT request, which updates the fields of an item with new values. When submitting a PUT request, it is important to send the values of all the fields you intend to leave the same as well as the fields whose values you are changing. To get all the field values for an item, send a GET request.

The behavior of a PUT request may appear unintuitive at first, but the reason for this design decision is to make PUTs more useful. While sending a new value for a field updates the content of that field, neglecting to send anything will reset the contents of the field. In Jama Software, this functionality can be utilized to exercise additional control over pick list state that is not provided by the user interface. In the UI, a pick list or multi-select selection cannot be cleared once set, only changed; with the API, the ‘value’ field can be left blank to reset the selection.

A valid PUT request for a pick list or multi-select field has the following properties: description, name, value, color, sortOrder, and the default flag. To clear a pick list, the relevant field to leave blank is the value field. Clearing a multi-select is an identical process, since a multi-select is a pick list with an array of values instead of a single string. This functionality allows for every field except for name to be cleared in a similar fashion.

The specific endpoint to that will hold the value of a particular pick list field in an item is of type picklistoptions. First, query the item containing the pick list field by ID. Then, look for the field prepended by “PL$”; this is the ID of the pick list in your item whose value is stored inside the picklistoptions endpoint and queried specifically by the ID number following “PL$”. Finally, once you have the value of the pick list, send a PUT request containing all this information minus the “value” field to clear the pick list selection.


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{

    \"name\": \"clearme\",

    \"description\": \"\",

    \"active\": true,

    \"sortOrder\": 4,

    \"pickList\": 226,

    \"default\": false,

    \"type\": \"picklistoptions\"

}" ""

This method is valid for any version of Jama Software with the picklistoptions endpoint exposed. However, there is an additional HTTP header known as PATCH. The PATCH header allows certain fields to be updated (and even cleared) without having to know the content of any of the item’s other fields. This operation is relatively simple, as it can be performed on the item containing the pick list field. The only additional information needed is the field name ID, which is easily found in Admin > Item Types > [item type] > Config. The example below clears a multi-select field of an item by item ID.

curl -X PATCH --header "Content-Type: application/json" --header "Accept: application/json" -d "[ {

    \"op\": \"remove\",

    \"path\": \"/fields/sel$116\",

    \"value\": {} 

} ]" ""


#REST #bestpractices