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

Amanda Jennewein
Amanda Jennewein
  • Updated

Author: Amanda Jennewein

Updated: August 2024

Audience: Everyone

Products Applicable: Jama Connect®REST API

Use Case

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

Best Practice

The behavior of a PUT request might initially seem confusing, but this design choice intends to make PUT more practical. When you send a new value for a field, it updates the content of that field. If you don't send anything, it resets the field's contents. In Jama Software®, you can use this feature to have more control over the pick list state that is not available in the user interface. In the UI, once a pick list or multi-select selection is set, it cannot be cleared; it can only be changed.

However, with the API, you can leave the 'value' field blank to reset the selection.

A valid PUT request for a pick list or multi-select field should include the following properties: description, name, value, color, sortOrder, and the default flag. To clear a pick list, leave the value field blank. Clearing a multi-select follows the same process as clearing a pick list, as 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 names to be cleared similarly.

Implementation

The specific endpoint that will hold the value of a particular picklist field in an item is of type picklistoptions.

  1. Query the item containing the pick list field by ID.
  2. 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$.”
  3. 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.

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, there is an additional HTTP header known as PATCH. The PATCH header allows specific fields to be updated (and even cleared) without knowing 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\": {} 

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

References

Please feel free to leave feedback in the comments below.

Related to

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.