Skip to main content
System StatusContact Support Agility Community

Exercise 3: Query a Scope (Project) for Specific Attributes


This tutorial will help you associate a project (Scope) that you would normally see in the VersionOne UI with data from the API.


What you'll learn

This exercise walks you through the process of accessing the Name, Description, Status and Members attributes (also called fields) that exist on a Scope.

Step 1: Add the attributes to the default query in the API Console and Execute Query

Add the Name, Description, Status and Members attributes to the URL in the API Console. The default query, when you started the API Console, displays many attributes for a Scope. However, we are only concerned with examining four, so we can list them individually in our query. When you are finished, go ahead and send the query.

Your output should look similar to this:

There were a total of three scopes sent back from our query. Let's focus on the second scope, "Scope:1005"; which begins at line 18, and ends at line 34. Each attribute that we queried, lives on the following lines:

  • Name - Line 19

  • Description - Line 20

  • Status -  Lines 21-24

  • Members - Lines 25-28 

Step 2: OIDs 

"OIDs", is the generic term for a system identifier, that represents a reference to a VersionOne asset. In the VersionOne system, it is guaranteed that each asset will have a unique identifier. For example, you can create two stories with the same name, and the system will maintain a unique way of accessing the two stories. VersionOne OIDS must have the following form: AssetType:Integer.

OIDs are read-only, generated by VersionOne, and used when writing queries. Recall in our exercise, that we examined: the "OID Scope:1005", which is the "OID" for the Project: "VersionOne REST APIs 101"; the "ScopeStatus:1012"  the "OID" for the Status; and Member:20,  the "OID" for the Member: "Administrator".

You will see OIDs split up into its component parts when you access them in some context. Recall in Step 2 of Exercise 2: Find a Scope (Project) OID Token in the UI, we extracted an OID from a URL. 

Examine the previous query output, and find this line below. In simplest terms this line means, "go to the place where you store all of your Scopes, and get me the Scope number 1020".

Asset href="/Api-Examples/rest-1.v1/Data/Scope/1020" id="Scope:1020">

Step 3: Data Types

Now that we have been exposed to OIDs, we need to revisit those four attributes, talk about what kind of data they can hold, and how OIDS relate to them.

  • Name
    This is an ordinary Scalar attribute. This is the most common, and simple; and when assigning something in a text attribute, you are assigning the literal value into the attribute.

  • Descriptions
    This is also an ordinary Scalar attribute.

  • Status
    This is something called a Single-Relation attribute.  A Single-Relation attribute contains a reference to a complex type that holds other information, in addition to the text representation of the value that we see on the screen.  

    • For example, if we examine status, we won't see "Special".  We will see a single OID ScopeStatus:1012.  

  • Members
    This is what we call a Multi-Relation attribute. This attribute holds a reference to multiple Member OIDs. It is basically a list of Members; and if you were to look inside the Members attribute, you would see a pointer to a resource that holds multiple OIDs.

    • For example, if we examine Members, we would see a reference to a list of 1 or more Members.

You will spend a lot of time reading and writing OIDS, if you write code that manipulates VersionOne assets using the VersionOne API.  Fortunately, you can download our .Net and JAVA SDKs to make things a little easier.

Step 4: Deeper Analysis of our attributes and output from our query (Optional)

Here is a graphical representation of XML output found in Step 1: Add the attributes to the default query in the API Console and Execute Query.

This image, is the same two element set of scopes; but here, we draw arrows to show how OIDs refer to some object from a VersionOne relation, which is similar to a database table. This image outlines the relationship of a list of Scopes in our system, along with their associated attributes. There are more attributes available in our Scope, but in exercise 1, we demonstrate how to minimize the number of attributes to examine.


When you look at your company’s data, you may see different statuses.  

This test instance contains this set of ScopeStatus values {Special, Hold, Current}. 

 Instead of looking at boring XML, the query output is translated into a graphic form. The status field, with the arrow attached to it, contains the value StoryStatus:1012. Instead of containing the literal string “Special”, which you would see in the VersionOne UI, it contains a system representation of ScopeStatus type (behind the scenes). The ScopeStatus types, live in their own relation.

In our instance, we have the “Special”, “Hold” and “Current” values available for Status in the UI. For each of the status values, there is a corresponding system representation. So basically, when you are in the VersionOne UI, and you set the Status to “Hold”, the VersionOne system is quietly inserting the value of ScopeStatus:1013 behind the scenes. 


  • Added specific attributes to a base query.

  • Examined three of the most common types of attributes: Scalar, Single-Relation, and Multi-Relation.

  • Examined OIDS.

  • (Optional) Examined the composition of the scope asset, including OIDs.