Creating scripts for report generation

This article describes how to create PowerShell scripts for reports generation in Adaxes.

Adding items to report

To add items to the report, use the $Context.Items.Add method. The following code samples show how to add items of different types:

Directory objects

$johnDoe = $Context.BindToObjectByDN("CN=John Doe,CN=Users,DC=company,DC=com")
$Context.Items.Add($johnDoe)

Search results

There are two ways how you can add results of a directory search to a report. The first option is to pass a specific search result to the Add method.

try
{
    $searchIterator = $Context.DirectorySearcher.ExecuteSearch()
    while ($Context.MoveNext($searchIterator))
    {
        $searchResult = $searchIterator.Current
        $Context.Items.Add($searchResult)
    }
}
finally
{
    if ($searchIterator) { $searchIterator.Dispose() }
}

Alternatively, you can add all search results to the report at once. To do this, pass the $Context.DirectorySearcher property to the Add method.

$Context.Items.Add($Context.DirectorySearcher)

Log records

$serviceLogPath = $Context.GetWellKnownContainerPath("ServiceLog")
$serviceLog = $Context.BindToObject($serviceLogPath)
$log = $serviceLog.GeneralLog.Log

$records = $log.GetPage(0)
$record = $records.GetObject(0)
$Context.Items.Add($record)

For information on how to get log records using scripts, see Accessing log records.

Approval requests

# Get pending approval requests
$containerPath = $Context.GetWellKnownContainerPath("ApprovalRequests")
$container = $Context.BindToObject($containerPath)
$requests = $container.GetApprovalRequests("ADM_APPROVALSTATE_PENDING")

foreach ($requestID in $requests)
{
    # Bind to request
    $guid = New-Object "System.Guid" (,$requestID)
    $guid = $guid.ToString("B")
    $request = $Context.BindToObject("Adaxes://<GUID=$guid>")

    # Add request to report
    $Context.Items.Add($request)
}

For information on how to get Approval Requests using scripts, see Managing approval requests.

Custom objects

To add a custom object, you need to pass the index of an icon to use with the object, object name, display type, and also a hash table with column values.

$columnValues = @{ }
$columnValues.Add("company", "Acme")
$columnValues.Add("department", "Sales")
$Context.Items.Add(1, "My Item", "My Type", $columnValues)

$iconsCount = 100
for ($i = 0; $i -lt $iconsCount; $i++)
{
    $Context.Items.Add($i, "Icon index $i", "Icon")
}

Getting parameter values

To get values of report parameters, you can use value references.

$department = "%param-ParamDepartment%"

Alternatively, use the $Context.GetParameterValue method. The method argument specifies the name of the report parameter whose value to obtain.

$date = $Context.GetParameterValue("param-ParamDate")
# The $date variable is set to "05/03/2022 12:24:00 PM"

If you need to use the report parameter value in an LDAP filter, set the optional second argument of the $Context.GetParameterValue method to $true. The value will be converted into a suitable format.

$date = $Context.GetParameterValue("param-ParamDate", $true)
# The $date variable is set to "20220503122400.0Z"

It is also possible to get the parameter value without converting it to string, using the GetParameterValueAsIs method.

$date = $Context.ReportArguments.GetParameterValueAsIs("param-ParamDate")
# The $date variable is set to a System.DateTime object

Getting information about report recipient

To get information about the user for which the report is generated, use the $Context.Initiator
property.

$recipientDepartment = $Context.Initiator.UserAdsObject.Get("department")

Alternatively, you can use value references (e.g. %department% or %title%).

$recipientDepartment = "%department%"

Modifying search parameters

You can modify various parameters of the search. To do so, use methods and properties provided by the $Context.DirectorySearcher property.

The following code sample modifies the search criteria based on a report parameter value, using the DirectorySearcher.AddCriteria method. For more details about building criteria, see How to build criteria.

# Modify search criteria

# WARNING: Replacing the criteria entirely will break the report.
# You need to merge the existing criteria with your criteria.

$department = $Context.GetParameterValue("param-ParamDepartment") 
$criteriaToAdd = New-AdmCriteria "user" {department -eq $department}
$Context.DirectorySearcher.AddCriteria($criteriaToAdd)

The following code sample adds properties to load during the search.

# Load the Department and Company properties during search

# WARNING: Replacing all properties to load is not recommended.
# Instead, you need to add the necessary properties.

$Context.DirectorySearcher.SearchParameters.PropertiesToLoad.AddRange(@("department", "company"))

Changing item color and font style

You can highlight items in the report with color and font style. To do so, create an item style with the help of the $Context.Items.CreateItemStyle method and pass it to the $Context.Items.Add method as the last parameter.

# Add first item

$textColor1 = "red"
$backgroundColor1 = $null # default
$fontStyle1 = "ADM_LISTITEMFONTSTYLE_BOLD" # bold
$style1 = $Context.Items.CreateItemStyle($textColor1, $backgroundColor1, $fontStyle1)
$reportItem1 = $Context.BindToObjectByDN("CN=John Doe,OU=People,DC=company,DC=com")
$Context.Items.Add($reportItem1, $style1)

# Add second item

$textColor2 = "#FFFFFF" # white
$backgroundColor2 = "16776960" # yellow
$fontStyle2 = "ADM_LISTITEMFONTSTYLE_BOLD",
              "ADM_LISTITEMFONTSTYLE_ITALIC" # bold + italic
$style2 = $Context.Items.CreateItemStyle($textColor2, $backgroundColor2, $fontStyle2)
$reportItem2 = $Context.BindToObjectByDN("%manager%")
$Context.Items.Add($reportItem2, $style2)

Setting values for custom columns

If the report contains custom columns, you can improve performance by setting values for them in the script that generates the report. To use this approach, select the Template option for custom columns generation and assign initial column values (e.g. (empty) for a text column).

To set a value for a custom column, you need to create a hash table that maps column identifier to column value, and pass the table to the $Context.Items.Add method.

$columnID = "{8421e8e1-65b2-4190-9f24-93a264c6c9ba}" # TODO replace with the identifier of
                                                     # the custom column you need

# Create hash table and specify column value
$columnValues = @{ }
$columnValues.Add($columnID, "My Value")

# Add item to report 
$item = $Context.BindToObjectByDN("CN=John Doe,CN=Users,DC=company,DC=com") 
$Context.Items.Add($item, $columnValues)

See also

• Creating scripts for custom column generation
• GenerateReportScriptContext