ExecuteScriptContext

The ExecuteScriptContext class provides methods and properties that can be used in PowerShell scripts executed in actions and conditions. To access an instance of this class, use the predefined PowerShell variable called $Context in your script.

Inheritance: Object

Methods

Properties

Details

Cancel()

Cancels the operation that caused execution of the script.

void Cancel(string reason)

Parameters

The reason parameter specifies a reason why the operation is cancelled.

Remarks

This method is not available in PowerShell scripts executed in conditions.

---

LogMessage()

Adds a message to the Execution Log of the operation that caused execution of the script.

void LogMessage(string message, ExecuteScriptLogMessageType messageType)

Parameters

• message - Specifies the text of the message that will be recorded in the Execution Log.
• messageType - Specifies the type of the Execution Log message.

---

LogException()

Adds the given exception to the Execution Log of the operation that caused execution of the script.

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 execute operations on the object directly in the directory or pass it through Adaxes pipeline to apply business rules, security roles, etc.

IAdmTop BindToObjectEx(string adsPath, bool pipelined)

Parameters

• adsPath - Specifies the ADS path of the directory object to bind to.
• pipelined - Set to $false to execute all operations on the object directly in the directory. Set to $true` to pass it through Adaxes pipeline.

Examples

The following code sample updates the Department property of a user.

$pipelined = $false # Adaxes functionality will not be applied on user update

$obj = $Context.BindToObjectEx("Adaxes://example.com/CN=John Doe,DC=example,DC=com", $pipelined)
$obj.Put("department", "Sales")
$obj.SetInfo()

---

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 execute operations on the object directly in the directory or pass it through Adaxes pipeline to apply business rules, security roles, etc.

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 execute all operations on the object directly in the directory. Set to $true to pass it through Adaxes pipeline.

Remarks

The method is supported starting with Adaxes version 2018.1.

Examples

The following code sample updates the Department property of a user.

$pipelined = $false # Adaxes functionality will not be applied on user update

$obj = $Context.BindToObjectByDNEx("CN=John Doe,DC=example,DC=com", $pipelined)
$obj.Put("department", "Sales")
$obj.SetInfo()

---

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.

Examples

The following code sample updates the Description property of groups in a certain OU.

# Bind to the container to search in
$containerDN = "OU=Sales,DC=example,DC=com"
$searcher = $Context.BindToObjectByDN($containerDN)

# Specify search parameters
$searcher.Criteria = New-AdmCriteria "group" {description -empty $true}
$searcher.SetPropertiesToLoad(@("objectGuid", "objectClass"))

try
{
    # Execute search
    $searchResultIterator = $searcher.ExecuteSearch()
    $searchResults = $searchResultIterator.FetchAll()
}

finally
{
    # Release resources
    if ($searchResultIterator) { $searchResultIterator.Dispose() }
}

foreach ($searchResult in $searchResults)
{
    # Bind to group
    $group = $Context.BindToObjectBySearchResult($searchResult)

    # Update group
    $group.Put("description", "Sales")
    $group.SetInfo()
}

---

BindToObjectBySearchResultEx()

Binds to a directory object by the specified search result. This method extends the BindToObjectBySearchResult method with the ability to specify whether to execute operations on the object directly in the directory or pass it through Adaxes pipeline to apply business rules, security roles, etc.

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 execute all operations on the object directly in the directory. Set to $true to pass it through Adaxes pipeline.

Remarks

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

Examples

The following code sample updates the Description property of groups in a certain OU.

# Bind to the container to search in
$containerDN = "OU=Sales,DC=example,DC=com"
$searcher = $Context.BindToObjectByDN($containerDN)

# Specify search parameters
$searcher.Criteria = New-AdmCriteria "group" {description -empty $true}
$searcher.SetPropertiesToLoad(@("objectGuid", "objectClass"))

try
{
    # Execute search
    $searchResultIterator = $searcher.ExecuteSearch()
    $searchResults = $searchResultIterator.FetchAll()
}

finally
{
    # Release resources
    if ($searchResultIterator) { $searchResultIterator.Dispose() }
}

$pipelined = $false # Adaxes functionality will not be applied on group update

foreach ($searchResult in $searchResults)
{
    # Bind to group
    $group = $Context.BindToObjectBySearchResultEx($searchResult, $pipelined)

    # Update group
    $group.Put("description", "Sales")
    $group.SetInfo()
}

---

IsPropertyModified()

Gets a value indicating whether a property of a given name was modified during the operation that caused execution of the script.

bool IsPropertyModified(string propertyName)

Parameters

The propertyName parameter indicates the name of the property to be checked.

---

GetModifiedPropertyValue()

Gets the value entered by the user for a property of a given name. If the property wasn't modified or its value was cleared, the method returns $null.

object GetModifiedPropertyValue(string propertyName)

Parameters

The propertyName parameter specifies the name of the property for which the value is requested.

---

GetModifiedPropertyValues()

Gets an array of values entered by the user for a property of a given name. If the property wasn't modified or its value was cleared, the method returns $null. Use this method for properties that can contain multiple values.

object[] GetModifiedPropertyValues(string propertyName)

Parameters

The propertyName parameter specifies the name of the property for which the values are requested.

---

SetModifiedPropertyValue()

Changes the value entered by the user for a property of a given name.

void SetModifiedPropertyValue(string propertyName, object propertyValue)

Parameters

• propertyName - Specifies the name of the property for which the value is set.
• propertyValue - Specifies the value to be set for the property.

---

SetModifiedPropertyValues()

Changes the values entered by the user for a multi-valued property of a given name.

void SetModifiedPropertyValues(string propertyName, object[] propertyValues)

Parameters

• propertyName - Specifies the name of the property for which the values are set.
• propertyValue - Specifies an array of values to be set for the property.

---

IsPasswordChanged()

Gets a value indicating whether the user password was changed during the operation that caused execution of the script.

bool IsPasswordChanged()

---

GetNewPassword()

Gets the new password entered for the user. If the password wasn't modified, the method returns $null.

string GetNewPassword()

---

SetNewPassword()

Changes the password entered for the user and sets it to the value specified.

void SetNewPassword(string newPassword)

---

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 specified 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.

Remarks

The method is supported starting with Adaxes version 2018.1.

Examples

The following code sample copies all members of a group to another group.

$sourceGroupDN = "CN=SourceGroup,CN=Groups,DC=domain,DC=com"
$targetGroupDN = "CN=TargetGroup,CN=Groups,DC=domain,DC=com"

# Bind to groups
$sourceGroup = $Context.BindToObjectByDN($sourceGroupDN)
$targetGroup = $Context.BindToObjectByDN($targetGroupDN)

# Get DNs of all source group members
$memberDNs = $Context.FetchAllPropertyValues($sourceGroup, "member")

# Add members to the target group
$targetGroup.PutEx("ADS_PROPERTY_APPEND", "member", $memberDNs)
$targetGroup.SetInfo()

---

GetOffice365Credential()

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

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

PSCredential GetOffice365Credential()

Return value

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

Examples

The following code sample places the Microsoft 365 mailbox associated with the target object on hold.

# Get Microsoft 365 credentials
$m365Credentials = $Context.GetOffice365Credential()

try
{
    $session = New-PSSession -ConfigurationName Microsoft.Exchange `
               -ConnectionUri https://outlook.office365.com/powershell-liveid/ `
               -Credential $m365Credentials -Authentication Basic -AllowRedirection
    Import-PSSession $session
    
    $mailboxSearch = Get-MailboxSearch -Identity "My Mailbox Hold"
    $sourceMailboxes = $mailboxSearch.SourceMailboxes
    $sourceMailboxes += "%userPrincipalName%"
    
    Set-MailboxSearch -Identity $mailboxSearchName -SourceMailboxes $sourceMailboxes
}
finally
{
    if ($session) { Remove-PSSession $session }
}

---

GetOffice365Credential(IAdmTop)

The method is deprecated and should not be used. Use the CloudServicesScriptContext::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.

Remarks

The method is supported starting with Adaxes version 2018.1.

Examples

The following code sample places on hold the Microsoft 365 mailbox associated with a user.

# Bind to user
$userDN = "CN=John Smith,CN=Users,DC=domain,DC=com"
$user = $Context.BindToObjectByDN($userDN)

# Get Microsoft 365 credentials
$m365Credentials = $Context.GetOffice365Credential($user)

try
{
    $session = New-PSSession -ConfigurationName Microsoft.Exchange `
               -ConnectionUri https://outlook.office365.com/powershell-liveid/ `
               -Credential $m365Credentials -Authentication Basic -AllowRedirection
    Import-PSSession $session

    $mailboxSearch = Get-MailboxSearch -Identity "My Mailbox Hold"
    $sourceMailboxes = $mailboxSearch.SourceMailboxes

    $userPrincipalName = $user.Get("userPrincipalName")
    $sourceMailboxes += $userPrincipalName
    
    Set-MailboxSearch -Identity "My Mailbox Hold" -SourceMailboxes $sourceMailboxes
}
finally
{
    if ($session) { Remove-PSSession $session }
}

---

SubmitForApproval()

Submits a request to approve the operation that caused execution of the script.

void SubmitForApproval(string[] approverDNs,
                       bool managerOfRequestorIsApprover,
                       bool ownerOfRequestorOUIsApprover,
                       bool managerOfTargetObjectIsApprover,
                       bool ownerOfTargetObjectOUIsApprover)

Parameters

• approverDNs - An array of string, each element of which is a distinguished name (DN) of a user or group that can approve or reject the request. For details on how to get the DN of a directory object, see Get the DN of a directory object.
• managerOfRequestorIsApprover - Specifies whether the manager of the user who initiated the operation can approve or deny it.
• ownerOfRequestorOUIsApprover - Specifies whether the owner of the organizational unit where the account of the operation initiator is located can approve or deny the request.
• managerOfTargetObjectIsApprover - Specifies whether the manager or owner of the directory object on which the operation is performed can approve or deny the request.
• ownerOfTargetObjectOUIsApprover - Specifies whether the owner of the organizational unit containing the directory object on which the operation is performed can approve or deny the request.

Remarks

• The method is supported starting with Adaxes version 2014.1.
• The method is not available in PowerShell scripts executed in conditions.
• When executed in a business rule, this method will work correctly only if the business rule is triggered before the operation you want to submit for approval.

Examples

The following code example submits an operation for approval to user John Smith.

$Context.SubmitForApproval(@("CN=John Smith,CN=Users,DC=example,DC=com"), $false, $false, $false, $false)

The following example submits an operation for approval to a specific user, group, and the manager of the operation initiator.

$approvers = @(
    "CN=John Smith,CN=Users,DC=example,DC=com",
    "CN=Group,OU=Groups,DC=example,DC=com")

$managerOfRequestorIsApprover = $true

$Context.SubmitForApproval($approvers, $managerOfRequestorIsApprover, $false, $false, $false)

---

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.

Remarks

The method is supported starting with Adaxes version 2018.1.

Examples

The following code sample updates Description of all direct members of a group

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

try
{
   # Execute search
   $searchResultIterator = $searcher.ExecuteSearch()
   $searchResults = $searchResultIterator.FetchAll()
}

finally
{
   # Release resources
   if ($searchResultIterator) { $searchResultIterator.Dispose() }
}

# Update group members description
foreach ($searchResult in $searchResults)
{
    $member = $Context.BindToObjectBySearchResult($searchResult)
    $member.Put("description", "My description")
    $member.SetInfo()       
}

---

GetParameterValue(string)

Returns the value of the given custom command parameter.

string GetParameterValue(string paramName)

Remarks

• The method is supported starting with Adaxes version 2018.2.
• The method is available only in PowerShell scripts executed in custom commands.

---

GetParameterValue(string, bool)

Returns the value of the given custom command parameter. This 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 parameter for which to return the value.
• 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").

Remarks

• The method is supported starting with Adaxes version 2018.2.
• The method is available only in PowerShell scripts executed in custom commands.

---

Action

Gets an object that represents the operation that caused execution of the script. The interfaces supported by this object will depend on the operation type. See, which interfaces are supported by different operation types.

---

TargetObject

Gets the directory object on which the operation that caused execution of the script was performed.

---

Initiator

Gets an instance of the ExecuteScriptInitiatorInfo class that allows you to get information about the user who initiated the operation that caused execution of the script.

---

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 CloudServicesScriptContext class that is used to work with cloud services.

Remarks

The property is supported starting with Adaxes version 2021.1.

---

ConditionIsMet

Gets or sets a value indicating whether the condition is satisfied.

Remarks

This property is available only in PowerShell scripts executed in conditions.

---

Arguments

Gets arguments for custom command execution.

Remarks

• The property is supported starting with Adaxes version 2018.2.
• The property is available only in PowerShell scripts executed in custom commands.

---

Requirements

Minimum required version: 2011.2

See also

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