Get a specific story
This article explains how to get details of a specific story using the Agility sync query.
What
I want to build a tool that accepts a Story Number as input and provides a useful representation of the data, including a link to get more information. How do I query for a specific story when I know a uniquely identifying piece of information?
How
This endpoint was introduced in 13.2, Summer 2013. Please check Support Center -> About to see if you are on this release or later.
The following uses the query.v1 endpoint. While there are other approaches, query.v1 is easy to write and returns JSON which is easy to parse.
Getting Started
- Have an HTTP Client.
- Obtain an API token.
from
Our query begins with the type of asset we are requesting. In this case, we know we want a Story asset so we use that for the from parameter.
from: Story
where
The important part of looking up a specific asset is the where parameter.
from: Story
where:
Number: B-01001
In order to execute the query, submit an HTTP POST with the query as the body to query.v1. The results look something like the following.
[
[
{
"_oid":"Story:1055"
}
]
]
select
Let's use a select parameter to specify additional fields we want. Most attribute definitions can be found by a query to meta.v1. To see the attributes available for Story, perform the following query.
<Server Base URI>/meta.v1/Story?xsl=api.xsl
The result will resemble the following, except with many more attributes.
Story derives from PrimaryWorkitem
* Name : Text
* Scope : Relation to Scope — reciprocal of Workitems
ID : Relation to Story
Number : Text
Description : LongText
We can use that information to decide what fields to bring back in the response.
from: Story
where:
Number: B-01001
select:
- Name
- Number
- ID
- Description
Again, we can execute the query by submitting an HTTP POST with the query as the body to query.v1. The results look something like the following.
[
[
{
"_oid":"Story:1055",
"Name":"Sample: Logon",
"Number":"B-01001",
"ID":
{
"_oid":"Story:1055"
},
"Description":null
}
]
]
Note that ID just contains a reference to the story itself. Since the OID Token is automatically returned with every query (even when no select is given), selecting the ID is rarely useful.
Deriving a Hyperlink to Story Details
Now that we have data for this asset, we can also derive a hyperlink to the details page from the OID Token.
<Server Base URI>/story.mvc/Summary?oidToken=Story:1055