DocsAPI ReferenceBlog
Docs

Selectors and filters

Suggest Edits

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.

Selectors: Custom Calculations over nested collections

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.
    • 



.NET Expressions


    

  • Casts are supported via Assignable.As<EntityType>. You can access any simple or reference field of a specific type, like: Assignable.As<UserStory>.Feature.Name or bugs:outboundrelations.select({id:outbound.id,name:outbound.name,priority:outbound.as<Bug>.priority.name})

      

    • Collections on casted entities are not supported.
      • 

    • Supported by native entities only. Extended domain entities (ExD) don't support Casts.
      • 

    

    • 

  • 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.Decimal and it.NullableDouble * it.Decimal will be double and double?. You don't need to use Convert.ToDouble(it.Decimal). This also works for IFNONE/IIF operators: you can simply write IFNONE(it.NullableDouble, it.NullableDecimal) or 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 to it.NullableBool == True.
    • 

  • Constructors are not supported, but you can construct your anonymous objects using syntax described above: {ex1,ex2} 
    • 

  • You can use static methods of some types (DateTime, Convert, Guid). E.g. DateTime.Now, Convert.ToInt
    • 

  • You can use Nullable types and checks for nulls 
    • 

  • You can use instance methods of simple types (e.g., object.ToString(), string.Length)
    • 

  • You can use IIF operator instead of a?b:c
    • 

  • You can use IFNONE operator: IFNONE(a,0) instead of a.HasValue?a.Value:0
    • 

  • You can use operators (-,+,*,/), comparisons (<,>,<=,>=,==), Boolean constants (true,false), string constants ("Some string"), chars ('c') and null identifier.
    • 

  • Do not forget that + sign is treated as space in URLs so do not forget to replace it with %2b.
    • 

  • You can use operator in (id in [1,2,3])
    • 

  • You can use ToPlainText() to strip HTML tags from Description or Rich-Text Custom Fields: (Description.ToPlainText())
    • 



Also some limited subset of IQueryable methods are supported for nested collections (e.g. bugs of user story):


    

  • Select(selector) - projection
    • 

  • Where(filter) - filters
    • 

  • Sum(expression) (as well as Max, Min, Average) - aggregations over specified expression
    • 

  • Count(filter) - count of filtered items
    • 



📘
API v2 uses LINQ expression parser which syntax is very close to standard C# syntax
Updated over 1 year ago