How to update Description or Notes field of artifact via Web Services API

Products

• Rally On-Premise
• Rally SaaS

Issue/Introduction

A user tries to update a rich text field and receives an error indicating that the allowed size has been exceeded.

Resolution

There is a 32Kb limitation on the Description and Notes RTF fields and 2Kb limitation on all other RTF fields. Note that a 32Kb entry immediately becomes larger than 32Kb once any type of formatting is applied to the text. Some formatting types extend each character to more than 1 byte.

Here is a screenshot from the UI showing the error when Notes field is updated with the text that exceeds the limit.

When updating Description or Notes field via WS API an error may not be as straightforward because there could be other factors at play besides the size limit.

For example, if the same text succeeds in the UI and fail in WS API it is possible that there is a character in the text that was not properly escaped when the custom code (of the language of your choice) did not properly escaped it when preparing a JSON for the payload, but the Rally tool itself, in the UI was able to deal with it successfully.

This conversion to JSON is not something that the user does manually. For example, if you are using Ruby the conversion from a Ruby hash to JSON happens deep in the bowels of the language itself, and even the rally_api gem has nothing to do with it.

In the scenario when the culprit is unclear, a quick curl command can be useful to determine if updating a particular defect, or any defect with a simple text, e.g. "this is a test" completes successfully:

curl --header "zsessionid:<API Key - include the underscore before the key>" -H "Content-Type: application/json" -d"{\"Defect\":{\"Notes\":\"this is a test\"}}" https://rally1.rallydev.com/slm/webservice/v2.0/Defect/<DEFECT_OID>

where zsessionid:<API Key - include the underscore before the key> is the user's ApiKey, and <DEFECT_OID> is defect ObjectID.

Assuming that the curl test succeeds a more complex scenario can be tested.

To continue with Ruby example, see this Ruby script that reads a text file (specified as a command line argument), checks the file size against the limit, and if the size validation passes, proceeds with copying the content of the text file into a Rally artifact's Notes field. Details needed for this test are described in the Readme file.