Querying Assets
This topic explains how to query for assets in Agility.
Overview
One of the most fundamental, if not the most common, things that you can do with the .NET SDK is to query VersionOne for information about the assets that it contains. To do so, all you need is a valid V1Connectorobject and an instance of the Services object, which is the primary object that you will use to perform actions with the Digital.ai Agility API. Once you have those, you can then write queries to access data for just about any asset contained within Agility.
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 MetaModelobject. However, starting with the 15.0.0.0 release, that is no longer necessary. The MetaModel object is now available from the Meta property of the Services object.
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.Assets[0];
Console.WriteLine(member.Oid.Token);
/***** OUTPUT ****
Member:20
******************/
Querying an Asset for Specific Attributes
This example shows how to retrieve an asset with specific attributes by using the Selection property of the Query object:
Oid memberId = services.GetOid("Member:20");
Query query = new Query(memberId);
IAttributeDefinition nameAttribute = metaModel.GetAttributeDefinition("Member.Name");
IAttributeDefinition emailAttribute = metaModel.GetAttributeDefinition("Member.Email");
query.Selection.Add(nameAttribute);
query.Selection.Add(emailAttribute);
QueryResult result = services.Retrieve(query);
Asset member = result.Assets[0];
Console.WriteLine(member.Oid.Token);
Console.WriteLine(member.GetAttribute(nameAttribute).Value);
Console.WriteLine(member.GetAttribute(emailAttribute).Value);
/***** 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 Agility:
IAssetType storyType = services.Meta.GetAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.GetAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.GetAttributeDefinition("Estimate");
query.Selection.Add(nameAttribute);
query.Selection.Add(estimateAttribute);
QueryResult result = services.Retrieve(query);
foreach (Asset story in result.Assets)
{
Console.WriteLine(story.Oid.Token);
Console.WriteLine(story.GetAttribute(nameAttribute).Value);
Console.WriteLine(story.GetAttribute(estimateAttribute).Value);
Console.WriteLine();
}
/***** 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
This example shows how to query using FilterTerm with the Filter property 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.Meta.GetAssetType("Task");
Query query = new Query(taskType);
IAttributeDefinition nameAttribute = taskType.GetAttributeDefinition("Name");
IAttributeDefinition todoAttribute = taskType.GetAttributeDefinition("ToDo");
query.Selection.Add(nameAttribute);
query.Selection.Add(todoAttribute);
FilterTerm term = new FilterTerm(todoAttribute);
term.Equal(0);
query.Filter = term;
QueryResult result = services.Retrieve(query);
foreach (Asset task in result.Assets)
{
Console.WriteLine(task.Oid.Token);
Console.WriteLine(task.GetAttribute(nameAttribute).Value);
Console.WriteLine(task.GetAttribute(todoAttribute).Value);
Console.WriteLine();
}
/***** OUTPUT *****
Task:1153
Code Review
0
Task:1154
Design Component
0 ...
******************/
Querying with Searching
This example shows how to use theFind property of the Query object to search for text. This query will retrieve only Request assets with the word "Urgent" in the name:
IAssetType requestType = services.Meta.GetAssetType("Request");
Query query = new Query(requestType);
IAttributeDefinition nameAttribute = requestType.GetAttributeDefinition("Name");
query.Selection.Add(nameAttribute);
query.Find = new QueryFind("Urgent", new AttributeSelection(nameAttribute));
QueryResult result = services.Retrieve(query);
foreach (Asset request in result.Assets)
{
Console.WriteLine(request.Oid.Token);
Console.WriteLine(request.GetAttribute(nameAttribute).Value);
Console.WriteLine();
}
/***** OUTPUT *****
Request:1195
Urgent! Filter by owner
Request:1244
Urgent: improve search performance ...
******************/
Querying with Sorting
This example shows how to use the OrderBy property of the Query object to sort the results. This query will retrieve Story assets sorted by increasing Estimate:
IAssetType storyType = services.Meta.GetAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.GetAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.GetAttributeDefinition("Estimate");
query.Selection.Add(nameAttribute);
query.Selection.Add(estimateAttribute);
query.OrderBy.MinorSort(estimateAttribute, OrderBy.Order.Ascending);
QueryResult result = services.Retrieve(query);
foreach (Asset story in result.Assets)
{
Console.WriteLine(story.Oid.Token);
Console.WriteLine(story.GetAttribute(nameAttribute).Value);
Console.WriteLine(story.GetAttribute(estimateAttribute).Value);
Console.WriteLine();
}
/***** 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 Paging property of the Query object. This query will retrieve the first 3 Story assets:
IAssetType storyType = services.Meta.GetAssetType("Story");
Query query = new Query(storyType);
IAttributeDefinition nameAttribute = storyType.GetAttributeDefinition("Name");
IAttributeDefinition estimateAttribute = storyType.GetAttributeDefinition("Estimate");
query.Selection.Add(nameAttribute);
query.Selection.Add(estimateAttribute);
query.Paging.PageSize = 3;
query.Paging.Start = 0;
QueryResult result = services.Retrieve(query);
foreach (Asset story in result.Assets)
{
Console.WriteLine(story.Oid.Token);
Console.WriteLine(story.GetAttribute(nameAttribute).Value);
Console.WriteLine(story.GetAttribute(estimateAttribute).Value);
Console.WriteLine();
}
/***** OUTPUT *****
Story:1063
Logon
2
Story:1064
Add Customer Details
2
Story:1065
Add Customer Header
3
******************/
The PageSize property shown asks for 3 items, and the Start property indicates to start at 0. The next 3 items can be retrieve with PageSize=3, Start=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:
IAssetType assetType = services.Meta.GetAssetType("Story");
Oid assetOID = services.GetOid("Story:6606");
Query query = new Query(assetOID);
IAttributeDefinition nameAttribute = assetType.GetAttributeDefinition("Children:Test.Name");
query.Selection.Add(nameAttribute);
QueryResult result = services.Retrieve(query);
foreach (var value in result.Assets.First().GetAttribute(nameAttribute).Values)
{
Console.WriteLine(value);
}
/***** OUTPUT *****
Test #1
Test #2
******************/
Querying with Functions
This example shows how to use a function to sum the Detail Estimate values for all Task assets associated with a specific Story:
IAssetType assetType = services.Meta.GetAssetType("Story");
Oid assetOID = services.GetOid("Story:6606");
Query query = new Query(assetOID);
IAttributeDefinition sumAttribute = assetType.GetAttributeDefinition("Children:Task.DetailEstimate.@Sum");
query.Selection.Add(sumAttribute);
QueryResult result = services.Retrieve(query);
Console.WriteLine(result.Assets.First().GetAttribute(sumAttribute).Value);
/***** OUTPUT *****
20
******************/