Skip to main content
System StatusContact Support

Documentation related to the following products will soon be moved to a new portal: ( Agility, Agility Connect and Agility Integrations Continuum and ALM Connect
Links from the site will automatically redirect to the new site.
If you have any questions, please contact Support. Agility Community

Querying Configurations and Localizations

In addition to working with VersionOne assets, the Java SDK provides read-only access to a subset of system configurations and localizations to allow for client-side data validation.

For system configurations, settings for Effort Tracking, Story Tracking Level, Defect Tracking Level are available so that entry of Effort, Detail Estimate, and ToDo can be done consistently with the way VersionOne is configured.

For system localizations, you can look up the value used within the VersionOne user interface based on the asset's or attribute's system name.

Prior to querying configurations and localizations in VersionOne, you must first instantiate a V1Connector object:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
IServices services = new Services(connector);

In versions of the SDK prior to the release, you would also have to instantiate a connector for the MetaModel object. However, starting with the 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 System Configurations

While working with VersionOne assets requires the use of the Services object, accessing the system configurations requires using the V1Configuration object. This example shows how to get the available system settings using the V1Configuration object:

V1Configuration configuration = new V1Configuration(connector);

System.out.println(String.format("Effort tracking level: %s", configuration.isEffortTracking()));
System.out.println(String.format("Story tracking level: %s", configuration.getStoryTrackingLevel()));
System.out.println(String.format("Defect tracking level: %s", configuration.getDefectTrackingLevel()));
System.out.println(String.format("Capacity planning: %s", configuration.getCapacityPlanning()));
System.out.println(String.format("Maximum attachment size: %s", configuration.getMaxAttachmentSize()));
/***** OUTPUT *****
Effort tracking level: True
Story tracking level: Mix
Defect tracking level: Mix
Capacity planning: ByMemberByTeam
Maximum attachment size: 4194304

Detail Estimate, ToDo and Effort can be entered for Stories and Defects, or for their child Tasks and Tests, depending on how the system is configured. The StoryTrackingLevel and DefectTrackingLevel properties indicate where input of Detail Estimate, ToDo and Effort are taken.

A value of "True" indicates that Detail Estimate, ToDo, and Effort input is accepted at the PrimaryWorkitem level only.  A value of "False" indicates that Detail Estimate, ToDo, and Effort input is accepted at the Task/Test level only.  A value of "Mix" indicates that Detail Estimate, ToDo, and Effort input is accepted at both the PrimaryWorkitem and Task/Test level.

Querying System Localizations

Accessing system localizations is accomplished via the Services object using its getLocalization method, and there are three approaches that it supports.

The first approach is used for getting the localized name of an asset based on its system name:

System.out.println(String.format("Timebox name: %s", services.getLocalization("Timebox")));
System.out.println(String.format("Scope name: %s", services.getLocalization("Scope")));
System.out.println(String.format("Epic name: %s", services.getLocalization("Epic")));
System.out.println(String.format("Story name: %s", services.getLocalization("Story")));
System.out.println(String.format("Defect name: %s", services.getLocalization("Defect")));
/***** OUTPUT *****
Timebox: Iteration
Scope: Project
Epic: Portfolio Item
Story: Story
Defect: Defect

The second approach is used for getting the localized value of a single attribute based on its attribute definition:

IAttributeDefinition scopeNameAttribute = services.getAttributeDefinition("Scope.Name");
IAttributeDefinition timeboxNameAttribute = services.getAttributeDefinition("Timebox.Name");
System.out.println(String.format("Scope name attribute: %s", services.getLocalization(timeboxNameAttribute)));
System.out.println(String.format("Timebox name attribute: %s", services.getLocalization(scopeNameAttribute)));
/***** OUTPUT *****
Scope name attribute: Title
Timebox name attribute: Title

The third approach is used for getting the localized values of multiple attributes based on their attribute definitions:

IAttributeDefinition nameAttribute = services.getAttributeDefinition("Story.Name");
IAttributeDefinition estimateAttribute = services.getAttributeDefinition("Story.Estimate");
ArrayList<IAttributeDefinition> attributes = new ArrayList<IAttributeDefinition>(Arrays.asList(nameAttribute, estimateAttribute));
Map<String, String> localizations = services.getLocalization(attributes);
System.out.println(String.format("Story name attribute: %s", localizations.get(nameAttribute.getToken())));
System.out.println(String.format("Story estimate attribute: %s", localizations.get(estimateAttribute.getToken())));
/***** OUTPUT *****
Story name attribute: Title
Story estimate attribute: Estimate Pts.