PUT/projects/{ProjectId}/requirements/{Id}

Applies to QAComplete 12.71 SaaS, last modified on January 19, 2021

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:

http://{server}/rest-api/service/api/v1/projects/{ProjectId}/requirements/{Id}
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 john@example.com: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"
}

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.

See Also

Requirements Resources

Highlight search results