ReportCustomColumnScriptContext

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

Inheritance: Object

Methods

Properties

Details

GetDirectoryObject()

Returns the directory object for which the custom column value is generated.

IAdmTop GetDirectoryObject()

Examples

The following code sample sets the custom column value to the Full Name of the object's manager.

# Get AD object
$obj = $Context.GetDirectoryObject()

# Get manager of the object
$managerDN = $obj.GetPropertyValue("manager")
if ($managerDN)
{
    $manager = $Context.BindToObjectByDN($managerDN)

    # Set column value
    $Context.Value = $manager.Get("cn")
}

---

GetParameterValue(string)

Returns the value of the given report parameter.

string GetParameterValue(string paramName)

---

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").

---

IsProtectedFromDeletion()

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

void ConvertToRegularMailbox()

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 sets the custom column value to "Protected" if an object is protected from accidental deletion.

# Get AD object
$obj = $Context.GetDirectoryObject()

# Get object security descriptor
$objSecurityDescriptor = $obj.Get("ntSecurityDescriptor")

# Get security descriptor of the object parent
$parent = $Context.BindToObject($obj.Parent)
$parentSecurityDescriptor = $parent.Get("ntSecurityDescriptor")

# Set column value
if ($Context.IsProtectedFromDeletion($objSecurityDescriptor, $parentSecurityDescriptor))
{
    $Context.Value = "Protected"
}

---

GetHostNameFromNetworkPath()

Returns the host name from the given network path.

string GetHostNameFromNetworkPath(string networkPath)

Examples

The following code sample sets the custom column value to the host name of the user's home directory.

# Get AD object
$user = $Context.GetDirectoryObject()

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

# Set column value
$Context.Value = $Context.GetHostNameFromNetworkPath($homeDirectory)

---

CreatePropertyValueComparer()

Returns an instance of the IEqualityComparer interface 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 information about account expiration to the custom column.

# Get AD object
$user = $Context.GetDirectoryObject()
    
# Get display text for the Account Expires property
$accountExpires = $user.Get("accountExpires")
$accountExpiresDisplayText = $Context.GetPropertyValueDisplayText("accountExpires", $accountExpires)

# Set column value
$Context.Value = "Account expiration date: $accountExpiresDisplayText"

---

LogMessage()

Adds a message of the given type to the report Data Retrieval 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 Data Retrieval 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 Data Retrieval 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.

public 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 sets the custom column value to the number of user's subordinates.

# Get AD object
$user = $Context.GetDirectoryObject()

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

# Set column value
$Context.Value = $subordinateDNs.Length

---

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 Active Directory 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[]).

public DirectorySearcher CreateGuidBasedSearcher(IList<Object> objectGuids)

Parameters

The objectGuids parameter specifies a list of object GUIDs.

---

ColumnId

Gets the unique identifier of the custom column.

---

ColumnDisplayName

Gets the display name of the custom column.

---

Value

Gets or sets the custom column value.

---

ValueType

Gets the data type of the custom column.

---

ReportItem

Gets the report item for which the custom column value is generated.

---

ReportArguments

Gets arguments for report generation.

---

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 used to generate the custom column is executed. If the property is null, the credentials of the Adaxes service account are used.

---

ItemID

Gets or sets the identifier of the report item for which the custom column value is generated.

---

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