Skip to main content
Version: 24.3

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

This topic explains how to query a project for specific attributes.

Overview​

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

Prerequisites​

  • Access to a Digital.ai Agility 7.0 instance or newer. You can use https://www16.v1host.com/api-examplesfrom our previous exercises.

  • An understanding of all material found in Exercise 1: Basic Use of the API Console and Exercise 2: Find a Scope (Project) OID Token in the UI, including OIDS and Scopes.

  • Knowledge of the Agility API Console.

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:

Output

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. Recalling our exercise, that we examined: the "OID Scope:1005",which is the "OID" for theProject:"**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 Scalarattribute. 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 Scalarattribute.

  • 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 OIDScopeStatus: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 Agility assets using the Agility 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.

XML Output

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.

Scope Relationship

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

This test instance contains this set ofScopeStatusvalues

{***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 Agility UI, it contains a system representation of Scope Status type (behind the scenes). The Scope Status 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 Agility UI, and you set the Status to “Hold”, the Agility system is quietly inserting the value of ScopeStatus:1013 behind the scenes.

Review​

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

Quiz​

Don't have a good question yet

Submit