Skip to content

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:

Active 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 an AD 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)
How to obtain a list of icons and corresponding icon indexes

Create a report generated by the following PowerShell script:

$iconCount = 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, use the $Context.GetParameterValue method. The first argument of the method specifies the parameter name. The second argument specifies whether to convert the parameter value into a format required for LDAP filters. If the parameter is set to TRUE, the method escapes necessary characters in the parameter value (e.g. for “John*” the method will return “John\2A”) or converts a date into the format required for LDAP filters (e.g. “20180122151647.0Z”).

$date = $Context.GetParameterValue("param-ParamDate", $False)
# The $date variable is set to "10/25/2017 7:33:18 PM"

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

Alternatively, you can get parameter values using value references.

 $department = "%param-ParamDepartment%"

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 LDAP search filter based on a report parameter value.

# Modify search filter 

# WARNING: Replacing the search filter completely is not allowed. 
# You need to append filter parts instead. 

$department = $Context.GetParameterValue("param-ParamDepartment", $True) 
$Context.DirectorySearcher.AppendFilter("(&(department=$department))")

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.

How to get the identifier of a custom column
  1. Launch Adaxes Administration Console.

  2. Navigate to Reports / All Reports.

  3. Right-click a report and click Edit in the context menu.

  4. Activate the Columns tab.

  5. Right-click the column in the Report-specific columns list.

  6. In the context menu, point to Copy and click Column ID.

    Tip

    The custom column identifier will be copied to the clipboard.

$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