Generating reports

To generate a report, you need to bind to it, specify arguments for the report generation (e.g. scope, parameter values) and then call the Generate method of the IAdmReport interface. Below is a basic example for generating a report.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Generate
$listItems = $report.Generate($arguments)

Specifying a scope for report generation

To specify the scope of objects to be included in a report, use the Scope property of the IAdmReportArguments interface. The scope will require a base object (e.g. domain, organizational unit). To specify the object, use the BaseObjects property of the IAdmReportScope interface.

The below code sample generates a report with scope set to all managed domains (Everywhere).

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation.
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Scope
$scope = $configuration.CreateScope("ADM_REPORTSCOPETYPE_LOCATION")
$baseObject = $scope.CreateBaseObject()
$baseObject.ObjectReference = $null # Everywhere
$scope.BaseObjects = @($baseObject)
$arguments.Scope = $scope

# Generate
$listItems = $report.Generate($arguments)

Using a predefined scope

To generate a report, you can use one of the scopes predefined for it. To obtain predefined report scopes, use the Scopes property of the IAdmReportGenerator interface.

To use a predefined scope for report generation, you will need to specify a base object for the scope. It can be one of the the base objects predefined for the scope. To obtain the predefined base objects, use the PredefinedBaseObjects property of the IAdmReportScope interface.

The below code sample generates a report using the first scope predefined for it and the first base object predefined for the scope.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Predefined scope
$generator = $configuration.Generator
$predefinedScope = $generator.Scopes[0]

# Predefined base object
$predefinedBaseObject = $predefinedScope.PredefinedBaseObjects[0]
$predefinedScope.BaseObjects = @($predefinedBaseObject)

$arguments.Scope = $predefinedScope

# Generate
$listItems = $report.Generate($arguments)

Using a specific scope

In some cases, you might want to generate a report for a specific scope that is not predefined for the report. It can be done by creating a scope specifically for the report generation. To create a scope, retrieve report configuration and call the CreateScope method of the IAdmReportConfiguration interface.

To use the scope for report generation, you will need to create a base object for it. That can be done using the CreateBaseObject method of the IAdmReportScope interface.

The following code sample creates a scope set to members of the Sales group and generates a report for it.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"
$groupDN = "CN=Sales,OU=Groups,DC=company,DC=com"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Create scope.
$scope = $configuration.CreateScope("ADM_REPORTSCOPETYPE_GROUPMEMBERS")

# Create base object
$baseObject = $scope.CreateBaseObject()
$objReference = New-Object "Softerra.Adaxes.Adsi.AdmObjectReference"
$objReference.ObjectDN = $groupDN
$baseObject.ObjectReference = $objReference
$scope.BaseObjects = @($baseObject)

$arguments.Scope = $scope

# Generate
$listItems = $report.Generate($arguments)

Specifying parameter values for report generation

To specify parameter values for report generation, use the SetParameterValue method of the IAdmReportArguments interface. The following code samples generate reports with different types of parameters.

Text and checkbox parameters 

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Parameter values
$arguments.SetParameterValue("param-textParameter", "MyValue")
$arguments.SetParameterValue("param-checkboxParameter", 1)

# Generate
$listItems = $report.Generate($arguments)

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Parameter value
$itemId = "ADAXESVALUEID:{db2744b0-ace2-4022-bfc2-53de5ec5f7c6}"
$arguments.SetParameterValue("param-dropDownListParameter", $itemId)

# Generate
$listItems = $report.Generate($arguments)

In the above code sample, the $itemId variable represents the identifier of an item in the drop-down list. For information on how to get the identifier, see View information on report parameters.

Checkbox list parameter 

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Checked parameter items
$itemOneId = "ADAXESPARAMID:{96f07f9e-092b-4f8a-803c-e7f03601740b}"
$itemTwoId = "ADAXESPARAMID:{5ef7b316-7b56-4063-96bb-b235609ad8e5}"
$checkedItemIds = [String[]]@($itemOneId, $itemTwoId)
$arguments.SetParameterValue("param-checkboxListParameter", $checkedItemIds)

# Generate
$listItems = $report.Generate($arguments)

In the above code sample, the $itemOneId and $itemTwoId variables represent identifiers of checkboxes in the list. For information on how to get the identifiers, see View information on report parameters.

 View information on report parameters {id=viewReportParameters}

The following code sample outputs the names, types, and identifiers of all report parameters. For the drop-down list and checkbox list parameters the script also outputs display names and identifiers of the parameter items.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

# Retrieve report configuration.
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)
$configuration = $report.GetConfiguration()

# Output report parameters.
foreach ($parameter in $configuration.Parameters)
{
    Write-Host "`nParameter name:" $parameter.DisplayName
    Write-Host "Identifier:" $parameter.Id
    Write-Host "Type:" $parameter.Type

    # Check box list.
    if ($parameter.Type -eq "ADM_PARAMETERTYPE_CHECKLIST") 
    {
        Write-Host "Checkbox items:"

        # Get each checkbox item identifier.
        foreach ($checkbox in $parameter.Items)
        {
            Write-Host "`n`tDisplay name:" $checkbox.DisplayName
            Write-Host "`tIdentifier:" $checkbox.Id
        }
    }
    # Drop-down list.
    if ($parameter.Type -eq "ADM_PARAMETERTYPE_LIST") 
    {
        Write-Host "Drop-down list items:"

        # Get each drop-down list value identifier.
        foreach ($listItem in $parameter.Values)
        {
            Write-Host "`n`tDisplay name:" $listItem.DisplayName
            Write-Host "`tValue:" $listItem.Value
            Write-Host "`tIdentifier:" $listItem.ID
        }
    }
}

Specifying columns for report generation

To specify the columns to be present in a report, use the Columns property of the IAdmReportArguments interface. You can generate a report with its default columns or explicitly specify the columns you need.

Using default report columns

To obtain the default columns of a report, use the Columns property of the IAdmReportGenerator interface.

The following code sample generates a report with its default columns.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()

# Default columns
$reportGenerator = $configuration.Generator
$defaultReportColumns = $reportGenerator.Columns.Columns
$arguments.Columns = $defaultReportColumns

# Generate
$listItems = $report.Generate($arguments)

Specifying columns explicitly

In some cases, you might want to explicitly specify the columns to be present in a report. To identify a column that represents a directory property, use the property name (e.g. description). Custom columns should be represented by the IAdmReportCustomColumn interface.

 Obtain interface representing a custom column

To obtain the IAdmReportCustomColumn interface representing a specific report custom column:

  1. Get the identifier of the custom column. For details, see View information on report custom columns.
  2. Call the GetColumnByIdentifier method of the IAdmReportColumns interface. Pass the custom column identifier as the method parameter.

The below code sample generates a report with the following columns: name, description and a custom column with the specified identifier.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"
$customColumnId = "{095d2acd-6850-4c49-97f4-435441c3eea5}"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Get custom column.
$configuration = $report.GetConfiguration()
$customColumn = $configuration.Columns.GetColumnByIdentifier($customColumnId)

# Arguments for report generation.
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = @("name", "description", $customColumn)

# Generate
$listItems = $report.Generate($arguments)
 View information on report custom columns {id=viewReportCustomColumns}

The following code sample displays names and identifiers of all custom columns of a report.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Output custom column display names and identifiers.
$configuration = $report.GetConfiguration()
$customColumns = $configuration.Columns.CustomColumns

foreach ($customColumn in $customColumns)
{
    Write-Host $customColumn.DisplayName
    Write-Host $customColumn.ID
    Write-Host
}

Specifying a user to generate a report for

To generate a report for a specific user account use the Recipient property of the IAdmReportArguments interface. If the property is not specified, a report is generated for the account whose credentials were used to bind to the report.

The below code sample generates a report for user James Smith.

[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportDN = "CN=My Report,CN=Reports,CN=Reports Root,CN=Configuration Objects," +
    "CN=Adaxes Configuration,CN=Adaxes"
$recipientDN = "CN=James Smith,OU=Users,DC=company,DC=com"

# Bind to the report.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)
$report = $service.OpenObject("Adaxes://$reportDN", $null, $null, 0)

# Arguments for report generation
$configuration = $report.GetConfiguration()
$arguments = $configuration.CreateReportArguments()
$arguments.Columns = $configuration.Generator.Columns.Columns

# Recipient
$recipient = $service.OpenObject("Adaxes://$recipientDN", $null, $null, 0)
$arguments.Recipient = $recipient

# Generate
$listItems = $report.Generate($arguments)

To bind to reports, the above code samples use the distinguished names (DNs) of the reports. However, report DNs can change (e.g. when a report is renamed or moved to another container). As an alternative, you can bind to a report using its identifier that is immutable. For information on how to get the identifier, see Get identifier of Adaxes configuration object.

 How
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

$serviceHost = "localhost"
$reportId = "b662f6a9-581a-4315-b8b2-4aa9a2d7bdd5"

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly($serviceHost)

try
{
    # Bind to the 'Reports' container.
    $reportsPath = $service.Backend.GetConfigurationContainerPath("Reports")
    $searcher = $service.OpenObject($reportsPath, $null, $null, 0)
    
    # Search report by identifier.
    $searcher.Criteria = New-AdmCriteria "adm-Report" {adm-ObjectId -eq $reportId}
    $searcher.SearchScope = "ADS_SCOPE_SUBTREE"

    # Execute search.
    $searchResultIterator = $searcher.ExecuteSearch()
    $searchResults = $searchResultIterator.FetchAll()

    if ($searchResults.Length -eq 0)
    {
        Write-Warning "Report with ID $reportId not found."
        return
    }
    else
    {
        # Bind to the report.
        $reportPath = $searchResults[0].AdsPath
        $report = $service.OpenObject($reportPath, $null, $null, 0)
    }
}
finally
{
    # Release resources.
    if ($searchResultIterator){ $searchResultIterator.Dispose() }
}

Outputting report items

The below code sample fetches all report items and outputs their names.

# The $report variable represents a report.
# The $arguments variable represents arguments for report generation.

# Generate
$listItems = $report.Generate($arguments)

while ($true)
{
    # Get report item IDs.
    $listItemsIds = $listItems.GetNextIDs(10)

    # Check if generation is completed.
    if ($listItemsIds -eq $null)
    {
        break
    }

    # Wait if items not fetched.
    if ($listItemsIds.Length -eq 0)
    {
        Sleep -Milliseconds 100
        continue
    }
    
    # Output item names.
    $columnValues = $listItems.GetColumnValues($listItemsIds, $arguments.Columns)

    foreach ($columnValue in $columnValues)
    {
        Write-Host "Name:" $columnValue.GetPropertyByName("name").Value
    }
}

See also

Specify a scope Specify parameter values Specify columns Generate for specific user Output items
© Softerra 2022. All rights reserved.
Send feedback