Skip to main content
System StatusContact Support
VersionOne Community

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

Overview 

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

Prerequisites

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, but 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 are the generic term for a system identifier that represents a reference to a VersionOne Lifecycle asset.  In the Lifecycle 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 of AssetType:Integer.

OIDs are read-only and generated by Lifecycle and we will use them when writing queries.  Recall that in our exercise, we examined the OID Scope:1005 which is the OID for the project VersionOne Lifecycle 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 contexts. 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 yours 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 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 so if you were to look inside of the Members attribute, you would see a pointer some 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 Lifecycle assets using the VersionOne Lifecycle 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 demonstrated 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, I have translated the query output 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 Lifecycle UI, it contains a system representation, of ScopeStatus type underneath the scenes. These ScopeStatus type live in their own relation.  In our instance, we have the “Special”, “Hold” and “Current” value available for Status in the UI. For each of these statuses, there is a corresponding system representation. So basically, when you are in the Lifecycle UI and you set the Status to “Hold”, the VersionOne system is quietly inserting the value of ScopeStatus:1013 behind the scenes. 

Review

  • Added specific attributes to a base query.

  • Examined the 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.