Before and After Scripts for IQService

The IQService supports function customization by allowing integrating Before/After scripts implemented in languages like PowerShell and Batch. Scripts can be used to automate any required actions that cannot be automated using current source functions. Scripts called before processing the request are referred to as Native Before Scripts and scripts called after processing the request are referred to as Native After Scripts.

SailPoint provides most of the provisioning functionality for many systems through its connectors. Some systems provide a better integration interface from the Windows platform compared to other platforms. So connectors for these systems require IQService deployed on a Windows system. The IQService implementation performs the provisioning functions (such as Add User, Connect User to a Group) that are supported by the respective managed system. The IQService functions are called by the SailPoint source implementation.

In addition to the basic action, some organizations may require supplementary actions performed by each function from the Windows system. The IQService supports customization of the functions by allowing you to integrate Before and After scripts in any language. The following are some features of IQService Before and After scripts:

Centralized configurations (in SailPoint) for setting up Before and After scripts
Supports Object Oriented scripting
Script refers SailPoint library to get the request and result classes
Can be executed with specific context
Script can modify requests and results

A script is a group of statements that perform one or more actions and manipulate request and result attributes. Scripts can be used to automate any required actions.

The scripts need to be defined in a rule and then configured for a source in SailPoint. Based on the rule type (Before or After), the connector sends the scripts to be executed before or after processing the request to IQService.

IQService supports executing Before and After Rules for Create, Modify, and Delete request operations.

Warning

To enhance security, it is mandatory to configure the TLS for IQService. If you continue using non-TLS configuration, any before and after script execution will be disabled to safeguard your environment. Remove non-TLS configuration for IQService to execute any rules and scripts.

Writing a Script

IQService divides scripts in the following categories:

Scripts with Object Oriented support
Scripts without Object Oriented support

Scripts with Object Oriented Support

Scripting languages with Object Oriented capabilities (for example, PowerShell) are popular because of their simplistic nature and ease of use. These scripts can form objects of any type by referring to any library or assembly implemented in any language and call its methods.

Native scripts implemented in these languages have easier and more powerful access to request and result objects. IQService comes with a class library named Utils.dll which bundles all required classes to access the request and result objects. The inputs provided to the script are in the form of process environment variables. The following table describes the environment variables created by IQService:

Name	Type	Before Script	After Script
Application	System.Collections.Hashtable	Read Only	Read Only
Request	SailPoint.Utils.objects.AccountRequest	Read/Write	Read Only
Result	SailPoint.Utils.objects.ServiceResult	Not Available	Read/Write

The data in the environment variables is in XML. The script creates respective objects using Utils.dll. Once the object is modified, the script converts it to XML by calling the toxml() method of the object and then writes a file at the path passed as the only argument to the script to the XML.

The script returns a non-zero value if an error occurs. It writes the error message in the file at the path passed as the argument to the script. This failure is communicated to SailPoint as part of a result.

Sample PowerShell Before Script

The following is a sample PowerShell Before script which modifies the value of an attribute and adds one new attribute to the request:

# Refer to SailPoint class library Requires PowerShell v2 installed on the system.
Add-type -path utils.dll
# Read the environment variables
$sReader = New-Object System.IO.StringReader([System.String]$env:Request);

# Form the xml reader object
$xmlReader = [System.xml.XmlTextReader]([SailPoint.Utils.xml.XmlUtil]::getReader($sReader));

# Create SailPoint Request object
$requestObject = New-Object SailPoint.Utils.objects.AccountRequest($xmlReader);

# Loop through the attributes from the request for each ($attribute in $requestObject.AttributeRequests){
if($attribute.Name -eq "description"){
$attribute.value = "my description"; #change value of the attribute
}
}

# Add a new attribute to request
$attributeObject = New-Object SailPoint.Utils.objects.AttributeRequest;
$attributeObject.Name = "otherMobile";
$otherMobileValues = New-Object System.Collections.ArrayList;
$otherMobileValues.Add("222-292-2929");
$otherMobileValues.Add("333-292-2929");
$attributeObject.Value= $otherMobileValues;
$attributeObject.Operation = "Set";
$requestObject.AttributeRequests.Add($attributeObject);

# Write the request xml to file at the path passed as argument
$requestObject.toxml()|out-file $args[0];

Sample PowerShell After Script

The following is a sample PowerShell After script which ensures that the request was processed successfully and creates a home directory at the path specified in the request:

# Refer to SailPoint class library. Requires PowerShell v2 installed on the system.
Add-type -path E:\SVN\trunk\src\WinRPCGateway\IQService\bin\Debug\utils.dll

# Read the environment variables
$sReader = New-Object System.IO.StringReader([System.String]$env:Request);
$sResult = New-Object System.IO.StringReader([System.String]$env:Result);

# Form the xml reader objects
$xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader));
$xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult));

# Create SailPoint objects
$requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader);
$resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result);

#Check if the request was processed successfully
if($resultObject.Errors.count -eq 0){

#Get Home directory path
foreach ($attribute in $requestObject.AttributeRequests){

#Create Home directory
if($attribute.Name -eq "TS_TerminalServicesHomeDirectory"){
new-item $attribute.Value -itemtype directory;
}
}
}

The following script displays how to access any application configuration attribute in the script. The following example reads application attributes with the name, Office365Username and its associated password. It uses them to connect to Exchange Online and sets Mailbox properties:

# Refer to SailPoint class library.
Add-type -path C:\Program files\IQService\bin\Debug\utils.dll

# Read the environment variables
$sReader = New-Object System.IO.StringReader([System.String]$env:Request);
$sResult = New-Object System.IO.StringReader([System.String]$env:Result);

# Form the xml reader objects
$xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader));
$xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult));

# Create SailPoint objects
$requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader);
$resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result);

# Retrieve nativeIdentity from request object
$nativeIdentity = $requestObject.NativeIdentity

# Get xmlFactory object to retrieve application configuration
$xmlFactory = [sailpoint.Utils.xml.XmlFactory]::Instance;

# Read the environment variables
$sReader1 = $env:Application

# Retrieve application configuration object
$appObject = $xmlFactory.parseXml($sReader1)

#Retrieve application configuration entries named Office365username and password value from AzureAD application config
$office365AdminUsername = $appObject.Office365username

#Retrieve password attribute value
$o365Password = $appObject.password

#create Credential object
$secpasswd = ConvertTo-SecureString $o365Password -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential ($office365AdminUsername, $secpasswd)

#Connect to Office365
Import-Module msonline
Connect-MsolService -Credential $cred

#Connect Exchange-Online
$msoExchangeURL = "https://ps.outlook.com/powershell/"
$session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $msoExchangeURL -Credential $cred -Authentication Basic -AllowRedirection
Import-PSSession $session

# Set mailbox properties
Set-MailBox -identity $nativeIdentity -UseDatabaseQuotaDefaults $false -IssueWarningQuota "200MB" -ProhibitSendQuota "250MB" -ProhibitSendReceiveQuota "280MB"

Scripts Without Object Oriented Support

Non-Object Oriented scripts do not refer to the class library or support a way of parsing XML. To have easy access to each attribute along with their operation and values, IQService creates process environment variables for each of the application and request attributes. It formats the names as SP_<OPERATION>_<NAME> for requests and SP_APP_<NAME> for applications. For native identity, the environment variable is SP_NativeIdentity. These types of scripts have limited access to results and get only SUCCESS or FAIL in the Result environment variable. So the After scripts implemented using these scripting languages cannot modify any attribute or result. Before scripts can add, modify, or remove any attribute from the request. The script needs to write the newly added or modified attribute to the file at the path passed as an argument to the script in the form SP_<OPERATION>_<NAME>=<VALUE>. To remove the attribute from the request, write /~<ATTRIBUTE_NAME> to the file. The value for the multivalued attribute is delimited by /#/.

The following is a sample batch After script which ensures that the request was processed successfully and creates a home directory at the path specified in the request:

IF %Result% ==SUCCESS md %SP_Set_TS_TerminalServicesHomeDirectory%

Creating a Rule

To add the script to a rule and use it, you need to create a rule. Contact SailPoint Services for assistance on creating rule as per requirement.

Configuring the Rules in Source

Add the nativeRules attribute under the Attributes map with a list of rules that must be configured for a source in SailPoint using the REST API.

Note

For more information on SailPoint's REST APIs, refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) in the SailPoint Developer Community.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.