PowerShell

The PowerShell connector supports data provisioning only. You can configure provisioning to systems where PowerShell scripts are used to perform the tasks. Upload the extension scripts using the Cloud Management Portal (for Omada Identity Cloud with VPN connectivity) or use a local file repository with the on-premises Omada Provisioning Service and Cloud Application Gateway (CAG).

Using PowerShell provisioning with an Omada instance

Cloud Application Gateway (CAG) based connectivity

When using CAG hosted on a Windows server in the company infrastructure, place the script on the CAG host. Configure the full path to the script in the connector configuration on the system in the Omada portal.

important

The PowerShell connector is not supported for use with the Omada hosted CAG instance.

VPN based connectivity

tip

The PowerShell script executes on a host in the Omada cloud, so troubleshooting and debugging options are limited. Consider switching to Cloud Application Gateway to run the scripts on a host where the technical team has full access to test the script and use logging options.

To use PowerShell scripts in a cloud deployment when running without CAG enabled, upload the PowerShell scripts to the management portal:

1. Go to the Cloud Management Portal and log in as an administrator.

2. From the left-hand menu, select Environments.

3. Open the drop-down menu on the right of the selected environment and click the Connectivity Manager option.

   

4. In the Connectivity Manager, select the PowerShell upload option.

   

5. Click the UPLOAD button and choose the PowerShell scripts you want to upload.

   

6. To finalize, click the CLOSE button.

7. During system onboarding, go to the Connection details and configure the Script file setting with the PowerShell script name.

important

To make the selected script functional, commit the settings for the system that the script was applied to.

On-premises deployment

To use PowerShell scripts in the on-premises deployment model, copy the scripts to a folder on the server where the Omada Provisioning Service (OPS) is installed. The folder must be accessible to the service account used by the OPS service.

During system onboarding, go to the Connection details and configure the Script file setting with the full path to the PowerShell script.

Impersonation of script execution

By default, the PowerShell connector functions in the context of the user account that the Omada Provisioning Service runs as.

info

Impersonation is not available in Omada Identity Cloud when using the VPN-based connectivity option. Consider changing to use Cloud Application Gateway.

Configuring the PowerShell connector in the context of a different user is enabled by the impersonation feature. Impersonation is enabled using the following Connector Settings:

• Impersonate User - defines the user name of the impersonated user.
• Impersonate User Domain - defines the domain name of the impersonated user.
• Impersonate User Password - defines the password of the impersonated user.

Configuring a script for the PowerShell connector

Functions for provisioning operations

The PowerShell connector adopts a flexible data model that uses a naming convention for the name of the PowerShell function that it calls for a given operation for a given object type:

<Operation>-<ObjectTypeName>

The values are mapped in the task mapping for the object:

• <Operation> is defined by RoPE during calculation and is mapped as the "operation" in the task mapping. The value is one of the following: Create, Update, Delete, CreateOrUpdate or DeleteIfExists.
• <ObjectTypeName> is the value mapped as the "Object type" in the task mapping.

important

The PowerShell connector caches the script at startup. During script creation and testing, restart the OPS/CAG instance whenever you change the script to ensure that the new version is executed.

If you want to create files, for example, using the PowerShell connector, you have to create a PowerShell function named Create-File. The function could receive a parameter for the name of the file, for example, $name. In this case, your PowerShell function should look like this:

 function Create-File{
   Param
   (
      [Parameter(Mandatory=$true)][String]$name
   )
   New-Item -ErrorAction Ignore -ItemType file -Path "$name"

 }

It is important to specify parameters in the Param section. If you have not specified the parameters in the Param section of a function, the connector can handle the parameters as bundled attributes. For more details, see Bundled Attributes. A connector data model for the above function has the following structure:

 <connectorDataModel xmlns="http://schemas.omada.net/ops/2015/ConnectorDataModelML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    <property name="name" />
  </properties>
  <objects>
    <object name="File">
      <objectProperties>
        <objectProperty>name</objectProperty>
      </objectProperties>
    </object>
  </objects>
 </connectorDataModel>

When you run the function, the connector verifies data types in the connector model with data types of the parameters on the function. The connector also verifies if the parameters are multi-value properties and if mandatory parameters are filled.

The Initialize method

To perform general initialization before running provisioning operations, for example, to make a connection to a server or a database, define an Initialize function in the script. The function does not receive any parameters, for example:

 function Initialize{
    --do some initialization stuff
 }

The Initialize method is called only once. To call the method again, you must restart the OPS service or push the configuration to OPS from the Provisioning Monitor.

The Finalize method

To perform cleanup when OPS is shut down, define a PowerShell function named Finalize. The function receives no parameters, for example:

 function Finalize{
    -- Finalization functionality
 }

The TestConnection method

To perform validation when saving connector settings (for example, to verify that the connection to the database can be established from the script), define a PowerShell function named TestConnection and include validation code in it. The function does not receive any parameters.

function TestConnection{
  #if (validation failure)
  #{
  #  throw 'Some error occurred'
  #}
}

In case of failure, a message can be reported to the user by throwing an exception. If the validation is not required, leave the method body empty.

Bundled Attributes

Bundled attributes are an alternative way to handle parameters for a PowerShell function without having explicitly declared them in the Param section of the function. For this feature to work, perform the following actions:

• Declare the bundledAttributes parameter in the Param section of the function.
• The OPS-Return-HashTable function may be in use in the body of the function.
• The Connector Data Model and the corresponding TaskMapping file must also be configured to support the bundledAttributes.
• The bundledAttributes parameter must be declared in the PowerShell function, and the parameter attribute ValueFromRemainingArguments must be set to True. By doing that, all the remaining arguments, which have not been declared but are passed to the function, are set to the bundledAttributes variable as a list.

function Create-File{
 Param
 (
    [Parameter(Mandatory=$true)][String]$name,

    [parameter(ValueFromRemainingArguments=$true)]$bundledAttributes
 )
 ……………
}

By using the OPS-Return-HashTable function, you can transform the list of the remaining arguments that have been set to the bundledAttributes variable to a hash table, which is easier to handle. If the Create-File function is called like this:

Create-File -name "Folder Name" -path "C:\Temp\TestingFolder" -title "my test file"

function Create-File{

  Param
  (
      [Parameter(Mandatory=$true)][String]$name,
      [parameter(ValueFromRemainingArguments=$true)]$bundledAttributes
  )
  $htvars = OPS-Return-HashTable $bundledAttributes
}

Then, the $htvars hashtable variable has the following value:

Name	Value
-----	-----
title	my test file
path	C:\Temp\TestingFolder

The File object type should support the bundledAttributes property and must be configured in the related DataModel.

<connectorDataModel xmlns="http://schemas.omada.net/ops/2015/ConnectorDataModelML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    <property name="name" />
    <property name="bundledAttributes" />
  </properties>
  <objects>
    <object name="File">
      <objectProperties>
        <objectProperty>name</objectProperty>
        <objectProperty>bundledAttributes</objectProperty>
      </objectProperties>
    </object>
  </objects>
</connectorDataModel>

The related task mapping must also be configured to support the bundledAttributes. The fieldMapping name must be bundledAttributes, and the data type must be string. The value of the fieldMapping must follow this naming convention:

<Parameter>=<Value>

For example: title=my test file

<taskMapping xmlns="http://schemas.omada.net/ops/2015/TaskMappingConfigurationML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <connectorObjectType mappingType="Constant">File</connectorObjectType>
  <mappedObjectType mappingType="Constant">File</mappedObjectType>
  <mappedObjectId mappingType="SourceField">ObjectId</mappedObjectId>
  <fieldMappings>
    <fieldMapping name="name" dataType="stringType" action="modify" mappingType="SourceField">ROPE_ATTR_FILENAME</fieldMapping>
    <fieldMapping name="bundledAttributes" dataType="stringType" mappingType="Expression">string.Format("path={0}", ROPE_ATTR_FILEPATH)</fieldMapping>
    <fieldMapping name="bundledAttributes" dataType="stringType" mappingType="Expression">string.Format("title={0}", ROPE_ATTR_FILETITLE)</fieldMapping>
  </fieldMappings>
</taskMapping>

Reporting the provisioning result

You can report the result of a provisioning task in the PowerShell script. To do so, use the OPS-Create-ReturnValue function. The function has four parameters:

• success - a Boolean variable to indicate if the task was successful. The parameter is optional, and its default value is True.
• transient - a Boolean variable to indicate if a failed task should be retried. The parameter is optional, and its default value is False.
• message - a string variable containing a descriptive message of the success or failure. The string is visible from the provisioning monitor.
• resultValues - a string array containing additional result information. Each entry in the array should be formed as a name-value pair, for example, errorCode=5. The parameter is optional.

The following example shows how to use the function (note the backticks/grave accents that are used in PowerShell when a statement is multi-line):

 function Create-SomeObject{
   return OPS-Create-ReturnValue `
     -success $true `
     -transient $false `
     -message "Object successfully created" `
     -resultValues @("objectId=12345","returnCode=1")
 }

Important: Only return the status object

The returned status object will not be parsed if other parts of the script generate output.

Example:

The web request generates output and therefore no return value is processed by the connector.

function Create-SampleUser
{
  param (
   [Parameter(Mandatory=$true)][String]$name
  )
  Invoke-WebRequest -Uri 'https://testendpoint47.free.beeceptor.com/user' -Method POST -Body "{""Username"" : ""$name""}"
  return OPS-Create-ReturnValue -success $true -transient $false -message "Object successfully created" -resultValues @("objectId=$name","returnCode=1")
}

Discarding the output by assigning it to $null solves the problem:

  $null=Invoke-WebRequest -Uri 'https://testendpoint47.free.beeceptor.com/user' -Method POST -Body "{""Username"" : ""$name""}"

Using configuration settings

You can optionally add options to the connector configuration to define connectivity parameters in the Omada UI. Prefix every parameter that must be available in the PowerShell script with setting. To read the value, use the built-in OPS-Get-Setting function. The function takes one parameter (-key), which is the name of the setting, including "setting", for example:

$filename=OPS-Get-Setting -key "settingsysUrl"

Example

Adding the following XML to the Onboarding configuration property on a PowerShell Connector data object extends the configuration options with three properties: URL, User name, and Password.

The schema for the configuration XML document is defined in the name space http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML and available in the Setup\XML Schemas menu available to System Administrators in the Omada UI.

Onboarding configuration XML

Option: Remove the sections marked Custom parameters to revert to the standard setting.

<systemCategoryConfiguration xmlns="http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML"
                             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<configurationSections>
  <configurationSection 
    allowFinish="true"
    name="ConnectorSettings"
    title="S_SYSOVW_OPSEX_ConnectorSettings_Title"
    description="S_SYSOVW_OPSEX_ConnectorSettings_Description">
  <configurationParameters>

<!-- Standard PowerShell connector parameters-->
	<configurationParameter 
          name="OPSScriptFile"
          title="Script file"
          description="Enter the name of the PowerShell script file that contains the functions"
          requiredProvisioning="true"
          type="stringType"
          scope="dataConnection"
          connectorSetting="scriptFile"/>
  <configurationParameter 
          name="OPSImpersonateUser"
          title="Impersonate User"
          description="The user name of the user that should be impersonated."
          requiredProvisioning="false"
          type="stringType"
          scope="dataConnection"
          connectorSetting="impersonateUser"/>
  <configurationParameter 
          name="OPSImpersonateUserDomain"
          title="Impersonate User Domain"
          description="The name of the domain where the impersonated user exists."
          requiredProvisioning="false"
          type="stringType"
          scope="dataConnection"
          connectorSetting="impersonateUserDomain"/>
  <configurationParameter 
          name="OPSImpersonateUserPassword"
          title="Impersonate User Password"
          description="The password for the given user."
          requiredProvisioning="false"
          type="secureStringType"
          scope="dataConnection"
          connectorSetting="impersonateUserPassword"/>
<!-- Custom parameters -->
  <configurationParameter 
          name="sysUrl"
          title="URL"
          description="Enter the URL of the Megamart system."
          requiredProvisioning="true"
          type="stringType"
          scope="dataConnection"
          connectorSetting="settingsysUrl"/>
  <configurationParameter 
          name="sysUser"
          title="User name"
          description="Enter the user name to connect to the Megamart system."
          requiredProvisioning="true"
          type="stringType"
          scope="dataConnection"
          connectorSetting="settingsysUser"/>
  <configurationParameter 
          name="sysPassword"
          title="Password"
          description="The password to connect to the Megamart system."
          requiredProvisioning="true"
          type="secureStringType"
          scope="dataConnection"
          connectorSetting="settingsysPassword"/>

<!-- Standard PowerShell connector parameter-->
  <configurationParameter 
          name="OPSTestConnection"
          title="S_SYSOVW_AD_ConnectionDetails_ConnectionTest_Title"
          description="S_SYSOVW_AD_ConnectionDetails_ConnectionTest_Description"
          requiredOffline="false"
          requiredFull="false"
          defaultValue="false"
          requiredProvisioning="false"
          type="booleanType"
          scope="dataConnection"
          connectorSetting="OPSTestConnection"/>										
  </configurationParameters>
  </configurationSection>
</configurationSections>
	<settings>
		<postActionHandler>Omada.OE.Solution.OIM.Assembly.SystemOnBoardingPostActions.GenericPostActionHandlerOPS, Omada.OE.Solution.OIM.Assembly</postActionHandler>
	</settings>
</systemCategoryConfiguration>

You can retrieve the values in the script with:

$url=OPS-Get-Setting -key "settingsysUrl"
$usr=OPS-Get-Setting -key "settingsysUser"
$pw=OPS-Get-Setting -key "settingsysPassword"