Querying Assets
One of the most fundamental, if not the most common, things that you can do with the Java SDK is to query Digital.ai Agility 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 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 MetaModel object. However, starting with the 15.0.0.0 release, that is no longer necessary. The MetaModel object is now available from the get Meta 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 Meta Model object. However, starting with the 15.0.0.0 release, that is no longer necessary. The Meta Model object is now available from the get Meta 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 Agility:
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 theGroupFilterTerm and FilterTermobjects, then setting the filter for the query using the setFiltermethod 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 getOrderBymethod 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 Detail Estimate 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
******************/