Updates the specified requirement.
Use the operation to replace the contents of an existing requirement with new contents in QAComplete.
To update individual fields of an existing requirement, use the …/requirements/{Id} (PATCH) operation.
To add a new requirement to your project, use the …/requirements (POST) operation.
Authentication
Basic authentication using a user’s login and password. See Authentication for details.
Security Rights
The authenticating user must belong to a security group that has the Update privilege for Requirement.
Request Format
To update the requirement, send a PUT request to the following URL:
URL parameters
ProjectId : integer, required
The ID of the project, to which the requirement belongs.
Id : integer, required
The ID of the requirement that you want to update.
Body parameters
In the request body, pass the RequestRequirementPut JSON object that describes the requirement’s new contents:
"Title": "string",
"Status": "string",
"Active": "boolean",
"ActFinish": "Date",
"ActHrs": "double",
"ActStart": "Date",
"BusinessRule": "string",
"Comments": "string",
"CustomFields": [
{
"Id": "string",
"Name": "string",
"Value": "string"
}
],
"Description": "string",
"EstFinish": "Date",
"EstHrsRemaining": "double",
"EstHrs": "double",
"EstStart": "Date",
"FolderId": "int",
"Grouping": "string",
"Keywords": "string",
"OriginalId": "int",
"OwnerUserId": "int",
"PctComplete": "int",
"SubGrouping": "string"
}
Some string property values (for example, Status) are based on the choice lists defined in your QAComplete project. You can find these values in the Requirements > Show Requirements > Actions > Manage Choice Lists panel in QAComplete.
The property values you do not specify are set to their default values.
Title : string (max 255 chars), required
The requirement title (name). Cannot be empty.
Status : string (max 100 chars), required
The requirement status based on a choice list. Cannot be empty.
Active : boolean
Specifies whether the requirement is enabled (active).
ActFinish : dateTime
The actual date when the requirement was completed.
ActHrs : double
Actual hours spent working on the requirement. Default: 0.
ActStart : dateTime
Actual start date for working on the requirement.
BusinessRule : string
Business rule associated with the requirement. Can include HTML markup. Default value: empty string.
Comments : string
Comments to the requirement. Can include HTML markup. Default value: empty string.
CustomFields : array of objects
An array of CustomFields objects that describe custom fields and their values:
{
"Id": "string",
"Name": "string",
"Value": "string"
}
Id : string, required
The unique identifier of the custom field. Must be in the CustomN format, where N is the custom field’s number (index).
Name : string
The field name.
Value : string
The field value.
Description : string (max 65000 chars)
Long description of the requirement. Can include HTML markup. Default value: empty string.
EstFinish : dateTime
The estimate date of the finishing the requirement.
EstHrs : double
Estimated hours to finish the requirement. Default: 0.
EstHrsRemaining : double
Estimated remaining hours for finishing the requirement. Default: 0.
EstStart : dateTime
Estimated start date for working on the requirement.
FolderId : integer
The ID of the folder containing the requirement, or 0 if the requirement not in any folder.
Grouping : string
The group that contains the requirement.
Keywords : string
Keywords of the requirement.
OriginalId : integer
For importing: to retain the original key that was imported. Default: 0.
OwnerUserId : integer
The ID of the user who owns the requirement. Default value: the ID of the current user.
SubGrouping : string
The sub group that contains the requirement.
PctComplete : integer
Percentage complete of requirement completing. Default: 0.
A sample request:
PUT http://yourserver.com/rest-api/service/api/v1/projects/11873/requirements/1 HTTP/1.1
Host: yourserver.com
Connection: keep-alive
Content-Type: application/json
Accept: application/json
Authorization: Basic am9obkBleGFtcGxlLmNvbTpwQHNzd29yZA==
Content-Length: 264
{
"Title": "Implement search feature",
"Status": "Active",
"Description": "Need to allow users to search the desired information.",
"EstHrs": 10,
"EstFinish": "2015-09-20T17:00:00",
"EstStart": "2015-09-18T07:00:00"
}
A sample request made by using cURL:
curl -u [email protected]:p@ssword -d @requirement.txt -H "Content-Type: application/json" -H "Accept: application/json" http://yourserver.com/service/api/v1/projects/11873/requirements/1
Response Format
On success, the operation responds with HTTP status code 200 and returns a JSON object with the updated requirement information.
A sample response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1015
{
"id": 1,
"title": "Implement search feature",
"status": "Active",
"active": "true",
"project_id": 11873,
"__permissions": {
"acl": 7
},
"act_finish": "2015-09-10T00:00:00.0000000",
"act_hrs": 0,
"act_start": "2015-09-09T00:00:00.0000000",
"assignee_user_id": 0,
"date_created": "2015-09-10T08:39:19.9670000",
"date_last_escalated": "0001-01-01T00:00:00.0000000",
"date_opened": "2015-09-10T09:51:48.0000000",
"date_updated": "2015-09-10T09:51:48.0000000",
"description": "Need to allow users to search the desired information.",
"est_finish": "2015-09-20T17:00:00.0000000",
"est_hrs": 10,
"est_hrs_remaining": 10,
"est_start": "2015-09-18T07:00:00.0000000",
"folder_id": 0,
"custom_fields": [
{
"id": "Custom1",
"name": "Area",
"value": ""
}
],
"import_id": 0,
"last_escalation_rule_id": 0,
"nbr_escalations": 0,
"nbr_events": 0,
"nbr_files": 0,
"nbr_files_not_secured": 0,
"nbr_notes": 0,
"nbr_tasks": 0,
"original_id": 0,
"opened_by": 0,
"owner_user_id": 25263,
"owner_name": "Smith, John",
"pct_complete": 0,
"update_user_id": 25263,
"user_name": "Smith, John"
}
The authenticating user’s rights to access requirements.
Access rights:
- 0 - None
- 1 - Read
- 2 - Update
- 3 - Read and update
- 4 - Delete
- 5 - Read and delete
- 7 - Full access
An array of requirements.
Unique identifier of the requirement.
The ID of the QAComplete project that contains the requirement.
The requirement title (name).
The requirement status based on a choice list.
Specifies whether the requirement is enabled (active).
Keywords of the requirement.
The group that contains the requirement.
The sub group that contains the requirement.
Long description of the requirement. Can include HTML markup.
Business rule associated with the requirement. Can include HTML markup.
Estimated hours to finish the requirement.
Estimated start date for working on the requirement.
The estimate date of the finishing the requirement.
Actual hours spent working on the requirement.
Actual start date for working on the requirement.
The actual date when the requirement was completed.
The date and time when the requirement was last updated.
The date and time when the requirement was created.
The date and time when the requirement was opened.
The ID of the last user who updated the requirement.
For importing: the original key that was imported.
The ID of the import session, in which the requirement was imported. If the requirement was created in QAComplete, the ImportId property is equal to 0.
The ID of the user who owns the requirement.
The ID of the user the requirement is assigned to, or 0 if the requirement is not assigned to anyone.
The ID of the folder containing the requirement, or 0 if the requirement is not in any folder.
Percentage complete of requirement completing.
Estimated remaining hours for finishing the requirement.
The ID of the user who opened the requirement.
The name of the last user who updated the requirement, in the Lastname, Firstname format.
The name of the user who owns the requirement, in the Lastname, Firstname format.
The name of the user to whom the requirement is assigned, in the Lastname, Firstname format.
The latest note attached to the requirement. Can include HTML markup.
The number of files attached to the requirement.
The number of notes attached to the requirement.
The number of scheduled events associated with the requirement.
The number of tasks linked to the requirement.
The name of the folder containing the requirement, in the format ParentFolder/Subfolder/Subfolder.
The name of the user who opened the requirement, in the Lastname, Firstname format.
The e-mail address of the user who registered the requirement.
The company name of the user who registered the requirement.
Reserved.
The number of times the requirement was processed by escalation rules.
The date when the requirement was last processed by an escalation rule.
The ID of the escalation rule that processed the requirement last. 0 if no escalation rule processed the requirement.
The name of the escalation rule that processed the requirement last.
A list of custom fields and their values.
Comments to the requirement. Can include HTML markup.
The unique identifier of a custom field.
The field name.
The field value.
Error responses
If the operation fails, it returns the appropriate status code and (optionally) the error description in the response body.
If the project with the specified ProjectId does not exist or the authenticating user does not have rights to access the project, the operation returns the Access is denied error.
If the requirement with the specified Id does not exist, the operation returns the File or directory not found error.
If the Title or Status you specify for the requirement is empty, the operation returns an internal server error.
If the Title, Status, or Description you specify for the requirement exceeds the maximum value size, the operation returns an internal server error.