Skip to main content
System StatusContact Support
VersionOne Community

Get a specific story

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

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
  • Was this article helpful?