Skip to main content
System StatusContact Support
VersionOne Community

Querying Assets

One of the most fundamental, if not the most common, things that you can do with the Java SDK is to query VersionOne for information about the assets that it contains. To do so, all you need is a valid V1Connector object and an instance of the Services object, which is the primary object that you will use to perform actions with the VersionOne API. Once you have those, you can then write queries to to access data for just about any asset contained within VersionOne. Here's a quick example of instantiating a V1Connector and Services object: V1Connector connector = V1Connector .withInstanceUrl("<Server Base URI>") .withUserAgentHeader("AppName", "1.0") .withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=") .build(); IServices services = new Services(connector); In versions of the SDK prior to the 15.0.0.0 release, you would also have to instantiate a connector for the MetaModel object. However, starting with the 15.0.0.0 release, that is no longer necessary. The MetaModel object is now available from the getMeta method of the Services object. For more advanced Services constructor overloads, see the Creating a Services Object topic.

Quick Start

Here's a quick example of instantiating a V1Connector and Services object:

V1Connector connector = V1Connector .withInstanceUrl("<Server Base URI>") 
.withUserAgentHeader("AppName", "1.0") 
.withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=") 
.build(); 
IServices services = new Services(connector);

In versions of the SDK prior to the 15.0.0.0 release, you would also have to instantiate a connector for the MetaModel object. However, starting with the 15.0.0.0 release, that is no longer necessary. The MetaModel object is now available from the getMeta method of the Services object. For more advanced Services constructor overloads, see the Creating a Services Object topic.

Querying a Single Asset

In this example, the asset will have its OID populated, but will not have any other attributes populated. This is to minimize the size of the data sets returned. The next example shows how to ask for an asset with specific attributes populated:

Oid memberId = services.getOid("Member:20");
Query query = new Query(memberId);
QueryResult result = services.retrieve(query);
Asset member = result.getAssets()[0];

System.out.println(member.getOid().getToken());

/***** OUTPUT *****
Member:20
******************/

Querying an Asset for Specific Attributes

This example shows how to retrieve an asset with specific attributes using the getSelection method of the Query object:

Oid memberId = services.getOid("Member:20");
Query query = new Query(memberId);
IAttributeDefinition nameAttribute = services.getMeta().getAttributeDefinition("Member.Name");
IAttributeDefinition emailAttribute = services.getMeta().getAttributeDefinition("Member.Email");
query.getSelection().add(nameAttribute);
query.getSelection().add(emailAttribute);
QueryResult result = services.retrieve(query);
Asset member = result.getAssets()[0];

System.out.println(member.getOid().getToken());
System.out.println(member.getAttribute(nameAttribute).getValue());
System.out.println(member.getAttribute(emailAttribute).getValue());

/***** OUTPUT *****
Member:20
Administrator
admin@company.com
******************/

Query for a List of Assets

This example shows how to retrieve specific attributes for all the Stories contained within VersionOne:

IAssetType storyType = services.getMeta().getAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.getAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.getAttributeDefinition("Estimate");
query.getSelection().add(nameAttribute);
query.getSelection().add(estimateAttribute);
QueryResult result = services.retrieve(query);

for (Asset story : result.getAssets()) {
    System.out.println(story.getOid().getToken());
    System.out.println(story.getAttribute(nameAttribute).getValue());
    System.out.println(story.getAttribute(estimateAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Story:1083
View Daily Call Count
5
 
Story:1554
Multi-View Customer Calendar
1 ...
******************/

Depending on your security role, you may not be able to see all the Story assets in the entire system.

Querying with Filtering on a Single Attribute

This example shows how to query using a FilterTerm with the setFilter method of the Query object to filter the results that are returned. This query will retrieve only Task assets with a ToDo value of zero:

IAssetType taskType = services.getMeta().getAssetType("Task");
Query query = new Query(taskType);
IAttributeDefinition nameAttribute = taskType.getAttributeDefinition("Name");
IAttributeDefinition todoAttribute = taskType.getAttributeDefinition("ToDo");
query.getSelection().add(nameAttribute);
query.getSelection().add(todoAttribute);

FilterTerm toDoTerm = new FilterTerm(todoAttribute);
toDoTerm.equal(0);
query.setFilter(toDoTerm);
QueryResult result = services.retrieve(query);

for (Asset task : result.getAssets()) {
    System.out.println(task.getOid().getToken());
    System.out.println(task.getAttribute(nameAttribute).getValue());
    System.out.println(task.getAttribute(todoAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Task:1153
Code Review
0

Task:1154
Design Component
0 ...
******************/

Querying with Filtering on Multiple Attributes

This example shows how to group multiple filter terms using the GroupFilterTerm and FilterTerm objects, then setting the filter for the query using the setFilter method of the Query object. This query will retrieve only Defect assets in the base system project with a ToDo value of zero:

Oid projectOid = services.getOid("Scope:0");
IAssetType assetType = services.getMeta().getAssetType("Defect");

Query query = new Query(assetType);
IAttributeDefinition projectAttribute = assetType.getAttributeDefinition("Scope");
IAttributeDefinition todoAttribute = assetType.getAttributeDefinition("ToDo");
query.getSelection().add(projectAttribute);
query.getSelection().add(todoAttribute);

FilterTerm projectTerm = new FilterTerm(projectAttribute);
projectTerm.equal(projectOid);
FilterTerm todoTerm = new FilterTerm(todoAttribute);
todoTerm.equal(0);

GroupFilterTerm groupFilter = new AndFilterTerm(projectTerm, todoTerm);
query.setFilter(groupFilter);

QueryResult result = services.retrieve(query); 
for (Asset task : result.getAssets()) {
    System.out.println(task.getOid().getToken());
    System.out.println(task.getAttribute(projectAttribute).getValue());
    System.out.println(task.getAttribute(todoAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Defect:37396
Scope:0
0.0

Defect:39675
Scope:0
0.0
******************/

Querying with Searching

This example shows how to use the setFind method of the Query object to search for text. This query will retrieve all Story assets with the word "Urgent" in their name:

IAssetType requestType = services.getMeta().getAssetType("Story");
Query query = new Query(requestType);
IAttributeDefinition nameAttribute = requestType.getAttributeDefinition("Name");
query.getSelection().add(nameAttribute);

AttributeSelection selection = new AttributeSelection();
selection.add(nameAttribute);
query.setFind(new QueryFind("Urgent", selection)); 
QueryResult result = services.retrieve(query);

for (Asset request : result.getAssets())
{
    System.out.println(request.getOid().getToken());
    System.out.println(request.getAttribute(nameAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Story:1195
Urgent!  Filter by owner
******************/

Querying with Sorting

This example shows how to use the getOrderBy method of the Query object to sort the results. This query will retrieve all Story assets sorted by increasing Estimate:

IAssetType storyType = services.getMeta().getAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.getAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.getAttributeDefinition("Estimate");
query.getSelection().add(nameAttribute);
query.getSelection().add(estimateAttribute);
query.getOrderBy().minorSort(estimateAttribute, Order.Ascending);
QueryResult result = services.retrieve(query);

for (Asset story : result.getAssets()) {
    System.out.println(story.getOid().getToken());
    System.out.println(story.getAttribute(nameAttribute).getValue());
    System.out.println(story.getAttribute(estimateAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Story:1073
Add Order Line
1
Story:1068
Update Member
2 ...
******************/

There are two methods you can call on the OrderBy object to sort your results: minorSort and majorSort. If you are sorting by only one field, it does not matter which one you use. If you want to sort by multiple fields, you need to call either minorSort or majorSort multiple times. The difference is that each time you call minorSort, the parameter will be added to the end of the OrderBy statement. Each time you call majorSort, the parameter will be inserted at the beginning of the OrderBy statement.

Querying with Paging

This example shows how to retrieve a "page" of query results by using the getPaging method of the Query object. This query will retrieve the first 3 Story assets:

IAssetType storyType = services.getMeta().getAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.getAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.getAttributeDefinition("Estimate");
query.getSelection().add(nameAttribute);
query.getSelection().add(estimateAttribute);
query.getPaging().setPageSize(3);
query.getPaging().setStart(0);
QueryResult result = services.retrieve(query);

for (Asset story : result.getAssets()) {
    System.out.println(story.getOid().getToken());
    System.out.println(story.getAttribute(nameAttribute).getValue());
    System.out.println(story.getAttribute(estimateAttribute).getValue());
    System.out.println();
}

/***** OUTPUT *****
Story:1063
Logon
2

Story:1064
Add Customer Details
2

Story:1065
Add Customer Header
3
******************/

The setPageSize method shown asks for 3 items, and the setStart method indicates to start at 0. The next 3 items can be retrieve with setPageSize=3, setStart=3.

Querying with Downcasting

This example shows how to use a downcast to select the Name attribute of all Test assets associated with a specific Story:

Oid assetOID = services.getOid("Story:7608");
IAssetType assetType = services.getMeta().getAssetType("Story");
Query query = new Query(assetOID);
IAttributeDefinition nameAttribute = assetType.getAttributeDefinition("Children:Test.Name");
query.getSelection().add(nameAttribute);
QueryResult result = services.retrieve(query);

for (Object value : result.getAssets()[0].getAttribute(nameAttribute).getValues()) {
    System.out.println(value);
}

/***** OUTPUT *****
Test #1
Test #2
******************/

Querying with Functions

This example shows how to use a function to sum the DetailEstimate values for all Task assets associated with a specific Story:

Oid assetOID = services.getOid("Story:7608");
IAssetType assetType = services.getMeta().getAssetType("Story");
Query query = new Query(assetOID);
IAttributeDefinition sumAttribute = assetType.getAttributeDefinition("Children:Task.DetailEstimate.@Sum");
query.getSelection().add(sumAttribute);
QueryResult result = services.retrieve(query);

System.out.println(result.getAssets()[0].getAttribute(sumAttribute).getValue());

/***** OUTPUT *****
20.0
******************/
  • Was this article helpful?