Knowledge Base

Edit an Item using the Jama REST API

By John posted 10-08-2015 20:21

  
Overview
This article describes how to use the Jama REST API to edit an item.  This is very common in custom integrations, but can crop up in other applications as well.

Before you begin
This process assumes you have an application which can interact with the Jama REST API, and which can consume, edit, and generate JSON data.  It also assumes that the edits you’re making are on items in a live project.  If no users or other applications will be interacting with the items you’ll be editing then the ‘Lock’ and ‘Unlock’ steps can be omitted.  

Process
The basic workflow for editing an item in Jama using the REST API involves 5 steps.  Before you begin you need the item’s ID so you can lock it.  Since you intend to edit the item, you’ve probably already gotten its ID and stored it somewhere.


CAUTION:  PUT’s definition requires that it create or replace a resource.  Any data not supplied in the PUT request will not exist in the item after the PUT completes--even if it existed before.  The specification of PUT can be found at https://tools.ietf.org/html/rfc7231#section-4.3.4.

1. Lock the item to be edited, otherwise there’s a small chance that someone can make changes to the item while you are editing it.  If someone else has locked the item, your attempt to lock it may fail.



2. Now GET the item you just locked.



3. Copy and paste the “data” object into the PUT request and edit the “description” field.



4. When you make the put request the entire resource is replaced with this new data object.  


5. Now unlock the item and the edit is complete.


#REST
4 comments
240 views

Permalink

Comments

John
03-30-2016 19:13

Shiran,

There are some situations where you need to remove certain read-only fields from the PUT request body.  In most cases the system can tell that the data is the same and lets the PUT go through, but sometimes (usually with dates) it can't tell that they're the same.  I've seen this most often with test runs.

PUT will not affect the relationships between the item you're updating and other items.

John

Shiran
03-30-2016 06:28

Thanks Grant. I found that I must enter the old fields as well and not only the field I want to change ("Name", for example), else PUT deletes them.

Grant
03-24-2016 22:31

I found that in order to do a PUT for an item, I had to remove the createdDate and modifiedDate fields (from GET results) as I was getting the same error.

Also, when using the bare minimum data for a PUT, I had to include the parent item which the PUT document says is optional...

{
    "location": {"parent": {"item": 31037711}},
    "fields": {"name": "Updated from REST"}
}
This worked!

Shiran
03-17-2016 16:11

Hi!
1. I got an error saying: "You cannot set read-only fields. fields: createdDate, modifiedDate"
2. Just to be sure- PUT will not (!) delete upstream/downstream relationships of the item we want to edit, right?

Thanks John.