Adaxes SDKShow AllHide All

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 a predefined PowerShell variable called $Context in your script.

Inheritance: The ExecuteScriptContext class inherits from the Object class.

Methods

MethodDescription
Cancel Cancels the operation that caused execution of the script.

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

Details

Syntax

void Cancel(String reason)

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

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

Syntax

void LogMessage(String message, ExecuteScriptLogMessageType messageType)

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

  • messageType - Specifies the type of the Execution Log message. For more information and a list of values, see ExecuteScriptLogMessageType.

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

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

Details
Syntax
void LogException(Exception exception)
Examples
try
{
    ...
}
catch
{
    $Context.LogException($_.Exception)
}
BindToObject Binds to a directory object by the given ADS path.
Details

Syntax

IAdmTop BindToObject(String adsPath)

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 Active Directory or pass it through Adaxes pipeline to apply Business Rules, Security Roles, etc.
Details
Syntax
IAdmTop BindToObjectEx(String adsPath, Boolean pipelined)
  • 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 Active Directory. Set to $True to pass it through Adaxes pipeline.

Examples
The following example shows how to update the Department property of a user:
$pipelined=$False # If set to $True, Adaxes functionality will 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).
Details
Syntax
IAdmTop BindToObjectByDN(String dn)

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 Active Directory or pass it through Adaxes pipeline to apply Business Rules, Security Roles, etc.

The method is supported starting with Adaxes version 2018.1.

Details
Syntax
IAdmTop BindToObjectByDNEx(String dn, Boolean pipelined)

  • 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 Active Directory. Set to $True to pass it through Adaxes pipeline.

Examples
The following example shows how to update 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.

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

The method is supported starting with Adaxes version 2018.1.

Details
Syntax
IAdmTop BindToObjectBySearchResult(IAdmSearchResult searchResult)

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

Examples
The following code sample updates the Description property of groups in a certain OU:
# Execute search
# Bind to the container to search in $containerDN = "OU=Sales,DC=example,DC=com" $searcher = $Context.BindToObjectByDN($containerDN) # Specify search parameters $searcher.SearchFilter = "(&(objectClass=group)(!(description=*)))" $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 Active Directory or pass it through Adaxes pipeline to apply Business Rules, Security Roles, etc.

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

The method is supported starting with Adaxes version 2018.1.

Details
Syntax
IAdmTop BindToObjectBySearchResultEx(IAdmSearchResult searchResult, Boolean pipelined)
  • 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 Active Directory. Set to $True to pass it through Adaxes pipeline.

Examples
The following code sample updates the Description property of groups in a certain OU:
# Execute search
# Bind to the container to search in $containerDN = "OU=Sales,DC=example,DC=com" $searcher = $Context.BindToObjectByDN($containerDN) # Specify search parameters $searcher.SearchFilter = "(&(objectClass=group)(!(description=*)))" $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.
Details

Syntax

Boolean IsPropertyModified(String propertyName)

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

Syntax

Object GetModifiedPropertyValue(String propertyName)

The propertyName parameter indicates 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.
Details

Syntax

Object[] GetModifiedPropertyValues(String propertyName)

The propertyName parameter indicates 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.
Details

Syntax

void SetModifiedPropertyValue(String propertyName, Object propertyValue)

  • propertyName - Indicates 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.
Details

Syntax

void SetModifiedPropertyValues(String propertyName, Object[] propertyValues)

  • propertyName - Indicates the name of the property for which the values are set.

  • propertyValues - Contains 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.
Details

Syntax

Boolean IsPasswordChanged()

GetNewPassword Gets the new password entered for the user. If the password wasn't modified, the method returns NULL.
Details

Syntax

String GetNewPassword()

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

Syntax

void SetNewPassword(String newPassword)

SendMail Sends an email to the specified recipient.
Details

Syntax

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

  • toAddress - Specifies the recipient's e-mail address.

  • subject - Specifies the subject of the email.

  • textBody - Contains the body of the email in the plain text format. This parameter can be set to NULL.

  • htmlBody - Contains the body of the email in the HTML format. This parameter can be set to NULL.

SendSms (String, String) Sends an SMS message with the given text to the given phone number.
Details

Syntax

void SendSms(String mobileNumber, String smsText)

  • 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.
Details

Syntax

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

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

Syntax

String GetObjectDomain(String objectDN)

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

Syntax

String GetDisplayNameFromAdsPath(String adsPath)

The adsPath parameter specifies the ADS path of the directory object to build a display name for.

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

Syntax

String GetWellKnownContainerPath(String containerAlias)

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.

The method is supported starting with Adaxes version 2019.1.

Details
Syntax
String GetDomainController(String domain)

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.

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.

The method is supported starting with Adaxes version 2018.1.

Details
Syntax
Object[] FetchAllPropertyValues(IAdmTop obj, String propertyName)
  • obj - Specifies the directory object.
  • propertyName - Specifies the name of the directory object property.
Examples
The following code sample copies all members of a group to another group.
$sourceGroupDN = "CN=SourceGroup,CN=Users,DC=domain,DC=com"
$targetGroupDN = "CN=TargetGroup,CN=Users,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 Returns credentials of the Office 365 tenant associated with the target object.
Details

Syntax

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 Office 365 mailbox associated with the target object on hold.

# Get Office 365 credentials
$o365Credentials = $Context.GetOffice365Credential()

try
{
    $session = New-PSSession -ConfigurationName Microsoft.Exchange `
               -ConnectionUri https://outlook.office365.com/powershell-liveid/ `
               -Credential $o365Credentials -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) Returns credentials of the Office 365 tenant associated with the given object.

The method is supported starting with Adaxes version 2018.1.

Details

Syntax

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.

Examples

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

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

# Get Office 365 credentials
$o365Credentials = $Context.GetOffice365Credential($user)

try
{
    $session = New-PSSession -ConfigurationName Microsoft.Exchange `
               -ConnectionUri https://outlook.office365.com/powershell-liveid/ `
               -Credential $o365Credentials -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.
Details

Syntax

void SubmitForApproval(String[] approverDNs,
                       Boolean managerOfRequestorIsApprover,
                       Boolean ownerOfRequestorOUIsApprover,
                       Boolean managerOfTargetObjectIsApprover,
                       Boolean ownerOfTargetObjectOUIsApprover)

  • 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 an Active Directory Object.

  • managerOfRequestorIsApprover - Indicates whether the manager of the user who initiated the operation can approve or deny it.

  • ownerOfRequestorOUIsApprover - Indicates whether the owner of the Organizational Unit where the account of the operation initiator is located can approve or deny the request.

  • managerOfTargetObjectIsApprover - Indicates whether the manager or owner of the AD object on which the operation is performed can approve or deny the request.

  • ownerOfTargetObjectOUIsApprover - Indicates whether the owner of the Organizational Unit containing the AD object on which the operation is performed can approve or deny the request.

Remarks

The SubmitForApproval method is available in Run a program or PowerShell script actions executed by Business Rules, Custom Commands and Scheduled Tasks, and is not available in scripts executed by If PowerShell script returns true 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.

This method is available in versions 2014.1 and higher.

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)

For details on how to get the DN of a directory object, see Get the DN of an Active Directory Object.

IsApprovalRequiredException Returns TRUE if the given exception occurred because the operation requires approval.

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

Details
Syntax
Boolean IsApprovalRequiredException(Exception exception)
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[]).

The method is supported starting with Adaxes version 2018.1.

Details
Syntax
DirectorySearcher CreateGuidBasedSearcher(IList<Object> objectGuids)

The objectGuids parameter specifies a list of object GUIDs.

Examples
The following code sample updates Description of all direct members of a group.
$groupDN = "CN=SalesGroup,CN=Users,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.

Remarks

  • The method is supported starting with Adaxes version 2018.2.

  • The method is available only in PowerShell scripts executed in Custom Commands.

Details
Syntax
String GetParameterValue(String paramName)
GetParameterValue(String, Boolean) 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.

Remarks

  • The method is supported starting with Adaxes version 2018.2.

  • The method is available only in PowerShell scripts executed in Custom Commands.

Details
Syntax
String GetParameterValue(String paramName, Boolean valueForLdapFilter)
  • 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").

Properties

PropertyAccess TypeData TypeDescription
ActionRead-onlyIAdmAction

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.

TargetObjectRead-onlyIADs

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

InitiatorRead-onlyExecuteScriptInitiatorInfo

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.

RunAsRead-only NetworkCredential

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.

ConditionIsMetRead/Write Boolean Gets or sets a value indicating whether the condition is satisfied.

Remarks

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

ArgumentsRead-onlyIAdmArguments 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