Skip to main content
Matrix42 Self-Service Help Center

History SDK


Additionally to the History Wizard, you are able to browse the history data by using an interface in your C# code or by using Workflow Studio activities.

The direct browsing of the history database by SQL is not supported and the table Schema might change at any time. The SDK is the supported way to browse history data. For cloud environments access to the history database might be restricted or the data is not stored in a database at all.

Workflow Activities

There are 4 different workflow activities that offer methods to browse the history data. These are located in the workflow studio under GeneralHistory and are as follows:

  1. GetTransactions
  2. GetTransactionDetailsObject
  3. GetTransactionDetailsCi
  4. GetTransactionDetailsAttribute

All 4 activities may return a large amount of data. To handle this all activities share a mechanism to page the data. Interface

As long as you are working in the context of the Matrix42 processes, the interface IHistoryQuery in the namespace Matrix42.History.Contracts can be automatically injected by the dependency injection framework into your code to use it. You need to reference the Matrix42.History.Contracts assembly to get references to all the classes used by this interface and the methods.

The interface defines 4 methods, 2 of which (QueryTransactionsForObject, QueryTransactionDetailsForObject) provide you with the same functionality as the History Wizard, browsing data when you have an objectId

The other 2 methods (QueryTransactionDetailsForCi, QueryTransactionDetailsForCiAndAttribute) allow you to request data from a different base, you can request the data for a certain Schema CI without knowing the object or for an attribute of a CI. Be aware that this might return a massive amount of data, you should always apply reasonable filter criteria.

Always use the Schema to get the IDs of Schema objects, never rely on constants. The IDs of relation attributes are not fixed between environments and might differ.

The 4 request methods are very similar, they expect a request object defining the parameters of the request and they all have an out string parameter called СontinuationToken. All replies from the methods are paged in case a certain amount of data is in the reply. Each request object class has a property ContinuationToken, the СontinuationToken is used to access the next pages. The mechanism is the following, you receive the first page of data when the ContinuationToken in the request is not set and as long aы you reсeive a СontinuationToken that is not null you can ask for the next batch of data by setting the ContinuationToken as a parameter in the request object. You should not change the other parameters of the request except the ContinuationToken, the behavior is otherwise undefined and may give you incorrect data.

The method QueryTransactionsForObject returns an array of objects of the class ObjectTransaction.

The return type of the 3 other methods (the transaction details methods) is an array of objects of the base class ObjectTransactionDetail. This class has 2 child classes ObjectTransactionDetailRelation and ObjectTransactionDetailScalar. Objects of these classes are returned depending on the kind of change.


    public class HistoryRequestSample
        private readonly IHistoryQuery _historyQuery;
        public HistoryRequestSample(IHistoryQuery historyService)
            _historyQuery = historyService;
        public void GetTransactionsAndDetailsForObjectId()
            var objectID = new Guid("{7900057B-5DA2-43B3-B527-C806F2B2911B}"); //your object id
            string token = null;
                var queryResult = _historyQuery.QueryTransactionsForObject(
                    new ObjectTransactionRequest
                        ObjectId = transactionRequest.ObjectId
/* optional parameters
                        From = ...,
                        Until = ...,
                        UserId = ...,
                        AttributeIds = ...,
                        TransactionType = ...,
                        ContinuationToken = token
                    out token);
                // do something with the result, here we ask for the details of every transaction
                foreach(ObjectTransaction transaction in queryResult)
                    string detailsToken = null;
                        var detailsResult = _historyQuery.QueryTransactionDetailsForObject(
                            new ObjectTransactionDetailRequest
                                TransactionId =  transaction.Id,
                                ObjectId = objectID,
                                ContinuationToken = detailsToken
                            out detailsToken);
                        // do something with the result.
                    } while (detailsToken != null)
            } while (token != null);
  • Was this article helpful?