Appends and Calculations

Targetprocess REST API v.1 is quite powerful with its ability to do advanced calculations. In a single API v.1 request you can perform common math operations over fields of entities in nested collections. As a result you get calculated numeric values.

📘

Besides Calculations performed within REST API there are a few other features in Targetprocess that support custom calculations. More information: Custom Calculations and Formula Expressions

The following aggregation functions are supported:

• Count
• Sum
• Avg
• Min
• Max

For example, you can retrieve Tasks and Bugs count for User Story:

/api/v1/UserStories?append=[Bugs-Count,Tasks-Count]

<UserStories>
 <UserStory Id="196" Name="Set Due Date">
 <Bugs-Count>0</Bugs-Count>
 <Tasks-Count>3</Tasks-Count>
 </UserStory>
 <UserStory Id="192" Name="Make Task Important">
 <Bugs-Count>10</Bugs-Count>
 <Tasks-Count>0</Tasks-Count>
 </UserStory>
</UserStories>

🚧

It is not possible to filter entities by appended field within REST API v.1 (e.g. it's not possible to get a lists of User Stories which have more than 2 Tasks)

And here is an example of calculating average effort of all the Bugs for User Story:

/api/v1/UserStories?include=[Bugs-Effort-Avg]

<UserStories>
 <UserStory Id="196">
 <Bugs-Effort-Avg nil="true"/>
 </UserStory>
 <UserStory Id="192">
 <Bugs-Effort-Avg>12.5<Bugs-Effort-Avg/>
 </UserStory>
</UserStories>

🚧

It is not possible to add a condition into appended field within REST API v.1 (e.g. it's not possible to calculate average effort of all open Bugs for User Story)

More examples with different calculations:

/api/v1/Features?include=[Bugs-Effort-Sum]&take=1000
/api/v1/Assignables?include=[Times-Spent-Max]&take=1000
/api/v1/Tags?include=[Generals-Count]&take=1000
/api/v1/Epics?include=[Comments-CreateDate-Min]&take=1000
/api/v1/Projects?include=[UserStories-TimeSpent-Avg]&take=1000