Query for owned tasks
What
I would like to get a list of Owned Tasks similar to the Owned Tasks panel on the My Home > My Work panel.
How
The following tutorial uses the query.v1 endpoint to obtain Task data. While there are other approaches, query.v1 is the preferred approach that returns results efficiently in a single query.
This endpoint was introduced in 13.2, Summer 2013. Please view the About Digital.aiAgility information from the help icon in the menu bar to see if you are on this release or later.
Getting Started
- Have an HTTP Client, or use
<Server Base URI>/http.html. - Obtain an API token, or post directly to the query.v1 endpoint.
Query parameters
from
You can view Owned items for any asset which has an owner. For this example, we want to find owned tasks. However, you can build a similar query for owned stories, owned defects, or owned tests.
For our query, the from is Task. This means the primary query is about Task assets.
from: Task
If our query only has a from parameter, we get a default set of attributes. To return only selected attributes, add a select parameter to your query.
select
To select attributes, you will need to find the system name for the attribute you want to return. Attribute names can be found by querying meta, or meta.v1. To see the attributes available for Task, run the following query by pasting it into your browser address bar and pressing return.
<Server Base URI>/meta.v1/Task?xsl=api.xsl
The result will resemble the following, except with many more attributes.
Task derives from Workitem
* Name : Text
* Parent : Relation to PrimaryWorkitem — reciprocal of Children
Category : Relation to TaskCategory — reciprocal of Tasks
Customer : Relation to Member — reciprocal of CustomeredTasks
Description : LongText
DetailEstimate : Numeric
Estimate : Numeric
Goals : Multi-Relation to Goal — reciprocal of Workitems
Ideas : Multi-LongInt
LastVersion : Text
MentionedInExpressions : Multi-Relation to Expression — reciprocal of Mentions
Order : Rank
Owners : Multi-Relation to Member — reciprocal of OwnedWorkitems
We can use any of the attributes directly in the select. Let's add Name and ID, or Number.
from: Task
select:
- Name
- Number
where or filter
If our query does not have a where or filter parameter, the results will include every Task. Since I want tasks owned by a particular member, I want to filter by Owners Name. I also only want active tasks, so I need to add a filter for AssetState.
from: Task
filter:
- Owners.Name="Andre Agile"
- AssetState="Active"
select:
- Name
- Number
sort
Lastly, I want to define the order of the results. I can order the results, ascending or descending, by a selected attribute value with the sort parameter. For my query, I'd like to see results ordered ascending by rank, or Order. To reverse the order, I can change the + to a -. My final query looks like this:
view sourceprint
from: Task
filter:
- Owners.Name="Andre Agile"
- AssetState="Active"
select:
- Name
- Number
sort:
- +Order