VersionOne Data Application Programming Interface (API)
The VersionOne Data API allows programmatic access to the information stored in your VersionOne system. Through the Data API, you can query for simple or complex sets of information, update the information, and execute system-defined operations.
Simple queries can request the value of a single attribute on a single asset, or multiple attributes on a single asset. Complex queries can request multiple assets meeting a certain criteria, have the results sorted in a particular way, and even ask for a portion (a "page") of the overall results.
Using the VersionOne Data API involves sending HTTP requests to specific URLs. GET requests are used to query information, and receive an XML response. POST requests are used to update information, and include an XML payload to describe the update. POST requests are also used to execute operations, which change data in ways that cannot be accomplished with a simple update (such as re-opening a closed Story).
The VersionOne Information Model
Practically all data in VersionOne is stored in the form of assets, which have attributes. Each asset is classified by an asset type, which describes a number of attribute definitions, operations, rules, and possibly an inheritance from another asset type. A list of all the types within VersionOne can be obtained by accessing the meta data url of your VersionOne instance. Additionally, VersionOne comes with an xsl stylesheet, which can be referenced as a parameter to the meta data url and makes it easier to read the response:
http://localhost/VersionOne/meta.v1/?xsl=api.xsl
Individual types can also be viewed through the meta url:
http://localhost/VersionOne/meta.v1/Story?xsl=api.xsl
You must use the system name for the type you would like to retrieve. This is true whether using the API directly or the APIClient. For instance, in the example above the system name is "Story", which certain methodology templates display as "Backlog Item" or "Requirement". Here is a list of some of the most important system names and their corresponding default display names in the available methodology templates:
Table 1.
| System Name |
XP Display Name |
Scrum Display Name |
AgileUP Display Name |
DSDM Display Name |
| Scope |
Project |
Project |
Project |
Project |
| Timebox |
Iteration |
Sprint |
Iteration |
Iteration |
| Theme |
Theme |
Feature Group |
Use Case |
Feature Group |
| Story |
Story |
Backlog Item |
Requirement |
Requirement |
| Defect |
Defect |
Defect |
Defect |
Defect |
| Task |
Task |
Task |
Task |
Task |
| Test |
Test |
Test |
Test |
Test |
Asset Type. Asset types describe the "classes" of business data available. Asset types form an inheritance hierarchy, such that each asset type inherits attribute definitions, operations, and rules from it's "parent" asset type. Those asset types at the leaves of this hierarchy are concrete, whereas asset types with "children" asset types are abstract. Assets are all instances of concrete asset types. Asset types are identified by unique names.
By way of example, Story and Defect are concrete asset types. On the other hand, Workitem is an abstract asset type, from which Story and Defect ultimately derive.
Attribute Definition. Attribute definitions describe the properties that "make up" each asset type. An attribute definition defines the type of its value, whether it is required and/or read-only, and many other qualities. Attribute definitions are identified by a name that is unique within its asset type.
Attribute definitions are defined as either scalars or relations to other assets. Further, relation attribute definitions can be either single-value or multi-value. For example, the Estimate attribute definition on the Workitem asset type is a scalar (specifically, a floating-point number). On the other hand, the Workitem asset type's Scope attribute definition is a single-value relation (to a Scope asset). The reverse relation, Workitems on the Scope asset type, is a multi-value relation (to Workitem assets).
Asset. Actual business objects in VersionOne are assets, which are instances of concrete asset types. Each asset is uniquely identified by it's asset type and ID (an integer). For example, Member:20 identifies the Member asset with ID of 20.
Attribute. On every asset are a number of attributes, which attach specific values to the attribute definitions defined in the asset type. If the attribute's definition is a relation, then the value(s) of the attribute are references to an asset(s).
Moment. As data changes in VersionOne, a history is maintained. Every change to every asset is journaled within the system, and assigned a chronologically-increasing integer called a moment. A past version of an asset is uniquely identified by it's asset type, ID, and Moment. A past version of a relation attribute will refer to the past version of it's target asset. For example, Member:20:563 identifies the Member asset with ID of 20, as it was at the time of moment 563.
Learn By Example: Queries
This section is a series of examples, starting with simpler queries and moving to more advanced queries. Any of these examples are viewable directly in a web browser capable of displaying XML data.
How to query a single asset
This URL will retrieve the Member with ID 20, with a set of common attributes:
http://localhost/VersionOne/rest-1.v1/Data/Member/20
<Asset href="/VersionOne/rest-1.v1/Data/Member/20" id="Member:20">
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="/v1.six/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone" />
<Attribute name="AssetType">Member</Attribute>
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email">admin@demo.com</Attribute>
</Asset>
The XML returned will start with a root node called "Asset" which indicates the results are for a single asset not a list of assets. The "Asset" node also contains an "href" attribute, which corresponds to the full URL used to retrieve this asset, as well as an "id" attribute which contains the internal VersionOne ID of the specific asset.
The child nodes of an "Asset" node are a mixture of "Attribute" and "Relation" nodes. Both types of nodes contain a "name" attribute which tells you what Attribute the value corresponds to. While "Attribute" nodes contain their value, a "Relation" node contains an "Asset" sub node that describes the related asset. Note how the "Asset" sub node contains an "href" attribute like the root "Asset" node but contains an "idref" attribute instead of an "id" attribute.
All assets reside at URLs of the same format; "Member" and "20" can be replaced with any asset's type and ID. If no such asset exists, or if you do not have sufficient rights to view it, then the response will be 404 Not Found.
How to query for different attributes
Retrieve attributes other than the default set by using the sel query parameter.
http://localhost/VersionOne/rest-1.v1/Data/Member/20?sel=Name,Email
<Asset href="/VersionOne/rest-1.v1/Data/Member/20" id="Member:20">
<Attribute name="Email">admin@demo.com</Attribute>
<Attribute name="Name">Administrator</Attribute>
</Asset>
The response contains only those attributes specified.
Best Practice
Whenever possible, use the sel query parameter to choose specific attributes, thereby reducing the load put on the API.
How to query the value of a single attribute
Just as each asset resides at its own URL, so does each attribute. This URL retrieves the Name attribute on Member 20:
http://localhost/VersionOne/rest-1.v1/Data/Member/20/Name
<Attribute name="Name" href="/VersionOne/rest-1.v1/Data/Member/20/Name" of="/VersionOne/rest-1.v1/Data/Member/20">Administrator</Attribute>
The XML returned will start with a root node called "Attribute" or "Relation" which indicates the results are for a single attribute on a single asset. The root node also contains a "name" attribute, which identifies the attribute the value corresponds to, an "href" attribute, which corresponds to the full URL used to retrieve this attribute, as well as an "of" attribute which corresponds to the full URL used to retrieve the asset this attribute belongs to.
If the root node is "Attribute" the scalar value will be in a Text node inside the root node. If the root node is "Relation" there may be one or more "Asset" nodes which are references to the assets the asset relates to.
How to get a list of all Story assets
This URL will retrieve all Story assets (that you have rights to see):
http://localhost/VersionOne/rest-1.v1/Data/Story
<Assets total="10" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1021" id="Story:1021">
<Attribute name="Name">Logon</Attribute>
<Relation name="Status">
<Asset href="/VersionOne/rest-1.v1/Data/StoryStatus/137" idref="StoryStatus:137" />
</Relation>
<Relation name="Timebox">
<Asset href="/VersionOne/rest-1.v1/Data/Timebox/1022" idref="Timebox:1022" />
</Relation>
<Attribute name="DetailEstimate" />
<Attribute name="AssetType">Story</Attribute>
<Attribute name="AssetState">128</Attribute>
<Attribute name="Number">S-01001</Attribute>
<Attribute name="ToDo" />
<Attribute name="Order">32</Attribute>
<Relation name="Parent">
<Asset href="/VersionOne/rest-1.v1/Data/Theme/1015" idref="Theme:1015" />
</Relation>
<Attribute name="Description" />
<Attribute name="Estimate">2</Attribute>
<Relation name="Priority">
<Asset href="/VersionOne/rest-1.v1/Data/WorkitemPriority/140" idref="WorkitemPriority:140" />
</Relation>
<Relation name="Scope">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1010" idref="Scope:1010" />
</Relation>
<Relation name="Owners">
<Asset href="/VersionOne/rest-1.v1/Data/Member/1000" idref="Member:1000" />
</Relation>
</Asset>
<!-- Additional Asset Nodes -->
</Assets>
Depending on your security role, you may not be able to see all the Story assets in the entire system.
The XML returned will start with a root node called "Assets" which indicates the results are list of assets. The "Assets" node also contains a "total" attribute, which tells you how many total items are available if paging is not used, as well as "pageStart" and "pageSize" attributes which indicate where in the given query the items belong. See the Paging Syntax for more information on paging queries.
How to query specific attributes for a list of Story assets
Use the sel query parameter to retrieve attributes other than the default set.
http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Name,DetailEstimate
<Assets total="10" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364" id="Story:1364">
<Attribute name="Name">Company History</Attribute>
<Attribute name="DetailEstimate">0</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1616" id="Story:1616">
<Attribute name="Name">Credit Check 1</Attribute>
<Attribute name="DetailEstimate" />
</Asset>
<!-- Additional Asset Nodes -->
</Assets>
Filter a query by using the where query parameter. This URL will retrieve only Story assets with a To Do of zero:
http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Name,ToDo&where=ToDo='0'
<Assets total="2" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1303" id="Story:1303">
<Attribute name="Name">Home Page</Attribute>
<Attribute name="ToDo">0</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1339" id="Story:1339">
<Attribute name="Name">Contact Us</Attribute>
<Attribute name="ToDo">0</Attribute>
</Asset>
</Assets>
The number 0 in the where query parameter is surrounded by single-quote marks.
Sort a query by using the sort query parameter. This URL will retrieve Story assets sorted by increasing Estimate:
http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Name,Estimate&sort=Estimate
<Assets total="10" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1068" id="Story:1068">
<Attribute name="Name">Ticket 3432</Attribute>
<Attribute name="Estimate">1</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1067" id="Story:1067">
<Attribute name="Name">Ticket 3431</Attribute>
<Attribute name="Estimate">2</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1845" id="Story:1845">
<Attribute name="Name">Shipping Lanes - Freight</Attribute>
<Attribute name="Estimate">3</Attribute>
</Asset>
<!-- Additional Asset Nodes -->
</Assets>
To sort in descending order prepend the attribute name with a minus sign: sort=-Estimate.
How to select a portion of query results
Retrieve a "page" of query results by using the page query parameter. This URL will retrieve the first 5 Story assets:
http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Name&page=5,0
<Assets total="10" pageSize="5" pageStart="0">
<Asset href="/v1.six/rest-1.v1/Data/Story/1021" id="Story:1021">
<Attribute name="Name">Logon</Attribute>
</Asset>
<Asset href="/v1.six/rest-1.v1/Data/Story/1064" id="Story:1064">
<Attribute name="Name">Ticket 3428</Attribute>
</Asset>
<Asset href="/v1.six/rest-1.v1/Data/Story/1065" id="Story:1065">
<Attribute name="Name">Ticket 3429</Attribute>
</Asset>
<Asset href="/v1.six/rest-1.v1/Data/Story/1066" id="Story:1066">
<Attribute name="Name">Ticket 3430</Attribute>
</Asset>
<Asset href="/v1.six/rest-1.v1/Data/Story/1067" id="Story:1067">
<Attribute name="Name">Ticket 3431</Attribute>
</Asset>
</Assets>
The page query parameter shown asks for 5 items, starting at position 0. The next 5 items can be retrieve with page=5,5.
The pageSize and pageStart attributes reflect the requested page, and the total attribute indicates how many assets satisfied the query in total.
How to search text attributes
Search for a string in text attributes by using the find and findin query parameters. This URL will retrieve all Story assets whose Name attribute contains the word Ticket.
http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Name&find=Ticket&findin=Name
<Assets total="3" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1065" id="Story:1065">
<Attribute name="Name">Ticket 3429</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1530" id="Story:1530">
<Attribute name="Name">Ticket 3449</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1518" id="Story:1518">
<Attribute name="Name">Ticket 3439</Attribute>
</Asset>
</Assets>
The findin query parameter is optional; if omitted, a base set of attributes will be searched. On the other hand, the findin query parameter may contain multiple text attributes as a comma-delimited list: findin=Name,Description,Reference.
How to query the history of a single asset
This URL will retrieve the history of the Member asset with ID 20.
http://localhost/VersionOne/rest-1.v1/Hist/Member/20
<History total="2" pageSize="2147483647" pageStart="0">
<Asset href="VersionOne/rest-1.v1/Data/Member/20/0" id="Member:20:0">
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email" />
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone" />
<Attribute name="AssetType">Member</Attribute>
</Asset>
<Asset href="VersionOne/rest-1.v1/Data/Member/20/113" id="Member:20:113">
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email">admin@demo.com</Attribute>
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone">555-555-1212</Attribute>
<Attribute name="AssetType">Member</Attribute>
</Asset>
</History>
This example queries from the Hist namespace, instead of the Data namespace. It responds with 2 historical versions of the same asset. The differences between the two historical assets may be difficult to spot—both the Email attribute and the Phone attribute changed.
The root node is named "History" to indicate you are viewing a historical result. The "href" attribute on each "Asset" node contains a moment after the asset type and ID portions of the path. That URL provides the path to the exact version of that specific asset, as it was at that moment.
Note how the first asset can be retrieved using moment number 0, while the second can be retrieved using moment number 113. This indicates that over 100 changes occured to other assets in the system before someone changed this Member asset.
How to query the history of a single attribute
This URL will retrieve the history of changes to the Email attribute of the Member asset with ID 20:
http://localhost/VersionOne/rest-1.v1/Hist/Member/20/Email
<History total="2" pageSize="2147483647" pageStart="0">
<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/0/Email" of="/VersionOne/rest-1.v1/Data/Member/20/0" />
<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/113/Email" of="/VersionOne/rest-1.v1/Data/Member/20/113">admin@demo.com</Attribute>
</History>
The root "History" node contains child nodes named "Attribute", indicating this is a historical query for a single attribute. As with normal attribute queries, the "Attribute" node contains a "name" attribute which identifies the name of the attribute on the asset, an "href" attribute which points to the specific attribute, and finally an "of" attribute which points to the asset the attribute is on. Note how both the "of" and "href" attributes contain a URL with a moment number.
How to query the history of many assets
This URL will retrieve history for all Story assets you are able to see:
http://localhost/VersionOne/rest-1.v1/Hist/Story?sel=Name,ToDo,ChangeDate
<History total="203" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:818">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">40</Attribute>
<Attribute name="ChangeDate">2005-08-01T12:28:35.577</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:874">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">20</Attribute>
<Attribute name="ChangeDate">2005-08-02T11:05:12.123</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/903" id="Story:1364:903">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">0</Attribute>
<Attribute name="ChangeDate">2005-08-03T13:09:05.983</Attribute>
</Asset>
<!-- Additional Asset Nodes -->
</History>
Again, the response is a list of historical assets. Note how each "Asset" has an "href" attribute with a moment number.
One of the attributes requested in this example is the ChangeDate attribute. This attribute is maintained by history and it indicates the exact time this change occurred.
All of the previously demonstrated query parameters can be used with historical queries also.
How to query an asset "as of" a specific time
Use the asof query parameter to retrieve data as it existed at some point in time. This URL finds the version of a Story asset as it existed at 5:30 PM on October 3rd, 2005:
http://localhost/VersionOne/rest-1.v1/Hist/Story/1364?asof=2005-08-03T17:30:00.00&sel=Name,ToDo,ChangeDate
<History total="1" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/903" id="Story:1364:903">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ChangeDate">2005-08-03T13:09:05.983</Attribute>
<Attribute name="ToDo">0</Attribute>
</Asset>
</History>
This query returns the last historical record on or before the date specified in the asof query string. Notice how the ChangeDate attribute indicates it was last changed at 1:09 PM on October 3rd, 2005. Between 1:09 PM and 5:30 PM no other changes occurred for this Story asset.
The asof query parameter can also be used on single-attribute and multi-asset historical queries.
Learn By Example: Updates
Updating assets through the API involves sending POST requests to the URL of the asset to be updated, with an XML payload. These examples can be tested in your browser by using the page http://localhost/VersionOne/http.html.
How to update a scalar attribute on an asset
Updating a scalar attribute on an asset is accomplished by marking the attribute with act="set", and filling in the new value in the element's text. This post will update the Phone attribute of the Member with ID 20: POST /VersionOne/rest-1.v1/Data/Member/20 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 78
<Asset>
<Attribute name="Phone" act="set">555-555-1212</Attribute>
</Asset>
The response is: <Asset href="/VersionOne/rest-1.v1/Data/Member/20/173" id="Member:20:173">
<Attribute name="Phone">555-555-1212</Attribute>
</Asset>
The response includes the URL of the exact version of the asset that was just updated.
How to update a single-value relation on an asset
Updating a single-value relation is accomplished by marking the attribute with act="set", and filling the idref of the enclosed Asset element. This post will change the Owner of the Scope with ID 0 to be the Member with ID 20: POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 98
<Asset>
<Relation name="Owner" act="set">
<Asset idref="Member:20" />
</Relation>
</Asset>
Whereas this post will change the Owner of the Scope with ID 0 to nobody (that is, NULL): POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 67
<Asset>
<Relation name="Owner" act="set">
</Relation>
</Asset>
How to add and remove values from a multi-value relation
Updating a multi-value relation is accomplished by marking enclosed Asset elements with either act="add" or act="remove". This post will add one Member and remove another Member from the Scope with ID 0: POST /VersionOne/rest-1.v1/Data/Scope/0 HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 197
<Asset>
<Relation name="Members">
<Asset idref="Member:1000" act="add"/>
<Asset idref="Member:1001" act="remove"/>
</Relation>
</Asset>
How to create a new asset
Creating a new asset is accomplished by posting to the asset type URL (without an ID). This post will create a Story with the name "New Story", within the Scope with ID 0. POST /VersionOne/rest-1.v1/Data/Story HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 221
<Asset>
<Attribute name="Name" act="set">New Story</Attribute>
<Relation name="Scope" act="set">
<Asset idref="Scope:0" />
</Relation>
</Asset>
The response is: <Asset href="/VersionOne/rest-1.v1/Data/Story/1072/214" id="Story:1072:214">
<Attribute name="Name">New Story</Attribute>
<Relation name="Scope">
<Asset href="/VersionOne.Web/rest-1.v1/Data/Scope/0" idref="Scope:0" />
</Relation>
</Asset>
When creating a new asset, all required attributes must be provided, or the save will fail. In the above example, the Name and Scope attributes are the minimum required attributes for a Story.
Learn By Example: New Asset Templates
A new asset template is an XML response that contains suggested attribute values for a new asset. These values can be changed, and new attributes added; then the whole template can be posted for saving.
Often a new asset should be created in the "context" of another asset. For example, if you ask for a new Story asset in the context of an Issue asset, the new Story asset will carry over some attributes from the Issue. A few of these attributes are the Name, Description, Scope, and a relationship back to the originating Issue. The same can be done with a Story in the context of a Request with similar attributes being carried across.
One example of a new asset template is asking for a new Timebox asset. When a new Timebox asset is asked for in the context of a Scope asset, it will automatically come with a suggested Name, as well as a StartDate and EndDate. This saves the client from having to calculate the StartDate and EndDate attributes.
These examples demonstrate how to ask for new assets. They should be viewable using a web browser capable of displaying XML data.
How to get a new Story asset template in the context of a Scope asset
Use this URL to get a new Story template.
http://localhost/VersionOne/rest-1.v1/New/Story?ctx=Scope:1000
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/New/Story">
<Relation name="Scope" act="set">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1000" idref="Scope:1000" />
</Relation>
</Asset>
Note how the response contains a pending change for the Scope attribute.
This Story asset is not saved yet. To save it (creating a new Story asset), you must add a Name attribute, and POST it to http://localhost/VersionOne/rest-1.v1/Data/Story as described in How to create a new asset.
How to get a new Story asset in the context of a Request asset
Use this URL to get a new Story template.
http://localhost/VersionOne/rest-1.v1/New/Story?ctx=Request:1684
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/New/Story">
<Relation name="Scope" act="set">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1009" idref="Scope:1009" />
</Relation>
<Attribute name="Description" act="set"><P>When an item's status is updated, alert the owner of the change in status value.</P></Attribute>
<Attribute name="RequestedBy" act="set">Joe Customer</Attribute>
<Attribute name="Name" act="set">Integrate with Palm Handheld</Attribute>
<Relation name="Requests">
<Asset href="/VersionOne/rest-1.v1/Data/Request/1684" idref="Request:1684" act="add" />
</Relation>
</Asset>
Note how the response contains many attributes carried over from the Request asset into the pending Story asset. Also note how the Story will have a relationship set to point back to the Request that it was created from.
Learn By Example: Operations
An operation is an action that is executed against a single asset. For example, to delete an asset you must execute the Delete operation on the asset. To close or inactivate a Workitem, you must use the Inactivate Operation. When executing an operation a request must be made to the URL using the POST HTTP method.
How to delete a Story asset
Post a request to this URL with an empty or 0 byte request.
http://localhost/VersionOne/rest-1.v1/Data/Story/1021?op=Delete
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/Data/Story/1021/2365" id="Story:1021:2365" />
Notice the returned "Asset" node which indicates the asset was properly updated or in this example deleted. The "href" attribute can be used to retrieve the asset in its deleted state. When deleting an asset from the system, the asset is simply marked as deleted. Future current info queries will automatically excluded deleted assets from results.
Currently, there is no support for undeleting a deleted asset.
How to close a Story asset
Post a request to this URL with an empty or 0 byte request.
http://localhost/VersionOne/rest-1.v1/Data/Story/1022?op=Inactivate
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/Data/Story/1022/2367" id="Story:1021:2367" />
The returned "Asset" node indicates the asset was properly updated. You can use the "href" attribute to retrieve the Story asset and see the AssetState attribute changed. The AssetState attribute is the internal state of an asset.
How to reopen a Story asset
Post a request to this URL with an empty or 0 byte request.
http://localhost/VersionOne/rest-1.v1/Data/Story/1022?op=Reactivate
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/Data/Story/1022/2368" id="Story:1021:2368" />
The returned "Asset" node indicates the asset was properly updated. You can use the "href" attribute to retrieve the Story asset and see the AssetState attribute changed.
How to activate a Timebox asset
Post a request to this URL with an empty or 0 byte request.
http://localhost/VersionOne/rest-1.v1/Data/Timebox/2011?op=Activate
The XML Response will look something like this. <Asset href="/VersionOne/rest-1.v1/Data/Timebox/2011/2254" id="Timebox:2011:2254" />
The returned "Asset" node indicates the asset was properly updated.
All API requests must be authenticated, which associates the request with a specific Member in the system. The results of the request will then be secured according to that Member's Roles defined within the system. A request that cannot be authenticated will result in a 401 Unauthorized response.
To authenticate with the API, the initial request should include the Member's Username and Password encoded into a Basic Authentication HTTP header. These credentials will be used by the system to log in, and the request will be processed in the context of that Member. The response will include, as a cookie, an Authentication Ticket, which serves as proof to the system that the Member has previously logged in successfully. If this Authentication Ticket cookie is returned to the server on each subsequent request, then the system can treat the Member as authenticated without performing a full log-in again.
Best Practice
While it is possible to simply use Basic Authorization on every request, it is more efficient to return the Authorization Ticket on each request after the first.
When a request results in an error, the response will have an HTTP status code in the range 400-500, and detailed information about the error will be returned in the response payload.
For example, the request http://localhost/VersionOne/rest-1.v1/Data/Story?sel=Bogus results in a 400 Bad Request response with this payload: <Error href="/VersionOne/rest-1.v1/Data/Story?sel=Bogus">
<Message>Invalid SEL parameter</Message>
<Exception class="VersionOne.MetaException">
<Message>Unknown AttributeDefinition: Story.Bogus</Message>
</Exception>
</Error>
The response is an Error element, with an href attribute indicating the offending requested URL. The Message element contains a textual description of the error. Optional Exception elements may contain technical details about the cause of the error.
Common Error Status Codes
400 Bad Request. A 400 status code is the most common error, resulting from a request that could not be processed by the API. The Error Message will identify the specific problem, and there may be Exception elements that give very detailed information. The usual causes of this error are:
401 Unauthorized. A 401 status code indicates that the request could not be authenticated. This may be caused by any one of these conditions:
-
No credentials supplied to Basic Authentication, and no Authorization Ticket cookie sent with the request.
-
An invalid username or password was supplied to Basic Authentication.
-
An expired or invalid Authorization Ticket cookie sent with the request.
The typical course of action would be to include Basic Authorization credentials and resend the request.
404 Not Found. A 404 status code indicates that there is no resource to retrieve at the requested URL. This could be due to:
-
An invalid URL path requested.
-
A request for a single asset which does not exist, or is deleted, or is secured from the user's view.
405 Method Not Allowed. A 405 status code indicates that the HTTP method used for the request is not valid at the requested URL. This will be returned for any method other than GET and POST, or if POST was sent to a URL that does not support updating.
500 Internal Server Error. A 500 status code indicates that an unexpected error occurred during the processing of the request. The response payload will contain Exception elements with specific information that will help technical diagnose the cause of the error. This could be due to:
-
An environmental problem (e.g., the database is unavailable).
-
An unhandled exception within the VersionOne software.
Responses returned from the API always have the content type "text/xml". The syntax of the responses varies depending on the query, update, or operation executed.
Responses for queries vary depending on what information was asked for. First, queries are seperated into historical and non-historical, and then seperated into the type of query. These types include Asset Type, Asset, and finally Attribute queries.
Data queries are the result of asking for a URL using the "/Data" portion of the path. These queries are for the current state of assets not the historical states.
The Asset Type query is a query to retrieve all assets of a given asset type in a single list. This list can be sorted, filtered, and paged.
The response will begin with an "Asset" node and it will contain attributes named "total", "pageSize", and "pageStart". The "total" attribute correspond to the total number of assets that would appear if the query was not paged. The "pageSize" attribute indicates how many assets were returned in a given page. Finally the "pageStart" attribute indicates where in the un-paged asset list this response begins at.
Inside the "Assets" node are any number of "Asset" nodes which correspond to the individual assets that met the filtered parameter. Each "Asset" node contains an "href" attribute which indicates the URL that the given asset resides at and it also contains an "id" attribute which is the internal ID used by VersionOne to uniquely identify the given asset.
Under each "Asset" node are any number of "Attribute" and "Relation" nodes. These nodes correspond to the attributes that make up the given instance of an asset type. Both nodes will contain a "name" attribute which identifes the name of the attribute the node represents. "Attribute" nodes will contain their value as an inner Text element. "Relation" nodes will contain one or more "Asset" nodes which are references to other assets that this specific asset relates to. Each "Asset" reference node will contain an "href" attribute which points to the instance of the related asset, and an "idref" attribute which identifies the unique VersionOne id of the related asset. <Assets total="10" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1021" id="Story:1021">
<Attribute name="Name">Logon</Attribute>
<Relation name="Status">
<Asset href="/VersionOne/rest-1.v1/Data/StoryStatus/137" idref="StoryStatus:137" />
</Relation>
<Relation name="Timebox">
<Asset href="/VersionOne/rest-1.v1/Data/Timebox/1022" idref="Timebox:1022" />
</Relation>
<Attribute name="DetailEstimate" />
<Attribute name="AssetType">Story</Attribute>
<Attribute name="AssetState">128</Attribute>
<Attribute name="Number">S-01001</Attribute>
<Attribute name="ToDo" />
<Attribute name="Order">32</Attribute>
<Relation name="Parent">
<Asset href="/VersionOne/rest-1.v1/Data/Theme/1015" idref="Theme:1015" />
</Relation>
<Attribute name="Description" />
<Attribute name="Estimate">2</Attribute>
<Relation name="Priority">
<Asset href="/VersionOne/rest-1.v1/Data/WorkitemPriority/140" idref="WorkitemPriority:140" />
</Relation>
<Relation name="Scope">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1010" idref="Scope:1010" />
</Relation>
<Relation name="Owners">
<Asset href="/VersionOne/rest-1.v1/Data/Member/1000" idref="Member:1000" />
</Relation>
</Asset>
<!-- Additional Asset Nodes -->
</Assets>
An asset response is returned when a specific asset is asked for. It corresponds to the "Asset" sub node under the "Assets" root node described in the previous section. And example of an asset query is show below. <Asset href="/VersionOne/rest-1.v1/Data/Member/20" id="Member:20">
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="/v1.six/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone" />
<Attribute name="AssetType">Member</Attribute>
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email">admin@demo.com</Attribute>
</Asset>
And attribute response is returned when a specific attribute on a specific asset is asked for. As described in the Asset Type Query section above, the node name may either be "Attribute" or "Relation". These nodes will also contain an "of" attribute which is a URL that points to the asset that this attribute is on. <Attribute name="Name" href="/VersionOne/rest-1.v1/Data/Member/20/Name" of="/VersionOne/rest-1.v1/Data/Member/20">Administrator</Attribute>
Query Historical Responses
Historical queries are executed in the same fashion as regular queries however their response is formatted differently. This is due to the fact that multiple records or nodes are returned for a particular query. Historical queries use the "/Hist" portion of the URL path.
When asking for historical asset types, the root node will be called "History". Under it will be any number of nodes called "Asset" which correspond to individual assets as they existed at points in time. On the "Asset" nodes the "href" and "id" attributes will now contain a moment number that indicates at what moment the asset changed. The sub nodes "Attribute" and "Relation" are displayed in the same manner as described in the Data Asset Type Query above. <History total="203" pageSize="2147483647" pageStart="0">
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:818">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">40</Attribute>
<Attribute name="ChangeDate">2005-08-01T12:28:35.577</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/818" id="Story:1364:874">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">20</Attribute>
<Attribute name="ChangeDate">2005-08-02T11:05:12.123</Attribute>
</Asset>
<Asset href="/VersionOne/rest-1.v1/Data/Story/1364/903" id="Story:1364:903">
<Attribute name="Name">Company History</Attribute>
<Attribute name="ToDo">0</Attribute>
<Attribute name="ChangeDate">2005-08-03T13:09:05.983</Attribute>
</Asset>
<!-- Additional Asset Nodes -->
</History>
When asking for the history of a particular asset, the results will be essentially the same as the historical asset type query above. The only difference is that the only assets returned are those that have a specific ID. Otherwise the results look identical to those returned above. <History total="2" pageSize="2147483647" pageStart="0">
<Asset href="VersionOne/rest-1.v1/Data/Member/20/0" id="Member:20:0">
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email" />
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone" />
<Attribute name="AssetType">Member</Attribute>
</Asset>
<Asset href="VersionOne/rest-1.v1/Data/Member/20/113" id="Member:20:113">
<Attribute name="Description" />
<Attribute name="Nickname">Admin</Attribute>
<Attribute name="Email">admin@demo.com</Attribute>
<Attribute name="AssetState">64</Attribute>
<Attribute name="DefaultRole.Name">System Admin</Attribute>
<Attribute name="Username">admin</Attribute>
<Attribute name="IsLoginDisabled">false</Attribute>
<Relation name="DefaultRole">
<Asset href="VersionOne/rest-1.v1/Data/Role/1" idref="Role:1" />
</Relation>
<Attribute name="Name">Administrator</Attribute>
<Attribute name="Phone">555-555-1212</Attribute>
<Attribute name="AssetType">Member</Attribute>
</Asset>
</History>
The history of an attribute will return a root node named "History" with a number of "Attribute" or "Relation" sub-nodes. Each sub-node corresponds to a moment in time when the asset the attribute exists on has changed. The "Attribute" or "Relation" node will have a "name" attribute that identifes the attribute and an "of" attribute which identifies the asset the attribute is on. Note that the "of" attribute will contain a URL with a moment. <History total="2" pageSize="2147483647" pageStart="0">
<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/0/Email" of="/VersionOne/rest-1.v1/Data/Member/20/0" />
<Attribute name="Email" href="/VersionOne/rest-1.v1/Data/Member/20/113/Email" of="/VersionOne/rest-1.v1/Data/Member/20/113">admin@demo.com</Attribute>
</History>
The response of an update is an "Asset" node that contains an "href" attribute and "id" attribute that include the ID and Moment of the saved asset. Under the "Asset" node are sub nodes that correspond to the changed attributes and relations. <Asset href="/VersionOne/rest-1.v1/Data/Member/20/173" id="Member:20:173">
<Attribute name="Phone">555-555-1212</Attribute>
</Asset>
The response of a new asset query is a payload that can be posted back to the API to be saved. <Asset href="/VersionOne/rest-1.v1/New/Story">
<Relation name="Scope" act="set">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1000" idref="Scope:1000" />
</Relation>
</Asset>
or <Asset href="/VersionOne/rest-1.v1/New/Story">
<Relation name="Scope" act="set">
<Asset href="/VersionOne/rest-1.v1/Data/Scope/1009" idref="Scope:1009" />
</Relation>
<Attribute name="Description" act="set"><P>When an item's status is updated, alert the owner of the change in status value.</P></Attribute>
<Attribute name="RequestedBy" act="set">Joe Customer</Attribute>
<Attribute name="Name" act="set">Integrate with Palm Handheld</Attribute>
<Relation name="Requests">
<Asset href="/VersionOne/rest-1.v1/Data/Request/1684" idref="Request:1684" act="add" />
</Relation>
</Asset>
The response contains an "Asset" node and multiple "Attribute" or "Relation" sub nodes that identify the values that the new asset will contain. Note that these pending attributes and relations are pre-marked with the "act" attribute which is used to mark the pending changes.
The response of an operation is generally an "Asset" node with an "href" attribute and "id" attribute containing an ID and Moment. <Asset href="/VersionOne/rest-1.v1/Data/Story/1021/2365" id="Story:1021:2365" />
or <Asset href="/VersionOne/rest-1.v1/Data/Timebox/2011/2254" id="Timebox:2011:2254" />
Every attribute, asset, and list of assets in VersionOne can be identified via a unique URL. The syntax for the URL is shown below:
The results of a query will be in the form of an XML response.
Table 1. Query URL Syntax
| Path Portion |
Description |
| QueryType |
| Required |
| Data - retrieves current information |
| Hist - retrieves historical information | |
| AssetType |
| Required |
| The token of the asset type to query. | |
| AssetID |
| Optional |
| An integer that uniquely identifies a specific asset. | |
| Moment |
| Optional |
| An integer that uniquely identifies a point in time for the specified asset. | |
| AttributeName |
|
| QueryString |
|
Table 2. Query String Parameters
| Parameter |
Description |
| sel |
| AttributeSelection |
| An attribute selection token used to determine which attributes are returned in a query. |
| Only valid when asking for a list of assets or an individual asset with or without a moment. | |
| where |
| QueryFilter |
| A filter token used to filter the results of a query. |
| Only valid when asking for a list of assets. | |
| sort |
| OrderBy |
| An order by token used to sort the results of a query. |
| Only valid when asking for a list of assets. | |
| page |
| Paging |
| A paging token used to page the results of a query. |
| Only valid when asking for a list of assets. | |
| find |
| string |
| A string used to limit the results of a query to only those whose attributes contain the given string. |
| Only valid when asking for a list of assets. | |
| findin |
| AttributeSelection |
| An attribute selection token used to determine which attributes are searched when using the find query parameter. |
| Only valid when asking for a list of assets. No effect unless used with find query parameter. | |
| op |
| Operation |
| An operation token used to execute an operation against an asset. |
| Only valid when used in a POST with an AssetType and AssetID. Any moment will be ignored. | |
| asof |
| DateTime |
| A datetime used to retrieve what an attribute, asset or list of assets looked like at a specific date and time. |
| When used in conjuntion with a moment the moment will be ignored. | |
An attribute is a single or multi-value property on an asset. For example a Story has an attribute called Reference which contains text, while the Owners attribute is a multi-value relationship which allows multiple people to own a single Workitem asset. Attributes can be very simple such as the previously mentioned Reference attribute or they may be complex including downcasting, filters and aggregates.
Often it is useful to follow a relationship from one asset through another to get another piece of information. For example if you wanted to know the name of a Category attribute on a Story asset you could ask for the attribute Category.Name on a Story and it would return the Name attribute of the StoryCategory which the Story asset relates to. Ex: http://localhost/VersionOne/rest-1.v1/Data/Story/1000/Category.Name
A Scope asset has a relation called Workitems which points back to all the Workitem assets that belong to the given Scope. This includes Story, Defect, Task, and Test asset types. If you wish to only get Story assets you can use downcasting to filter to Workitem assets to a specific type. For example: http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems:Story would return only those Story assets that are in Scope with ID 0.
In another example you may wish to know all the Workitem assets in a given Scope that are owned by a specific Member. A filtered attribute would help solve this problem. You can use Workitems[Owners='Member:20'] to return only those Workitem assets that are owned by Member with ID 20. An example URL would look like this: http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems[Owners='Member:20']
Lets say you wanted to get the total number of Workitem assets in a particular Scope. You can use the Aggregate portion of an attribute to count the number of Workitem assets. For example: http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems.@Count would return the total number of Workitem assets that belong to Scope with ID 0.
To combine all of this into a more complex example, you may also wish to get the total Estimate for all Story assets that have an owner and are in a given Scope. Rather than getting all Workitem assets and programatically sorting them into buckets, the API can help you. You can follow a relationship, filter the relationship, and then finally use an aggregate to return the final count all using a single attribute on a Scope asset.
The corresponding attribute would be something like this: Workitems:Story[Owners.@Count!='0'].Estimate.@Sum In this example the Scope Workitems attribute will be down cast to only include Story assets, then filtered where the number of Owners is not zero. Once the filtered list is determined, then Estimate for those Story assets will be pulled and finally a single rollup or sum will be returned. This attribute will have a URL like this: http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems:Story[Owners.@Count!='0'].Estimate.@Sum.
| Attribute = <AttributeExpression> [ . @ Aggregate ] |
| <AttributeExpression> ::= <AttributeTerm> [ { . <AttributeTerm> } ... ] |
| <AttributeTerm> ::= Name [ <DownCast> ] [ <Filter> ] |
| <DownCast> ::= : AssetType |
| <Filter> ::= [ Filters ] |
| Name |
| The name of an attribute such as the Reference or Owners attributes. |
|
| AssetType |
| An asset type used to limit or down cast muli-relation attributes such as a Story's Children attribute or a Scope's Workitems attribute. |
|
| Filters |
| A filter token used to filter the results of a multi-relation attribute such as a Member's Scopes attribute. |
|
| Aggregate |
| Use "Sum" to aggregate numeric attributes. |
| Use "Count" to count multi-relation attributes. |
| Use "MinDate" to return minimum date value. |
| Use "MaxDate" to return maximum date value. |
|
Downcast. A relation may refer to a higher level asset type, for example Scope.Workitems refers to Workitem assets. Downcasting allows the relation to be filtered to a more specific asset type and also the relation to be filtered by attributes of the more specific asset type. For example downcasting Scope.Workitems to Story assets allows you to use Story specific attributes in the filter such as the Category attribute. The URL, http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems[Category='StoryCategory:108'] will return a 404 Error while http://localhost/VersionOne/rest-1.v1/Data/Scope/0/Workitems:Story[Category='StoryCategory:108'] will work correctly.
ToDo. The ToDo attribute on a Workitem asset. This is a numeric value that indicates the amount of effort still remaining to complete the Workitem.
Scopes. The Scopes relation on a Member asset. This is a multi-value relation that lists all the Scopes to which the Member has access.
ChildrenMeAndDown. The ChildrenMeAndDown relation on a Workitem asset. This is a multi-value relation that lists the Workitem, the Children of the Workitem, and their Children, recursively. This list will include any Theme, Story, Defect, Task, and Test assets that are reachable through the Children relation.
ChildrenMeAndDown:Theme. The ChildrenMeAndDown relation on a Workitem asset, downcast to Theme asset type. The downcast causes only Theme assets to be included in the list (not Story, Defect, Task, or Test assets).
ChildrenMeAndDown[Owners='Member:20']. A Workitem hierarchy attribute that only includes assets that are owned by the Member with ID 20.
ChildrenMeAndDown:Theme[Scope='Scope:1000']. A Workitem hierarchy attribute that only includes Theme assets that are defined in the Scope with ID 1000.
ChildrenMeAndDown:Theme[Scope.ParentMeAndUp='Scope:1000']. A Workitem hierarchy attribute that only includes Theme assets that are defined at or below the Scope with ID 1000.
Members.@Count. A numeric attribute which indicates the total number of Members in the Scope.
Attribute Selection Syntax
An Attribute Selection token is used to list names of attributes. For example a list of attributes to return for a given asset, or a list of attributes to search in when using the find query parameter. Must be seperated by commas.
{ AttributeDefinition } [ , ... ]
| AttributeDefinition |
| The name of an attribute you wish to use in the selection. |
Name. Uses only the Name attribute in the given selection.
Name,Description. Uses Name and Description attributes in the given selection.
Name,ToDo,Scope. Uses Name, ToDo, and Scope attributes in the given selection.
A filter token is used to limit the results of an asset query. For example you may wish to filter a list of Story assets to only those that have 0 To Do. Note that Value arguments are or'd together while major terms of the filter are either AND'd or OR'd together depending on the Logical seperator. Value arguments are surrounded by single quotation marks and separated by commas.
{ AttributeDefinition Operator ' Value ' [ , ... ] } [ Logical ... ]
| AttributeDefinition |
| Is the attribute token you wish to filter on |
|
| Operator |
| Supported operators include =, !=, <, >, <=, and >= |
|
| Value |
| Any number or string that you wish to match against, must be surrounded with single-quote marks. To use either single- or double-quote marks within the value, enter the character twice in succession. |
|
| Logical |
| Use ; to denote the logical operation AND between two terms Use | to denote the logical operation OR between two terms |
|
| Note when using a mixture of logical AND and OR operators it may become necessary to group terms together. To do so surround the specific terms with parenthesises. |
ToDo='0'. Filter assets to only those that have 0 To Do
ToDo!='0';Owners='Member:20'. Filter assets to only those that have a non-zero To Do and are owned by Member with ID 20.
ToDo!='0';Owners='Member:20','Member:21','Member:22'. Filter assets to only those that have a non-zero To Do and are owned by a Member with ID 20, 21, or 22.
Name='Can''t Boot'. Filter assets to only those whose name is equal to the string "Can't Boot". Notice the quote character has been escaped by doubling.
Owners.@Count>'5'. Filter assets to only those that are owned by more than 5 Members.
Estimate<'1'. Filter assets to only those that have an Estimate less than 1.
Owners='Member:20','Member:21'|Scope='Scope:5'. Filter assets to only those that are owned by a Member with ID 20 or 21 OR belong to a Scope (Project) with ID 5.
(ToDo!='0';Owners='Member:20')|(ToDo='0';Owners='Member:20','Member:21'). Filter assets to only those that have a non-zero To Do AND are owned by a Member with ID 20 OR those that have a 0 To Do AND are owned by a Member with ID 20 or 21.
An Order By token is used to sort the results of an asset query. For example you may wish to sort a list of Story assets by their Estimate and then Name.
{ [ - | + ] AttributeDefinition } [ , ... ]
| Order Operator |
| Use + for ascending or - for descending. If omitted ascending is assumed. |
|
| AttributeDefinition |
| Is the attribute token you wish to sort by |
Estimate. Sort assets by Estimate ascending.
-Estimate,Name. Sort assets by Estimate descending, then by Name ascending.
A Paging token is used to indicate how many assets you want to retrieve and where to start in the list of assets. For example if you have 100 assets and want to see 10 at a time, you would use a page start of 0, and a page size of 10. To retrieve the second page simply ask for a page start of 10 with a page size of 10, and so on.
| PageSize |
| Is the maximum number of items to return in a single list. |
|
| PageStart |
| Is the position (zero-based) in a list of assets to begin returning from. |
5,0. Return the first 5 assets.
5,5. Return the second 5 assets.
5,10. Return the third 5 assets.
10,6. Return up to 10 assets, starting after the 6th asset.
Copyright © 2007, VersionOne, LLC. All rights reserved. This document was generated 2007-03-29 14:05:05. |
|
|
|