GenerateReportScriptContext

The GenerateReportScriptContext class provides methods and properties for PowerShell scripts used to generate reports. To access an instance of this class, use a predefined PowerShell variable called $Context.

Inheritance: Object

Methods

Properties

Details

GetParameterValue(string)

Returns the value of the given report parameter.

string GetParameterValue(string paramName)

Examples

The following code sample creates a visual style if a report parameter value is 1.

# Get parameter value
$value = $Context.GetParameterValue("param-MyParameter")

if ($value -eq "1")
{
    # Create visual style
    $highlightStyle = $Context.Items.CreateItemStyle("red", "yellow", "ADM_LISTITEMFONTSTYLE_BOLD")
}

---

GetParameterValue(string, bool)

Returns the value of the given report parameter. The method allows you to specify whether to convert the parameter value into a format required for LDAP filters.

string GetParameterValue(string paramName, bool valueForLdapFilter)

Parameters

• paramName - Specifies the name of the report parameter.
• valueForLdapFilter - If 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").

Examples

The following code sample modifies the LDAP search filter based on a report parameter value.

# Get parameter value
$department = $Context.GetParameterValue("param-ParamDepartment", $true) 

# Append search filter
$Context.DirectorySearcher.AppendFilter("(&(department=$department))")

---

IsAccountDisabled()

Returns a value indicating whether the given search result represents a disabled account.

bool IsAccountDisabled(IAdmSearchResult searchResult)

Remarks

To use this method the search result must contain the userAccountControl property

---

IsAccountExpired()

Returns a value indicating whether the given search result represents an expired account.

bool IsAccountExpired(IAdmSearchResult searchResult)

Remarks

To use this method the search result must contain the accountExpires property

---

IsSecurityGroup()

Returns a value indicating whether the specified object is a security group.

bool IsSecurityGroup(object obj)

Parameters

The obj parameter can be a search result represented by the IAdmSearchResult interface, or a directory object represented by the IAdmTop interface.

---

IsSearchResultProtectedFromDeletion()

Returns a value indicating whether the object represented by the given search result is protected from accidental deletion.

bool IsSearchResultProtectedFromDeletion(IAdmSearchResult searchResult, 
                                         object parentSecurityDescriptor)

Parameters

• searchResult - Specifies the search result.
• parentSecurityDescriptor - Specifies the security descriptor of the container where the object represented by the given search result is located. The security descriptor must contain the discretionary access-control list (DACL) part. The DACL part is included by default when you get the ntSecurityDescriptor property of an object.

Remarks

To use this method the search result must include the security descriptor that contains the discretionary access-control list (DACL) part. By default, the DACL part is included when you add the ntSecurityDescriptor property to the list of properties to be fetched during a directory search.

Examples

The following code sample adds users protected from accidental deletion to a report.

$Context.DirectorySearcher.SetPropertiesToLoad.Add(@("ntSecurityDescriptor"))

try
{
    $searchIterator = $Context.DirectorySearcher.ExecuteSearch()
    while ($Context.MoveNext($searchIterator))
    {
        $searchResult = $searchIterator.Current
        
        # Bind to parent
        $dn = New-Object "Softerra.Adaxes.Ldap.DN" $searchResult.AdsPath.DN
        $parent = $Context.BindToObjectByDN($dn.Parent)
        
        # Get parent security descriptor
        $parentSecurityDescriptor = $parent.Get("ntSecurityDescriptor")
        
        if ($Context.IsSearchResultProtectedFromDeletion($searchResult, $parentSecurityDescriptor))
        {
            # Add search result to report
            $Context.Items.Add($searchResult)
        }
    }
}
finally
{
    # Release resources
    if ($searchIterator) { $searchIterator.Dispose() }
}

---

MoveNext()

Advances the given search iterator to the next element in the search results.

bool MoveNext(IAdmSearchResultIterator iterator)

Return Value

The method returns $true if the iterator successfully moved and $false if the search is completed or aborted.

Remarks

Use this method instead of IAdmSearchResultIterator::MoveNext to iterate through search results in scripts used for report generation.

Examples

The following code sample adds search results to a report.

try
{
    # Execute search
    $searchIterator = $Context.DirectorySearcher.ExecuteSearch()
    while ($Context.MoveNext($searchIterator))
    {
        # Add search result to report
        $searchResult = $searchIterator.Current
        $Context.Items.Add($searchResult)        
    }
}
finally
{
    # Release resources
    if ($searchIterator) { $searchIterator.Dispose() }
}

---

IsProtectedFromDeletion()

Returns a value indicating whether the object with the given security descriptor is protected from accidental deletion.

bool IsProtectedFromDeletion(object securityDescriptor, 
                             object parentSecurityDescriptor)

Parameters

• securityDescriptor - Specifies the security descriptor of the object. The security descriptor must contain the discretionary access-control list (DACL) part. The DACL part is included by default when you get the ntSecurityDescriptor property of an object.
• parentSecurityDescriptor - Specifies the security descriptor of the object parent. The security descriptor must contain the discretionary access-control list (DACL) part. The DACL part is included by default when you get the ntSecurityDescriptor property of an object.

Examples

The following code sample checks whether a user is protected from accidental deletion.

$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"

# Bind to user
$user = $Context.BindToObjectByDN($userDN)

# Get only the DACL part of the user security descriptor
$user.SetOption("ADS_OPTION_SECURITY_MASK", 4) # ADS_SECURITY_INFO_DACL
$userSecurityDescriptor = $user.Get("ntSecurityDescriptor")
    
# Bind to user parent
$parent = $Context.BindToObject($user.Parent)

# Get only the DACL part of the user parent security descriptor
$parent.SetOption("ADS_OPTION_SECURITY_MASK", 4) # ADS_SECURITY_INFO_DACL
$parentSecurityDescriptor = $parent.Get("ntSecurityDescriptor")

# Check whether the user is protected from accidental deletion
$protected = $Context.IsProtectedFromDeletion($userSecurityDescriptor, $parentSecurityDescriptor)

---

GetHostNameFromNetworkPath()

Returns the host name from the given network path.

string GetHostNameFromNetworkPath(string networkPath)

Examples

The following code sample gets the host name from the home directory of a user.

$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"

# Bind to user
$user = $Context.BindToObjectByDN($userDN)

# Get host name from the home directory
$homeDirectory = $user.Get("homeDirectory")
$hostName = $Context.GetHostNameFromNetworkPath($homeDirectory)

---

CreatePropertyValueComparer()

Returns an instance of the IEqualityComparer that can be used to compare values of the given property.

IEqualityComparer CreatePropertyValueComparer(string propertyName)

---

GetPropertyValueDisplayText()

Returns the value of the given directory object property in a human-readable format.

string GetPropertyValueDisplayText(string propertyName, object value)

Parameters

• propertyName - Specifies the name of the directory object property.
• value - Specifies the property value.

Examples

The following code sample adds a user to a report and specified information about account expiration in the Description column.

$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"

# Bind to user
$user = $Context.BindToObjectByDN($userDN)
    
# Get display text for the Account Expires property
$accountExpires = $user.Get("accountExpires")
$accountExpiresDisplayText = $Context.GetPropertyValueDisplayText("accountExpires", $accountExpires)

# Add user to report
$Context.Items.Add($user, @{ "description"="Account expiration date: $accountExpiresDisplayText" })

---

LogMessage()

Adds a message of the given type to the report Generation Log.

void LogMessage(string message, ExecuteScriptLogMessageType messageType)

Parameters

• message - Specifies the message text.
• messageType - Specifies the message type.

Examples

The following code sample adds messages of different types to the report Generation Log.

$Context.LogMessage("My Message", "Information")
$Context.LogMessage("My Warning", "Warning")
$Context.LogMessage("My Error Message", "Error")

---

LogException()

Adds the given exception to the report Generation Log.

void LogException(Exception exception)

Remarks

The method is supported starting with Adaxes version 2019.1 Update 3.

Examples

try
{
    ...
}
catch
{
    $Context.LogException($_.Exception)
}

---

BindToObject()

Binds to a directory object by the given ADS path.

IAdmTop BindToObject(string adsPath)

Parameters

The adsPath parameter specifies the ADS path of the directory object to bind to

---

BindToObjectEx()

Binds to a directory object by the given ADS path. This method extends the BindToObject method with the ability to specify whether to perform all actions on the object directly or pass it through Adaxes pipeline. When passed through the pipeline, Adaxes functionality is applied (e.g. security roles).

IAdmTop BindToObjectEx(string adsPath, bool pipelined)

Parameters

• adsPath - Specifies the ADS path of the directory object to bind to.
• pipelined - Set to $false to perform all actions on the object directly. Set to $true to apply Adaxes functionality.

---

BindToObjectByDN()

Binds to a directory object by the given distinguished name (DN).

IAdmTop BindToObjectByDN(string dn)

Parameters

The dn parameter specifies the distinguished name (DN) of the directory object to bind to.

---

BindToObjectByDNEx()

Binds to a directory object by the given distinguished name (DN). This method extends the BindToObjectByDN method with the ability to specify whether to perform all actions on the object directly or pass it through Adaxes pipeline. When passed through the pipeline, Adaxes functionality is applied (e.g. security roles).

IAdmTop BindToObjectByDNEx(string dn, bool pipelined)

Parameters

• dn - Specifies the distinguished name (DN) of the directory object to bind to.
• pipelined - Set to $false to perform all actions on the object directly. Set to $true to apply Adaxes functionality.

---

BindToObjectBySearchResult()

Binds to a directory object by the specified search result.

IAdmTop BindToObjectBySearchResult(IAdmSearchResult searchResult)

Parameters

The searchResult parameter specifies the search result entry that contains properties for binding to the object.

Remarks

To make binding less resource-intensive, it is recommended for the search result to contain the objectGuid and objectClass properties.

---

BindToObjectBySearchResultEx()

Binds to a directory object by the specified search result. This method extends the BindToObjectBySearchResult method with the ability to specify whether to perform all actions on the object directly or pass it through Adaxes pipeline. When passed through the pipeline, Adaxes functionality is applied (e.g. security roles).

IAdmTop BindToObjectBySearchResultEx(IAdmSearchResult searchResult, bool pipelined)

Parameters

• searchResult - Specifies the search result entry that contains properties for binding to the object.
• pipelined - Set to $false to perform all actions on the object directly. Set to $true to apply Adaxes functionality.

Remarks

To make binding less resource-intensive, it is recommended for the search result to contain the objectGuid and objectClass properties.

---

SendMail()

Sends an email to the specified recipient.

void SendMail(string toAddress, 
              string subject, 
              string textBody, 
              string htmlBody)

Parameters

• toAddress - Specifies the recipient's e-mail address.
• subject - Specifies the subject of the email.
• textBody - Specifies the body of the email in the plain text format. This parameter can be $null.
• htmlBody - Specifies the body of the email in the HTML format. This parameter can be $null.

Examples

The following code sample sends a plaintext email to multiple recipients.

$Context.SendMail("jdoe@company.com, jsmith@company.com", "My subject", "Email body", $null)

---

SendSms(string, string)

Sends an SMS message with the given text to the given phone number.

void SendSms(string mobileNumber, string smsText)

Parameters

• mobileNumber - Specifies the phone number of the recipient.
• smsText - Specifies the text of the SMS message to send.

---

SendSms(string, string, IAdmTop)

Sends an SMS message with the given text to the given phone number. This method allows you to specify the object used to resolve value references in the SMS settings.

void SendSms(string mobileNumber, 
             string smsText, 
             IAdmTop objectToResolveValueReferences)

Parameters

• mobileNumber - Specifies the phone number of the recipient.
• smsText - Specifies the text of the SMS message to send.
• objectToResolveValueReferences - Specifies the object used to resolve value references in the SMS settings.

---

GetObjectDomain()

Extracts the domain name from the passed distinguished name (DN).

string GetObjectDomain(string objectDN)

Parameters

The objectDN parameter specifies the distinguished name from which to extract the domain name.

---

GetDisplayNameFromAdsPath()

Builds a display name of a directory object from its ADS path.

string GetDisplayNameFromAdsPath(string adsPath, bool includePath)

Parameters

• adsPath - Specifies the ADS path of the directory object.
• includePath - If set to $true the return value will include the path to the directory object, e.g. John Smith (company.com\Users).

---

GetWellKnownContainerPath()

Returns the ADS path of a well-known container for Adaxes configuration objects. For a list of container aliases, see Aliases for containers that store Adaxes configuration objects.

string GetWellKnownContainerPath(string containerAlias)

Parameters

The containerAlias parameter specifies the alias of the well-known container.

---

GetDomainController()

Returns the DNS host name of the domain controller the Adaxes service is currently connected to.

string GetDomainController(string domain)

Parameters

The domain parameter specifies the domain for which to return the domain controller. You can use the fully qualified domain name (e.g. mydomain.com) or NETBIOS domain name (e.g. MYDOMAIN) in the parameter.

Remarks

The method is supported starting with Adaxes version 2019.1.

---

FetchAllPropertyValues()

Returns all values of the given property for the given directory object. The method overcomes the limit of maximum property values returned per request.

object[] FetchAllPropertyValues(IAdmTop obj, string propertyName)

Parameters

• obj - Specifies the directory object.
• propertyName - Specifies the name of the directory object property.

Examples

The following code sample adds subordinates of a user to a report.

$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"

# Bind to user
$user = $Context.BindToObjectByDN($userDN)

# Get DNs of user's subordinates
$subordinateDNs = $Context.FetchAllPropertyValues($user, "directReports")

foreach ($subordinateDN in $subordinateDNs)
{
    # Add subordinate to report
    $subordinate = $Context.BindToObjectByDN($subordinateDN)
    $Context.Items.Add($subordinate)
}

---

GetOffice365Credential()

The method is deprecated and should not be used. Use the ReportCloudServicesScriptContext::GetAzureAuthAccessToken method instead.

Returns credentials of the Microsoft 365 tenant associated with the given object.

PSCredential GetOffice365Credential(IAdmTop obj)

Return value

The method returns an instance of the PSCredential class. If there is no tenant associated with the object, the method returns $null.

---

IsApprovalRequiredException()

Returns $true if the given exception occurred because the operation requires approval.

bool IsApprovalRequiredException(Exception exception)

Remarks

The method is supported starting with Adaxes version 2019.1 Update 3.

Examples

try
{
    ...
}

catch
{
    if ($Context.IsApprovalRequiredException($_.Exception))
    {
        $Context.LogException($_.Exception)
    }
    else
    {
        throw
    }    
}

---

CreateGuidBasedSearcher()

Creates an instance of a directory searcher configured to search for objects with the given GUIDs. Each GUID must be represented as an array of 16 bytes (Byte[]).

DirectorySearcher CreateGuidBasedSearcher(IList<Object> objectGuids)

Parameters

The objectGuids parameter specifies a list of object GUIDs.

Examples

The following code sample adds direct members of a group to a report.

$groupDN = "CN=SalesGroup,CN=Groups,DC=domain,DC=com"

# Bind to group
$group = $Context.BindToObjectByDN($groupDN)

# Get GUIDs of direct group members
$memberGuidsBytes = $group.DirectMembers

# Create a directory searcher instance
$searcher = $Context.CreateGuidBasedSearcher($memberGuidsBytes)

# Add search results to report
$Context.Items.Add($searcher)

---

ReportArguments

Gets arguments for report generation.

---

Items

Gets a collection of report items.

---

DirectorySearcher

Gets an instance of a directory searcher configured to search for objects defined by the report scope.

---

Initiator

Gets an instance of the ExecuteScriptInitiatorInfo class that allows you to get information about the user for which the report is generated.

---

RunAs

Gets an instance of the NetworkCredential class that represents the credentials of the user account under which the script is executed. If the property is $null, the credentials of the Adaxes service account are used.

---

CloudServices

Gets an instance of the ReportCloudServicesScriptContext class that is used to work with cloud services.

---

Requirements

Minimum required version: 2018.1

See also

• Server-side scripting
• IADs
• IAdmTop
• IAdmAction
• ExecuteScriptInitiatorInfo
• ExecuteScriptLogMessageType