Querying Configurations and Localizations

In addition to working with Digital.ai Agility 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 To Do can be done consistently with the way Agility is configured.

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

Prior to querying configurations and localizations in Agility, you must first instantiate a V1Connector 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 theMetaModelobject. However, starting with the 15.0.0.0 release, that is no longer necessary. TheMetaModelobject is now available from thegetMetamethod of theServicesobject. For more advancedServicesconstructor overloads, see the Creating a Services Object topic.

Querying System Configurations

While working with Agility assets requires the use of the Services object, accessing the system configurations requires using the V1Configuration object. This example shows how toget 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, To Do 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, To Do and Effort are taken.

A value of "True" indicates that Detail Estimate, To Do, and Effort input is accepted at the Primary Workitem 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 Primary Workitem and Task/Test level.

Querying System Localizations

Accessing system localizations is accomplished via the Services object using its getLocalizationmethod, 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 onitsattribute 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 thirdapproach is used for getting the localized values of multipleattributes based ontheir 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.
                ******************/