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
.
- Query the item containing the pick list field by ID.
- 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$.” - 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
- Success Programs
- Success Catalog
- Datasheets
- Request a Solution Offering or Training from the Success Catalog
Please feel free to leave feedback in the comments below.
Related to
Comments
0 comments
Please sign in to leave a comment.