Before/After Scripts for IQService

The IQService supports customization of the functions 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 functionalities. 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.

The following sources support Before/After Scripts for IQService:

Azure Active Directory
Active Directory
Lotus Domino
Microsoft SharePoint Online
Microsoft SharePoint Server

SailPoint provides most of the provisioning functionality for many systems through its connectors. Some systems provide better integration interface from Windows platform compared to other platforms. Hence connectors for such 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 System. The IQService functions are called by the Identity Security Cloud source implementation.

In addition to the basic action, some organizations may require supplementary actions performed by each function from Windows system. The IQService supports customization of the functions by allowing integrating before / after scripts implemented in any language. Following are some features of the IQService Before/After script:

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

A script is a group of statements that perform one or more actions and manipulate request / result attributes. Scripts can be used to automate any required actions that are currently performed manually. 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.

The scripts needs to be defined in a Rule and then configured for a source in Identity Security Cloud. Based on the rule type, the connector would send the scripts to IQService that needs to be executed before / after processing the request. The IQService supports executing before and after Rules for Create, Modify, and Delete request operations.

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 easy to use. These scripts can form objects of any type by referring any library/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 would be 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 should convert it to XML by calling toxml() method of the object and write the xml to a file at the path that is passed as the only argument to the script. The script returns non-zero value in case of error and writes the error message in the file at the path that is passed as the argument to the script. This failure is communicated to Identity Security Cloud as part of result.

Sample PowerShell before script

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

Copy

# 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 that ensures that the request was processed successfully and creates a home directory at the path specified in the request:

Copy

# 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;
}
}
}

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

Copy

# 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);

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

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

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

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

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

                            #Retrive 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 support referring to the class library or 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 attribute with name in the form SP_<OPERATION>_<NAME> for requests and SP_APP_<NAME> for application. For native identity, the environment variable would be SP_NativeIdentity. These types of scripts have limited access to result and get only SUCCESS or FAIL in the Result environment variable. Hence the after scripts implemented using these scripting languages cannot modify any attribute/result. The 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>. For removing the attribute from the request, write /~<ATTRIBUTE_NAME> to the file. Value for the multivalued attribute is delimited by /#/

Following is a sample batch after script which ensures that the request was processed successfully and creates 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 Attributes map with list of names of the Rules that must be configured for a source 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.

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.


	You are here:

Before/After Scripts for IQService

Writing a script

Scripts with Object Oriented support

Sample PowerShell before script

Sample PowerShell after script

Scripts without Object Oriented support

Creating a Rule

Configuring the Rules in Source

Documentation Feedback