Chat now with support
Chat with Support

Welcome, erwin customers to Quest Support Portal click here for for frequently asked questions regarding servicing your supported assets.

InTrust 11.3 - InTrust SDK Reference

Getting Started with Repository Services API

To check that the functionality of repository services API is available, use the RepositoryRecordInserterExample.exe test application, which is installed with the InTrust SDK. Run this application from the command prompt as follows:

RepositoryRecordInserterTest.exe <InTrust_server_binding_string> <repository_name>

<InTrust_server_binding_string> can be the name of the InTrust server.

<repository_name> is either the name of the repository as it appears in the InTrust UI (InTrust Deployment Manager, Repository Viewer, InTrust Manager).

Example:

RepositoryRecordInserterExample.exe intrust01 "Default InTrust Audit Repository"

The example uses the “Default InTrust Audit Repository” name. A repository with this name is created during InTrust deployment, so unless it has been renamed, it is present in every InTrust environment.

Testing Repository Searching

If the test program runs successfully, you should see event data in the command prompt's standard output. Getting the data is actually the second stage of the program's operation. The first stage is writing that data.

Testing Event Writing

The program writes a number of events to the specified repository. To examine them in detail, connect to the repository with Repository Viewer. For all these events, “MyComputer” is used as the Source Computer parameter value and “computer” as the Computer parameter value.

Next Steps

The sources of RepositoryRecordInserterExample.exe should have been provided to you together with the InTrust SDK installer. Open the project in Visual Studio, study it, try to customize it and test the effects of your changes.

Log Knowledge Base API

The log knowledge base contains settings for transforming data from original log formats to the repository format. The API does not work with predefined log definitions, which are completely out of its scope; it is designed only for user-defined logs.

To work with the log knowledge base, use the following interfaces:

To begin working with the log knowledge base, get a collection of known organizations (Organizations method of the IInTrustEnvironment interface) and pick the necessary one. This involves working with the IInTrustOrganizationCollection interface. Organizations are discovered by an Active Directory query.

The IInTrustOrganization that you get has the Eventory method, which provides access to the organization-wide log knowledge base.

For details about the format of rules for matching log events and mapping fields, see Log Transformation Rule Format.

Caution: If you modify the knowledge base for a specific log, this will invalidate all existing index data for that log in all repositories that contain the log. Indexed searches will no longer find this log’s events gathered prior to the modification. Data gathered after the modification will be indexed correctly and be searchable.

If the unavailability of old data is not a problem for you, you don't have to do anything. Otherwise, you will need to recreate valid indexes for all repositories that contain the log. However, it is not feasible to recreate an index for a large production repository without taking it offline for a long time. If you need to experiment with log knowledge base editing, use a dedicated test organization and small repositories, which can be reindexed quickly.

For details about repository reindexing, see Recreating the Index.

Example

static void GetFullEventory()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
string eventory = ev.Eventory;
    
Console.WriteLine("Full eventory : " + eventory);
}
static void AddNewLog()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection logs = ev.Logs;
    
IInTrustEventoryItem log = logs.Add("NewLog",
        
@"<FieldInfo>
            <Fields>
                <Field FieldName = ""New field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
            </Fields>
            <EventRules>
                <Event EventID = ""701"">
                    <Field Name = ""Who"" Index = ""11""></Field>
                    <Field Name = ""What"" Index = ""12""></Field>
                    <Field Name = ""Object_Type"" Index = ""13""></Field>
                    <Field Name = ""Object_Name"" Index = ""14""></Field>
                </Event>
            </EventRules>
        </FieldInfo>"
);
}
static void GetLogAndChangeRule()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection logs = ev.Logs;
    
IInTrustEventoryItem log = logs.Item("NewLog");
    
log.Rules = @"<FieldInfo>
        <Fields>
            <Field FieldName = ""New field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
        </Fields>
        <EventRules>
            <Event EventID = ""701"">
                <Field Name = ""Who"" Index = ""11""></Field>
            </Event>
        </FieldInfo>"
;
}
static void EnumLogs()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection logs = ev.Logs;
    
foreach (IInTrustEventoryItem cur_log in logs)
    
{
        
string log_name = cur_log.Name;
        
string log_rule = cur_log.Rules;
        
Console.WriteLine("Log name : " + log_name);
        
Console.WriteLine("Log rule : " + log_rule);
    
}
}
static void RemoveLog()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection logs = ev.Logs;
    
logs.Remove("NewLog");
}
static void AddNewDataSource()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection dataSources = ev.DataSources;
    
IInTrustEventoryItem dataSource = dataSources.Add("{10000000-0000-0000-0000-000000000001}",@"<FieldInfo>
  <Fields>
    <Field FieldName = ""New field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
  </Fields>
  <EventRules>
    <Event EventID = ""701"">
      <Field Name = ""Who"" Index = ""11""></Field>
      <Field Name = ""What"" Index = ""12""></Field>
      <Field Name = ""Object_Type"" Index = ""13""></Field>
      <Field Name = ""Object_Name"" Index = ""14""></Field>
    </Event>
  </EventRules>
</FieldInfo>"
);
}
static void GetDataSourceAndChangeRule()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection dataSources = ev.DataSources;
    
IInTrustEventoryItem dataSource = dataSources.Item("{10000000-0000-0000-0000-000000000001}");
    
dataSource.Rules = @"<FieldInfo>
        <Fields>
            <Field FieldName = ""New field"" DisplayName = ""NewField"" IsIndexed = ""true""></Field>
        </Fields>
        <EventRules>
            <Event EventID = ""701"">
                <Field Name = ""Who"" Index = ""11""></Field>
            </Event>
        </FieldInfo>"
;
}
static void EnumDataSources()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection dataSources = ev.DataSources;
    
foreach (IInTrustEventoryItem curDataSource in dataSources)
    
{
        
string ds_name = curDataSource.Name;
        
string ds_rule = curDataSource.Rules;
        
Console.WriteLine("Data source name : " + ds_name);
        
Console.WriteLine("Data source rule : " + ds_rule);
    
}
}
static void RemoveDataSources()
{
    
IInTrustEnvironment env = new InTrustEnvironment();
    
IInTrustServer server = env.ConnectToServer("10.30.46.24");
    
IInTrustOrganization org = server.Organization;
    
IInTrustEventory ev = org.Eventory;
    
IInTrustEventoryItemCollection dataSources = ev.DataSources;
    
dataSources.Remove("{10000000-0000-0000-0000-000000000001}");
}

NOTE: In the functions that handle data sources, the data source name must be in GUID format; for example:

{10000000-0000-0000-0000-000000000001}

Log Transformation Rule Format

Log transformation rules are defined as XML. The structure of a rule is shown in the example below, which contains all of the tags and parameters available.

<FieldInfo>
  <Fields>
    <Field FieldName = "TTF" DisplayName = "TTest Field" IsIndexed = "true"></Field>
    <Field FieldName = "TTF2" DisplayName = "TTest Field 2" IsIndexed = "true"></Field>
  </Fields>
  <EventRules>
    <Event EventID = "701">
      <Field Name = "TTF" Index = "1"></Field>
      <Field Name = "TTF2" Index = "3"></Field>
    </Event>
  </EventRules>
</FieldInfo>

Log events are matched by Event ID, and the Field tags specify how the original event fields are mapped to repository record fields. The Index parameter specifies the index of the target insertion string.

The following is a variation of the example above:

<FieldInfo>
    <Fields>
        <Field FieldName = "TTF" DisplayName = "TTest Field" IsIndexed = "true"></Field>
        <Field FieldName = "TTF2" DisplayName = "TTest Field 2" IsIndexed = "true"></Field>
    </Fields>
    <EventRules>
        <Field Name = "TTF" Index = "1"></Field>
        <Field Name = "TTF2" Index = "3"></Field>
    </EventRules>
</FieldInfo>

In this second snippet, the rule applies to all event IDs in a log.

Interfaces

The following is a list of all interfaces available with the InTrust repository API:

Interface Details
IBulkEventWithReadExtensions Results of a repository search as an array of event_with_read_extensions structures.
IBulkRecord Records packed into a single batch as an array of record structures for writing to the repository.
IBulkRecord2 Results of a repository search as an array of record2 structures.
ICookie Acts as the owner of a repository search and can stop the search.
IEventToRecordFormatter Transforms event records to a representation suitable for insertion into a repository by the PutRecords2 method of IRepositoryRecordInserter.
IIdleRepository An idle repository has the correct structure on the file system, but is not registered with an InTrust organization. Currently, you can search in idle repositories using the repository API, but you cannot write to them.
IIdleRepositoryFactory Creates an idle InTrust repository.
IIndexManager Provides access to indexing-related operations.
IIndexManagerFactory Creates an instance of IIndexManager for a production or idle repository.
IInTrustEnvironment Entry point for access to InTrust organizations, servers and repositories.
IInTrustEventory Provides access to the log knowledge base, which contains rules that govern the transformation of log entries into repository and event records.
IInTrustEventoryItem Represents an entry in the log knowledge base.
IInTrustEventoryItemCollection Provides a collection of IInTrustEventoryItem interfaces.
IInTrustOrganization Provides access to an InTrust organization.
IInTrustOrganizationCollection Provides a collection of all available InTrust organizations.
IInTrustRepository Provides the searching and writing capabilities of a repository.
IInTrustRepositoryCollection Provides a collection of all repositories available in the InTrust organization.
IInTrustRepositorySearcher Provides repository search capabilities.
IInTrustServer Provides access to an InTrust server.
IInTrustServerCollection Provides a collection of all InTrust servers in the InTrust organization.
IMultiRepositorySearcher A container for search objects that lets you search in all of the specified repositories simultaneously.
IMultiRepositorySearcherFactory Creates an instance of IMultiRepositorySearcher.
IObservable Defines a provider for push-based notification.
IObserver Provides a mechanism for receiving push-based notifications. You need to create your own implementation of this interface.
IProperty Property attached to an InTrust repository. A property is a way to tag repositories for arbitrary purposes.
IPropertyCollection Collection of properties associated with an InTrust repository. Access to the collections is gained through specialized methods of the IInTrustRepository interface (such as CustomAttributes and ForwardingProperties), which filter the available properties by purpose.
IRepositoryRecordInserter Provides write access to the repository that it is associated with and manages one or more IRepositoryRecordInserterLight interfaces, which do the actual writing.
IRepositoryRecordInserterLight Generates valid record structures from predefined and significant values and writes them to the repository.

 

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating