Create Report


Adaxes allows you to create reports for various purposes, such as monitoring your Active Directory environment, performing bulk operations, audit and so on. With the help of reports, it is possible to present Active Directory objects grouped together based on various criteria, such as their location in AD, property values, or group membership. In addition to Active Directory data, reports can include and be based upon information from other sources, including Adaxes logs and approval requests, Exchange, external database, HR system, etc.

In this tutorial, you will learn how to create reports in Adaxes.


  1. Launch Adaxes Administration Console, expand your Adaxes service, then expand Reports and All Reports. Right-click a container under which you want to create a report, point to New and click Report. The Create Report wizard will open.

  2. Report Name and Type

    On the 1st wizard step, enter a name and an optional description for the new report. Also, you need to specify how the new report will be generated.

    A report can be generated based on:

    • Active Directory search

      Reports of this type are generated by performing an LDAP search in Active Directory. The criteria to include objects in such a report are specified using an LDAP filter. In addition to that, when certain criteria cannot be specified via an LDAP filter, it is also possible to use conditions. For example, with the help of conditions, you can include or exclude inactive user accounts from your report.

    • Script

      Using this option, you can create reports on the basis of a PowerShell script. It allows you to specify more sophisticated criteria for including objects and even create reports without any common criteria at all. Apart from that, objects can be included in the report based on information that cannot be obtained from Active Directory. For example, information from an HR database can be used for this purpose. In addition to AD objects, such reports can include Adaxes log records, approval requests, and custom objects (for example, file shares, permissions, database records, etc).

    • Existing report with specific parameters

      With this report type, you can create new reports on the basis of existing ones, at the same time redefining certain report settings. You can override the scope, chart, columns, parameter values, report categories and related reports.

    When done, click Next.

  3. Scope

    On this wizard page, you need to specify options for selecting a report scope. A scope defines which Active Directory objects are included in the report.

    For reports based on an LDAP search, a scope specifies where in Active Directory to perform a search. Reports based on PowerShell scripts can be created without a scope. In this case, you can click Next to skip the step.

    A scope can include objects located in a particular Organizational Unit, subordinates of a certain manager, members of an AD group, etc. A report can have more than one scope. In this case, they will appear as a drop-down list when generating the report, so users can select the necessary one.

    To add a new scope, click New and follow the instructions of the New Scope Item wizard.

    • Select what type of scope you want to add and click Next.
    • In the Title field, specify a title under which the scope appears when selected.
    • In the Drop-down item text field, specify a caption under which the scope will appear in the list of available scopes. Click Next.

    • Specify options for selecting the base object of the new scope.

    When done, click Next.

  4. Parameters

    On this step, you can add parameters to the new report. Parameters can be used to supply additional information that can be necessary to generate the report.


    Parameter Usage


    • LDAP Filters

      You can use parameters in LDAP filters. Example: (department=%param-Department%).

    • Conditions

      Parameters can also be used in conditions meant to include or exclude objects from a report. Examples:

      • If is a member of %param-Group%
      • If the 'My Checkbox' parameter equals 'Yes'
    • Scripts

      It is possible to use parameter values in scripts. For instance, you can set a script variable to a parameter value as follows: $var = "%param-MyParam%" or $var = $Context.GetParameterValue("param-MyParam").

    • Charts

      Parameters can be used to build charts. For example, you can use the following value generation template for an item in a bar or pie chart: Count of (Department=%param-Department%).

    To add a parameter, click New and follow the instructions of the New Parameter wizard.

    When done, click Next.

  5. Columns

    On this step, you can specify the default columns for the report, as well as restrict which columns can be added. Also, you can set the default sorting and grouping options.

    Report-Specific Columns

    You can create columns that are specific to the new report only. Values in such columns are generated either using a template or with the help of a PowerShell script.

    1. Click the Add button in the Report-specific columns section. This will bring up the New Column wizard.

    2. Enter a display name for the new column.

    3. In the Data Type section, choose what kind of data the new column will contain.


      Click Next.


    4. Now, you need to specify how to generate values for the column.

      Template

      Using this option, you can generate column values based on properties of the objects included in the report. To include property values in the template, use value references (e.g. %department% or %title%). They will be replaced with corresponding property values of the object for which a column value is generated.

      Script

      Choose this option if you want to generate column values with the help of a PowerShell script.

      To assign a column value, you need to use a variable called Context. It is a predefined PowerShell variable of type ReportCustomColumnScriptContext. Use the Value property of the variable to set the column value.

      $Context.Value = "My value"


      Getting information about the report item which a column value is generated for

      To get information about the AD object which a column value is generated for, use the GetADObject method. The object returned by the method supports the IADs interface.

      Example: Setting column value to the UPN suffix of a user.

      # Get AD object
      $user = $Context.GetADObject()
      
      # Get property value
      $upn = $user.Get("userPrincipalName")
      
      # Set column value
      $upnSuffix = $upn.Substring($upn.LastIndexOf("@") + 1)
      $Context.Value = $upnSuffix


      In addition to that, you can access information on the report item using the $Context.ReportItem property. It supports the IAdmListItem interface. If the object represented by the item is a log record or a custom object, the property also supports the IAdmListItemLogRecord or IAdmListItemCustom interfaces respectively.

      $Context.Value = $Context.ReportItem.LogRecord.StartTime


      Getting information about the user which the report is generated for

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

      if (-not($Context.Initiator.Username.Contains("admin")))
      {
          $Context.Value = "Not allowed to view"
      }


      You can also use value references (e.g. %department% or %title%) to get property values of the user account.

      $recipientInfo = "%fullname%, %title% at %department%"


      Improving performance

      The script is executed for batches of objects rather than one at a time. For better performance, you can share information among iterations of the script within a batch. In the following example, a value requested from a web service is shared.

      if ($myvalue -eq $NULL) # check whether value has already been requested
      {
          # Get value from web service 
          $service = New-WebServiceProxy `
              -uri "http://www.company.com/Service.asmx?WSDL"
          $fileServer = $service.RequestSomething("My Argument")
      }
      
      # Get user
      $user = $Context.GetADObject()
      
      # Get username
      $username = $user.Get("sAMAccountName")
      
      # Set column value
      $Context.Value = "Personal Share: \\$fileServer\Shares\$username"


      If the report is generated with the help of a script, you can also optimize the performance by setting column values in the script used for report generation. This approach allows you to generate column values more efficiently.

      If you want to use the approach, select the Template option and assign an initial value to the column. For example, if it is a text column, the initial value can be (empty).
      For information on how to set column values in the script used for report generation, see Setting values of report-specific columns.
    5. When done, click Finish.

    Click Next.

  6. Depending on the report type, on this wizard page you need to specify either search criteria or a PowerShell script that will be used to generate the report.

    Search Options

    If the new report is generated on the basis of an Active Directory search, now, on the Search Options page, you need to specify the LDAP filter and optional conditions that will be used to include or exclude AD objects from the report.

    Search Filter

    In this field, specify an LDAP search filter that will be used to include objects in the report.

    To build a filter using a visual editor, click the associated Edit button.

    You can use value references in the LDAP filter. With their help, you can create a filter that depends on the user for which the report is generated. For example, if you specify the following filter: (&(objectCategory=user)(department=%department%)), the report will include users whose department is the same as the department of the user.

    Similarly, you can use value references to include parameters in LDAP filters. For example, if you specify the following filter: (&(objectCategory=user)(company=%param-ParamCompany%)), the report will include users whose company is specified by parameter ParamCompany.

    Conditions

    Conditions allow you to specify additional criteria for including or excluding objects from the report. To add a condition, click the Add Condition link.

    Using conditions is expensive with regard to performance, as each object is evaluated against conditions separately. Try to avoid using conditions where possible and specify as many criteria as possible with the help of the LDAP filter.

    By default, objects that meet conditions are excluded from the report. You can change the behavior to include only objects that match the conditions. To do so, click Exclude.

    You can use value references in conditions. With their help, you can create a condition that depends on the user which the report is generated for. For example, using the following condition: If located under %adm-ParentDN% you can exclude or include AD objects located in the same Organizational Unit as the user.

    Similarly, you can use value references to include parameters in conditions. For example, using the following condition: If is a member of %param-ParamGroup%, you can include or exclude members of a group specified by parameter ParamGroup.

    If you want the report to include deleted objects, enable the Search in Deleted Objects option.

    Script

    On the Script page, you need to create a script for report generation.

    To add items to the report, use the $Context.Items.Add method. The following examples demonstrate 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 include results of an AD search in the report. The first option is to pass specific search results 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 pass all search results at once. To do this, pass the $Context.DirectorySearcher property.

      $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)

    • 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)
      }

    • 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)
      

      For information on how to get indexes of available icons, see View List of Icons and Icon Indexes.
    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 how the value will be used. If you set it to $True, the parameter value will be returned in a format suitable for using in LDAP filters. If you set the argument to $False, the method returns the parameter value as is.

    $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"
    

    You can also get parameter values with the help of value references.

    $department = "%param-ParamDepartment%"



    Getting information about the user which report is generated for

    In your script, you can use information about the user which the report is generated for. For this purpose, use the $Context.Initiator property.

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

    To get property values of the initiator's user account, you can also use value references (e.g. %department% or %title%).

    $parentDn = "%adm-ParentDN%"



    Modifying search parameters

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


    Example 1: Modifying the search filter.

    # 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))")
    
    # Add all search results to report
    $Context.Items.Add($Context.DirectorySearcher)


    Example 2: Adding 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"))
    
    # Add all search results to report
    $Context.Items.Add($Context.DirectorySearcher)



    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 of report-specific columns

    If the report contains report-specific columns, you can also assign values to them. To set a value for a column, first you need to get the column ID. For this purpose, on the Columns step of the wizard, right-click the column and select Copy > Column ID. The ID will be copied to the clipboard.

    Then, for each object, you need to create a hash table that maps a column ID to the column value. When adding the object to the report, pass the hash table to the $Context.Items.Add method.

    $columnID = "{8421e8e1-65b2-4190-9f24-93a264c6c9ba}" # TODO replace with the ID of
                                                         # the 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)

    When done, click Next.

  7. Chart

    On this step, you can add a chart to the new report. A chart can be used to represent the report data visually. To add a chart, select the Enable chart option.

    You can add charts of the following types:

    Bar and Pie Charts

    When adding bar and pie charts to the report, you need to specify how to calculate the size of each bar or slice. The size is calculated on the basis of column values. For example, you can add an item that displays the number of times a certain value occurs in a specific column, e.g. Count of (Department=Sales).

    Using value references

    You can use value references in charts (e.g. %datetime%, %department%, %company%). With their help, you can create chart items that depend on the user for which the report is generated. For example, the following item will display the number of users in the same company as the user: Count of (Company=%company%).

    Similarly, you can use value references to create items based on parameters. For example, the following item will display the number of users in the department specified by parameter ParamDepartment: Count of (Department=%param-ParamDepartment%).


    Using report-specific columns

    Chart items can be based on report-specific columns. Such columns can be generated with the help of a script, which gives you more possibilities when generating chart items.

    Top Records Chart

    This type of chart allows displaying a certain number of items sorted by a specific column. For example, a chart can display top ten Organizational Units with the biggest number of objects in them.

    Using a report-specific column

    You can create the chart on the basis of a report-specific column. Such columns can be generated with the help of a script, which gives you more possibilities when generating a chart.

    Total Count Chart

    This chart displays the total number of items in the report. It does not have any parameters.


    When done, click Next.

  8. Miscellaneous

    Categories

    On the final step, you need to specify categories for the new report. Categories are used to distribute permissions to view reports. Only users who have the permissions for a category a report belongs to will be able to view it.

    To specify a report category, select it in the categories list. To create a new category, click the Manage categories link.

    For information on how to grant permissions to view reports belonging to a specific category, see Grant Rights to View Reports.

    Related Reports

    If there are any reports related to the new one, you can add them to the Related Reports section. This will make such reports easily accessible to users. For example, when working with a report in the Web Interface, a list of related reports will appear at the bottom of the left pane.

    To add a related report, click Add.

    When done, click Finish.

Open tutorial filtering

Got questions?
Support Forum