Querying Asset History

This topic explains how to query for asset history with optional parameter.

Overview

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". In addition, historical queries support all the regular query features such as selection, filtering, sorting, and paging.

Much like performing current asset queries, you must first instantiate a V1Connector and Services object prior to performing historical queries:

            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 theMetaproperty of theServicesobject.

Querying the History of a Single Asset

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

                IAssetType memberType = services.Meta.GetAssetType("Member");
                Query query = new Query(services.GetOid("Member:1000"), true);

                IAttributeDefinition changeDateAttribute = memberType.GetAttributeDefinition("ChangeDate");
                IAttributeDefinition emailAttribute = memberType.GetAttributeDefinition("Email");
                query.Selection.Add(changeDateAttribute);
                query.Selection.Add(emailAttribute);
                QueryResult result = services.Retrieve(query);
                AssetList memberHistory = result.Assets;
 
                foreach (Asset member in memberHistory)
                {
                Console.WriteLine(member.Oid.Token);
                Console.WriteLine(member.GetAttribute(changeDateAttribute).Value);
                Console.WriteLine(member.GetAttribute(emailAttribute).Value);
                Console.WriteLine();
                }

                /***** 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 MultipleAssets

This example shows how toretrieve history for all Member assets:

                IAssetType memberType = services.Meta.GetAssetType("Member");
                Query query = new Query(memberType, true);

                IAttributeDefinition changeDateAttribute = memberType.GetAttributeDefinition("ChangeDate");
                IAttributeDefinition emailAttribute = memberType.GetAttributeDefinition("Email");
                query.Selection.Add(changeDateAttribute);
                query.Selection.Add(emailAttribute);
                QueryResult result = services.Retrieve(query);
                AssetList memberHistory = result.Assets;
 
                foreach (Asset member in memberHistory)
                {
                Console.WriteLine(member.Oid.Token);
                Console.WriteLine(member.GetAttribute(changeDateAttribute).Value);
                Console.WriteLine(member.GetAttribute(emailAttribute).Value);
                Console.WriteLine();
                }

                /***** 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 AsOf property 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.Meta.GetAssetType("Story");
                Query query = new Query(storyType, true);

                IAttributeDefinition nameAttribute = storyType.GetAttributeDefinition("Name");
                IAttributeDefinition estimateAttribute = storyType.GetAttributeDefinition("Estimate");
                query.Selection.Add(nameAttribute);
                query.Selection.Add(estimateAttribute);
                query.AsOf = DateTime.Now.AddDays(-7);
                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
                3
 
                Story:1064
                Add Customer Details
                1
 
                Story:1065
                Add Customer Header
                3
                ******************/