Work Items

Work items are major part of TeamPulse and here is how they can be managed via the API.

GET /workitems/{id} - Get a work item by ID

GET /workitems - Get all work items to which the user has access to.

GET /workitems/{workItemId}/tasks - Get all tasks added to a work item

POST /workitems - Create a work item

DELETE /workitems/{id} - Delete a work item

Work Item Model

The types of the work items are 'Feature', 'Story', 'Bug', 'Issue', 'Risk', 'Feedback' and 'Task'. Features are available with TeamPulse version R1 2014 (2014.1.0414). The object representing a work item has the following properties:

id: integer (Read-only) - ID of the work item.

type: string (Required, Read-only) - The type of the work item. Valid values are 'Feature', 'Story', 'Bug', 'Issue', 'Risk', 'Feedback' and 'Task'.

projectId: integer (Required, Read-only) - ID of the project to which the work item belongs to.

fields: object (Required) - An object representing the work item properties. Based on the type, the fields may be different and here is the list of all valid ones.

createdBy: string - The name of the user who created the work item

createdAt: DateTime - The date when the work item is created

lastModifiedBy: string - The name of the user who last modified the work item

lastModifiedAt: DateTime - The date when the work item is last modified

Common fields

Name: string (Required)

Status: string - Status of the work item. Default value is 'Not Done'. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values for Story and Bug are 'Not Done', 'In Progress', 'Ready For Test', 'Done', 'Deferred', 'Deleted'.

Valid values for Task are: 'Not Done', 'In Progress', 'Done', 'Deleted'.

Valid values for Issue and Risk are: 'Active', 'Closed'.

NOTE: Not applicable to Feedback.

AreaID: integer - The area to which the work item is related to. Default value is root area ID.

IterationID: integer - The iteration in which the work item has to be completed. Default value is root iteration ID.

BacklogPriority: double (Read-only) - The priority of the work item in the backlog. By default a list of work items is sorted by this field.

Description: string

TeamID: integer - ID of the team assigned to the work item.

NOTE: Not applicable to Feedback.

AssignedToID: integer - ID of the user assigned to the work item.

NOTE: Not applicable to Feedback.

Estimate: string - The estimate of the work item.

NOTE: Not applicable to Task and Feedback

Tags: array of strings - A list of tags applied to the story.

NOTE: Not applicable to Task

IsSyncable: boolean (Read-only) - Returned only if the project is configured to be synced with TFS. True, in case the item is marked to be synced with TFS.

TfsID: integer (Read-only) - If the story is synced to TFS, the field represents the ID in TFS.

NOTE: Not applicable to Feedback

CalculatedEstimate: double - Roll-up of estimate of work item's children.

Feature fields

PriorityClass: string - Priority class of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Must Have', '2 - Should Have', '3 - Could Have', '4 - Won't Have'.

Story fields

Certainty: string - The certainty of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Uncertain', '2 - Somewhat Uncertain', '3 - Average', '4 - Somewhat Certain', '5 - Certain'.

Complexity: string - The complexity of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Simple', '2 - Somewhat Simple', '3 - Standard', '4 - Somewhat Complex', '5 - Complex'.

Maturity: string - Maturity of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Undefined', '2 - Not Mature', '3 - Somewhat Not Mature', '4 - Somewhat Mature', '5 - Mature'.

Priority: integer

PriorityClass: string - Priority class of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Must Have', '2 - Should Have', '3 - Could Have', '4 - Won't Have'.

ValueClass: string - Value class of the story. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Cost Saver', '2 - Differentiator', '3 - Spoiler', '4 - Table Stakes'.

Bug fields

IsBlocking: bool

IsTriaged: bool

Priority: integer

Severity: string - The severity of the bug. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Critical', '2 - High', '3 - Medium', '4 - Low'.

StepsToReproduce: string

Task fields

ParentID: integer (Required, Read-only) - The ID of the work item to which the task is added.

EstimateOptimistic: float

EstimatePessimistic: float

EstimateProbable: float

PertEstimate: float (Read-only) - PERT estimate is calculated based in the provided values for optimistic, pessimistic and probable estimates. Read more about PERT estimate.

WorkRemaining: double

WorkCompleted: double

Issue fields

Assessed: boolean

Benefit: string

IsBlocking: boolean

Priority: integer

Resolution: string

Severity: string - Severity of the issue. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Critical', '2 - High', '3 - Medium', '4 - Low'

Risk fields

Assessed: boolean

IsBlocking: boolean

Priority: integer

Probability: string - Probability of the Risk. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are: '1 - Unlikely', '2 - Somewhat Unlikely', '3 - Somewhat Likely', '4 - Likely',

Resolution: string

Severity: string - Severity of the issue. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are '1 - Critical', '2 - High', '3 - Medium', '4 - Low'

Feedback fields

FeedbackType: string - The type of the Feedback. Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are: 'Idea', 'Feedback', 'Feature Request', 'Problem'. IsVisibleInPortal: boolean - If true and the Feedback portal module is activated, the item is visible in the feedback portal.

IsPrivate: boolean

PortalDescription: string - The description show in the feedback portal in case the Feedback portal module is activated and IsVisibleInPortal is true.

Size: string - Valid values may vary based on the concrete project settings. Below are listed the default ones:

Valid values are 'Extra Small (XS)', 'Small (S)', 'Medium Small (MS)', 'Medium (M)', 'Medium Large (ML)', 'Large (L)', 'Extra Large (XL)', 'Extra, Extra Large (XXL)'.

Source: string

Likes: integer (Read-only) - The number of people who liked the work item. Disliked: integer (Read-only) - The number of people who disliked the work item.

Resource Url

To make API requests use the URL [teampulse]/api/v1 where [teampulse] is the URL to the TeamPulse instance which you want to manage via the API.

Example:
[teampulse]/api/v1/workitems

Get a work item

GET /workitems/{id}

Response

HTTP/1.1 200

{
    "id": 44904,
    "type": "Story",
    "projectId": 10,
    "createdAt": "2013-10-03T06:54:33.283",
    "createdBy": "Paul Smith",
    "lastModifiedAt": "2013-10-03T06:54:33.283",
    "lastModifiedBy": "Paul Smith",
    "fields": {
        "AreaID": 55,
        "TeamID": null,
        "AssignedToID": null,
        "BacklogPriority": 15570654336794,
        "Certainty": null,
        "Complexity": null,
        "Description": "",
        "Estimate": null,
        "IterationID": 118,
        "Maturity": null,
        "Name": "Some name",
        "Priority": null,
        "PriorityClass": null,
        "Status": "Not Done",
        "ValueClass": null,
        "Tags": [],
        "TfsID": null,
        "tp_MyCustomField_cf": "custom value"
    }
}

Get work items

GET /workitems : Get all work items. Top 100 are returned by default.

GET /workitems/{workItemId}/tasks : Get tasks for a specific work item.

OData $top and $skip options can be used to skip a number of items and get the next 100. $filter and $orderby can be supplied to filter and order the results. Read more how to use the OData options

Response

HTTP/1.1 200

{
    "totalResults": 44873,
    "top": 100,
    "skip": 0,
    "results": [
        {
            "id": 44904,
            "type": "Story",
            "projectId": 10,
            "createdAt": "2013-10-03T06:54:33.283",
            "createdBy": "Paul Smith",
            "lastModifiedAt": "2013-10-03T06:54:33.283",
            "lastModifiedBy": "Paul Smith",
            "fields": {
                "AreaID": 55,
                "TeamID": null,
                "AssignedToID": null,
                "BacklogPriority": 15570654336794,
                "Certainty": null,
                "Complexity": null,
                "Description": "",
                "Estimate": null,
                "IterationID": 118,
                "Maturity": null,
                "Name": "Some name",
                "Priority": null,
                "PriorityClass": null,
                "Status": "Not Done",
                "ValueClass": null,
                "Tags": [],
                "TfsID": null,
                "tp_MyCustomField_cf": "custom value"
            }
        },
        ....
        {
            "id": 44804,
            "type": "Story",
            "projectId": 10,
            "createdAt": "2013-10-02T14:29:14.823",
            "createdBy": "Paul Smith",
            "lastModifiedAt": "2013-10-02T14:29:14.823",
            "lastModifiedBy": "Paul Smith",
            "fields": {
                "AreaID": 55,
                "TeamID": null,
                "AssignedToID": null,
                "BacklogPriority": 15561429146276,
                "Certainty": null,
                "Complexity": null,
                "Description": "",
                "Estimate": null,
                "IterationID": 118,
                "Maturity": null,
                "Name": "sfsafs",
                "Priority": null,
                "PriorityClass": null,
                "Status": "Not Done",
                "ValueClass": null,
                "Tags": [],
                "TfsID": null,
                "tp_MyCustomField_cf": "another custom value"
            }
        }
    ]
}

Create a work item

POST /workitems

When a work item is created all the default values are preset if a value for the corresponding field is not supplied. This includes fields like Status, AreaID, IterationID, custom fields with default values.

Request - the minimum needed to create a work item

{
  "type": "Story",
  "projectId": 10,
  "fields": {
    "Name": "REST API for work items"
  }
}

Response

HTTP/1.1 201

{
    "id": 44905,
    "type": "Story",
    "projectId": 10,
    "createdAt": "2013-10-03T10:51:38.823",
    "createdBy": "Paul Smith",
    "lastModifiedAt": "2013-10-03T10:51:38.823",
    "lastModifiedBy": "Paul Smith",
    "fields": {
        "AreaID": 55,
        "TeamID": null,
        "AssignedToID": null,
        "BacklogPriority": 15571051389037,
        "Certainty": null,
        "Complexity": null,
        "Description": "",
        "Estimate": null,
        "IterationID": 118,
        "Maturity": null,
        "Name": "REST API for work items",
        "Priority": null,
        "PriorityClass": null,
        "Status": "Not Done",
        "ValueClass": null,
        "Tags": [],
        "TfsID": null,
        "tp_MyCustomField_cf": "my default value"
    }
}

Update a work item

PUT /workitems/{id}

The update can be done partially so only the properties that need to be updated can be provided in the request.

Request

{
  "Name": "API for work items",
  "Status": "In Progress"
}

Response

HTTP/1.1 201

{
    "id": 44905,
    "type": "Story",
    "projectId": 10,
    "createdAt": "2013-10-03T10:51:38.823",
    "createdBy": "Paul Smith",
    "lastModifiedAt": "2013-10-03T10:51:38.823",
    "lastModifiedBy": "Paul Smith",
    "fields": {
        "AreaID": 55,
        "TeamID": null,
        "AssignedToID": null,
        "BacklogPriority": 15571051389037,
        "Certainty": null,
        "Complexity": null,
        "Description": "",
        "Estimate": null,
        "IterationID": 118,
        "Maturity": null,
        "Name": "API for work items",
        "Priority": null,
        "PriorityClass": null,
        "Status": "In Progress",
        "ValueClass": null,
        "Tags": [],
        "TfsID": null,
        "tp_MyCustomField_cf": "my default value"
    }
}   

Delete a work item

DELETE /workitems/{id}

Response

HTTP/1.1 200