Querying Asset History

It is often useful to query Digital.ai Agility for the history of a particular asset. This can be useful for reporting on how an asset has changed over time, or to see who has changed it and the moment the change occurred. Querying for asset history is similar to querying for current asset data, the difference being that you set the optional Historical parameter of the Query object to "true".

Querying the History of a Single Asset

This example shows how to retrieve the history of the Member asset with ID 1000:

                IAssetType memberType = services.getMeta().getAssetType("Member");
                Query query = new Query(memberType, true);
                IAttributeDefinition idAttribute = memberType.getAttributeDefinition("ID");
                IAttributeDefinition changeDateAttribute = memberType.getAttributeDefinition("ChangeDate");
                IAttributeDefinition emailAttribute = memberType.getAttributeDefinition("Email");
                query.getSelection().add(changeDateAttribute);
                query.getSelection().add(emailAttribute);
                FilterTerm idTerm = new FilterTerm(idAttribute);
                idTerm.equal("Member:1000");
                query.setFilter(idTerm);
                QueryResult result = services.retrieve(query);

                for (Asset member : result.getAssets()) {
                System.out.println(member.getOid().getToken());
                System.out.println(member.getAttribute(changeDateAttribute).getValue());
                System.out.println(member.getAttribute(emailAttribute).getValue());
                System.out.println();
                }

                /***** OUTPUT *****
                Member:1000:105
                4/2/2015 1:22:03 PM
                andre.agile@company.com

                Member:1000:101
                3/29/2015 4:10:29 PM
                andre@company.net
                ******************/
            

As demonstrated in the example above, to create a history query, you provide a boolean value of "true" to the second argument of the Query object constructor.

Querying the History of Multiple Assets

This example shows how toretrieve history for all Member assets:

                IAssetType memberType = services.getMeta().getAssetType("Member");
                Query query = new Query(memberType, true);
                IAttributeDefinition changeDateAttribute = memberType.getAttributeDefinition("ChangeDate");
                IAttributeDefinition emailAttribute = memberType.getAttributeDefinition("Email");
                query.getSelection().add(changeDateAttribute);
                query.getSelection().add(emailAttribute);
                QueryResult result = services.retrieve(query);

                for (Asset member : result.getAssets()) {
                System.out.println(member.getOid().getToken());
                System.out.println(member.getAttribute(changeDateAttribute).getValue());
                System.out.println(member.getAttribute(emailAttribute).getValue());
                System.out.println();
                }

                /***** OUTPUT *****            
                Member:1010:106
                4/2/2015 3:27:23 PM
                tammy.coder@company.com
       
                Member:1000:105
                4/2/2015 1:22:03 PM
                andre.agile@company.com
       
                Member:1000:101
                3/29/2015 4:10:29 PM
                andre@company.net
            ******************/

Again, the response is a list of historical assets. There will be multiple Asset objects returned for an asset that has changed previously.

Querying Asset History "as of" a Specific Point in Time

This example shows how to use the setAsOf method of the Query object to retrieve data as it existed at some point in time. This query finds the version of each Story asset as it existed seven days ago:

                IAssetType storyType = services.getMeta().getAssetType("Story");
                Query query = new Query(storyType, true);
                IAttributeDefinition nameAttribute = storyType.getAttributeDefinition("Name");
                IAttributeDefinition estimateAttribute = storyType.getAttributeDefinition("Estimate");
                query.getSelection().add(nameAttribute);
                query.getSelection().add(estimateAttribute);
        
                Calendar c = Calendar.getInstance();
                c.add(Calendar.DAY_OF_MONTH, -7);
                query.setAsOf(c.getTime());
        
                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
                3
 
                Story:1064
                Add Customer Details
                1
 
                Story:1065
                Add Customer Header
                3
                ******************/