PUT/projects/{ProjectId}/agiletasks/{Id}

Applies to QAComplete 14.5, last modified on August 06, 2024

Updates the specified agile task.

Use the operation to replace the contents of an existing agile task with new contents in QAComplete.

To update individual fields of an existing agile task, use the …/agiletasks/{Id} (PATCH) operation.

To add a new agile task to your project, use the …/agiletasks (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 Agile Tasks.

Request Format

To update the agile task, send a PUT request to the following URL:

http://{server}/rest-api/service/api/v2/projects/{ProjectId}/agiletasks/{Id}
URL parameters

ProjectId  :  integer, required

The ID of the project, to which the agile task belongs.

Id  :  integer, required

The ID of the agile task that you want to update.

Body parameters

In the request body, pass the RequestProjectTaskPut JSON object that describes the agile task’s new contents:

{
  "Title": "string",
  "PctComplete": "int",
  "EstHrs": "double",
  "ActualHrs": "double",
  "EstCost": "double",
  "ActualCost": "double",
  "RequestedBy": "string",
  "OwnerUserId": "int",
  "AssigneeUserId": "int",
  "PriorityCode": "string",
  "StatusCode": "string",
  "Grouping": "string",
  "SubGrouping": "string",
  "Keywords": "string",
  "SortOrder": "int",
  "Description": "string",
  "OriginalId": "int",
  "ImportId": "int",
  "FolderId": "int",
  "EstStart": "Date",
  "EstFinish": "Date",
  "ActStart": "Date",
  "ActFinish": "Date",
  "EstHrsRemaining": "double",
  "ActHrs": "double",
  "CustomFields": [
    {
      "Id": "string",
      "Name": "string",
      "Value": "string"
    }
  ]
}

Some string property values (for example, StatusCode) are based on the choice lists defined in your QAComplete project. To view these values, go to the Agile Tasks > Actions > Manage Choice Lists screen in QAComplete.

The property values you do not specify are set to their default values.

Title  :  string (max 255 chars), required

The title of the agile task. Cannot be empty.

PctComplete  :  integer

Percentage of the agile task’s completion.

EstHrs  :  double

Estimated hours required to complete the agile task.

ActualHrs  :  double

Actual hours spent working on the agile task.

EstCost  :  double

The estimated cost of working on the agile task.

ActualCost  :  double

The actual cost of working on the agile task.

RequestedBy  :  string

The name of the user who requested the agile task, in the Last name, First name format.

OwnerUserId  :  integer

The ID of the user who owns the agile task.

AssigneeUserId  :  integer

The ID of the user to whom the agile task is assigned.

PriorityCode  :  string

The priority of the agile task.

StatusCode  :  string

The status code of the agile task.

Grouping  :  string

The mechanism of task grouping.

SubGrouping  :  string

The mechanism of task grouping.

Keywords  :  string

The list of keywords for searching purposes.

SortOrder  :  integer

The ordinal number of the agile task specified in the project.

Description  :  string

The description of the agile task.

OriginalId  :  integer

The original ID of the agile task, as it was specified in the external file from which it was import.

ImportId  :  integer

The ID of the operation that imported the agile task from an external file.

FolderId  :  integer

The ID of the folder to which the agile task belongs.

EstStart  :  dateTime

Estimated date and time when work on the agile task should begin.

EstFinish  :  dateTime

Estimated date and time when work on the agile task should finish.

ActStart  :  dateTime

Actual date when work on the agile task was started.

ActFinish  :  dateTime

Actual date when work on the agile task was finished.

EstHrsRemaining  :  double, required

Estimated number of hours required to finish the agile task.

ActHrs  :  double

Actual hours spent working on the agile task..

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.

A sample request:

PUT http://yourserver.com/rest-api/service/api/v2/projects/11873/agiletasks/1 HTTP/1.1
Host: yourserver.com
Connection: keep-alive
Content-Type: application/json
Accept: application/json
Authorization: Basic am9obkBleGFtcGxlLmNvbTpwQHNzd29yZA==
Content-Length: 111

{
  "Title": "New task title",
  "Description": "This is a description of a new agile task."  
}

A sample request made by using cURL:

curl -u [email protected]:p@ssword -d @agiletask.txt -H "Content-Type: application/json" -H "Accept: application/json" http://yourserver.com/service/api/v2/projects/11873/agiletasks/1

Response Format

On success, the operation responds with HTTP status code 200 and returns a JSON object with the updated agile task information.

A sample response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 804


{
  "project_id": 11873,
  "id": 1,
  "task_type_code": "ProjectTasks",
  "description": "This is a description of a new agile task.",  
  "title": "New task title",
  "pct_complete": 0,
  "est_hrs": 0,
  "owner_user_id": 146537,
  "assignee_user_id": 0,
  "status_code": "Active",
  "folder_id": 0,
  "est_start": "0001-01-01T00:00:00.0000000",
  "est_finish": "0001-01-01T00:00:00.0000000",
  "act_start": "0001-01-01T00:00:00.0000000",
  "act_finish": "0001-01-01T00:00:00.0000000",
  "est_hrs_remaining": 0,
  "act_hrs": 0,
  "update_user_id": 146537,
  "date_created": "2019-07-08T08:27:26.7500000",
  "date_updated": "2019-07-08T08:27:26.7500000",
  "user_name": "Smith, John ",
  "owner_name": "Smith, John ",
  "event_type": "Project Task",
  "nbr_files": 0,
  "nbr_notes": 0,
  "nbr_events": 0,
  "nbr_escalations": 0,
  "last_escalation_rule": "",
  "custom_fields": [],
  "__permissions": {
    "acl": 7
  }

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 agile task with the specified Id does not exist, the operation returns the File or directory not found error.

See Also

Agile Tasks Resources

Highlight search results