PATCH/projects/{ProjectId}/requirements/{Id}

Applies to QAComplete 12.70 SaaS, last modified on January 11, 2021

Updates a requirement in QAComplete.

Use this operation to update individual fields of an existing requirement in QAComplete.

To update all the fields of a requirement, use the …/requirements/{Id} (PUT) operation.

To add a new requirement, 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 Requirements.

Request Format

To update the requirement, send a PATCH request to the following URL:

http://{server}/rest-api/service/api/v1/projects/{ProjectId}/requirement/{Id}
URL parameters

ProjectId  :  integer, required

The ID of the project, to which the requirement belongs.

Id  :  integer, required

The ID of the requirement you want to update.

Body parameters

In the request body, pass the RequestRequirementsPatch JSON object that specifies the requirement’s fields to update:

{
  "Title": "string",
  "Status": "string",
  "Active": "boolean",
  "ActFinish": "Date",
  "ActHrs": "double",
  "ActStart": "Date",
  "AssigneeUserId": "int",
  "BusinessRule": "string",
  "Comments": "string",
  "CustomFields": [
    {
      "Id": "string",
      "Name": "string",
      "Value": "string"
    }
  ],
  "Description": "string",
  "EstFinish": "Date",
  "EstHrs": "double",
  "EstHrsRemaining": "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 remain unchanged.

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.

ActStart  :  dateTime

Actual start date for working on the requirement.

AssigneeUserId  :  integer

The ID of the user the requirement is assigned to, or 0 if the requirement is not assigned to anyone.

BusinessRule  :  string

Business rule associated with the requirement. Can include HTML markup.

Comments  :  string

Comments to the requirement. Can include HTML markup.

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.

EstFinish  :  dateTime

The estimate date of the finishing the requirement.

EstHrs  :  double

Estimated hours to finish the requirement.

EstHrsRemaining  :  double

Estimated remaining hours for finishing the requirement.

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 is 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.

OwnerUserId  :  integer

The ID of the user who owns the requirement.

PctComplete  :  integer

Percentage complete of requirement completing.

SubGrouping  :  string

The sub group that contains the requirement.

A sample request:

PATCH 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: 110

{
  "Title": "Implement search feature",
  "Status": "Active",
  "AssigneeUserId": 25263
}

A sample request made by using cURL:

curl -u john@example.com:p@ssword -d {"Title": "Implement search feature", "Status": "Active", "AssigneeUserId": 25263} -H "Content-Type: application/json" -H "Accept: application/json" http://yourserver.com/service/api/v1/projects/11873/requirements/17

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: 1063


{
  "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",
  "assigned_to_name": "Smith, John",
  "assignee_user_id": 25263,
  "custom_fields": [
    {
      "id": "Custom1",
      "name": "Area",
      "value": "Integration"
    }
  ],
  "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,
  "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_name": "Smith, John",
  "owner_user_id": 25263,
  "pct_complete": 0,
  "user_name": "Smith, John",
  "update_user_id": 25263
}

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