Knowledge Base

Clearing Picklist and Multiselect Fields with the REST API

By Abby posted 05-23-2017 18:39

  

Picklists and multiselect 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. PUT requests update 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 picklist or multiselect 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 picklist or multiselect field has the following properties: description, name, value, color, sortOrder, and the default flag. To clear a picklist, the relevant field to leave blank is the value field. Clearing a multiselect is an identical process, since a multiselect is a picklist 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 picklist field in an item is of type picklistoptions. First, query the item containing the picklist field by ID. Then, look for the field prepended by “PL$”; this is the ID of the picklist 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 picklist, send a PUT request containing all this information minus the “value” field to clear the picklist selection.

Example:

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\"

}" "https://jama-aembree.jamacloud.com/rest/latest/picklistoptions/502"

 

This method is valid for any version of Jama Software with the picklistoptions endpoint exposed. However, on Jama Software versions 8.14 and later, 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 picklist 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 multiselect 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\": {} 

} ]" "https://jama-aembree.jamacloud.com/rest/latest/items/6921"

 



#REST #bestpractices
0 comments
240 views