Update an entity

To update an entity, perform a PUT on the individual entity, passing an XML or JSON string that contains the fields to be changed. This example uses a defect, but the procedure is the same for all entities.

The procedure is different depending on whether versioning is enabled for the project. See How to Check if Versioning is Enabled

  1. Get the list of fields.
    To get the list of fields for an entity, use customization fields Collection. See the example of getting the defects fields.
    Do not use the field list returned by retrieving a single entity. The data returned for an entity may contain calculated fields that cannot be POSTed or PUT.
  2. Create an XML or JSON string that contains the fields to be changed. XML input must comply with the Entity Schema. JSON input must be of the same format as data returned from a GET operation on the entity.
  3. If versioning is not enabled, lock the entity if locking is supported for the entity. *
    If versioning is enabled, check-out the entity.
  4. PUT the data to the defect resource. For example:

    PUT http://SERVER:PORT/qcbin/rest/domains/{domain}/projects/
       {project}/defects/123 HTTP/1.1
    Accept: application/xml
    Content-Type: application/xml

    or Content-Type: application/json

    Example of input body to change the description of a defect:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <Entity Type="defect">
        <Field  Name="description">
            <Value>Problem observed only on GET operations.</Value>
  5. On success, the HTTP return value is 200. The returned string is the complete data of the updated entity.
  6. If versioning is not enabled, delete the lock if the entity is locked. *
    If versioning is enabled, check-in the entity.

See also: attachments Collection: Files of an Entity

* Locking is not required to perform an update, but we strongly recommend the use of locking to preserve data integrity.