Targetprocess REST API v.2 is quite powerful with its ability to do advanced calculations. In a single API v.2 request you can perform common math operations over entities in root result collection and in nested ones. As a result you get calculated numeric, date, boolean, text values.
You can request inner collections with filters, projections, and aggregations. E.g. I want to get projects with:
- all non-closed bugs
- sum of feature efforts
- count of opened requests
openBugs:Bugs.Where(EntityState.IsFinal!=true)- all non-closed bugs. We need to specify name of the result collection. As far as Bugs is a collection of bug we can use some standard Enumerable methods (see below)
featureEffort:features.sum(effort)- we can aggregate collections by some field of collection item.
openRequestCount:requests.Count(EntityState.IsInitial==true)- we can calculate counts with some filters.
- Casts are supported via
Assignable.As<UserStory>. You can access any simple or reference field of a specific type, like:
Assignable.As<UserStory>.Epic.Name. Collections on casted entities are not supported!
- You can use Convert class to convert strings to numbers or dates or vice versa.
- Decimal values are converted to double(nullable double) automatically in case double and decimal values are used in one expression: result of
it.Double + it.Decimaland
it.NullableDouble * it.Decimalwill be
double?. You don't need to use
Convert.ToDouble(it.Decimal). This also works for IFNONE/IIF operators: you can simply write
IIF(it.NullableDecimal.HasValue, it.NullableDecimal.Value, it.Double).
- Nullable bool is automatically converted to bool (false for null value). So if nullable bool is used in place where bool should be used it's usage will be converted from
it.NullableBool == True.
- Constructors are not supported, but you can construct your anonymous objects using syntax described above:
- You can use static methods of some types (DateTime, Convert, Guid). E.g.
- You can use Nullable types and checks for nulls
- You can use instance methods of simple types (e.g.,
- You can use IIF operator instead of
- You can use IFNONE operator:
- You can use operators (
/), comparisons (
==), Boolean constants (
false), string constants (
"Some string"), chars (
- Do not forget that
+sign is treated as space in URLs so do not forget to replace it with
- You can use operator
id in [1,2,3])
- You can use
ToPlainText()to strip HTML tags from Description or Rich-Text Custom Fields: (
Also some limited subset of IQueryable methods are supported for nested collections (e.g. bugs of user story):
)(as well as Max, Min, Average) - aggregations over specified expression
)- count of filtered items
API v2 uses LINQ expression parser which syntax is very close to standard C# syntax
Updated over 1 year ago