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