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) or use a local file repository.

Using PowerShell scripts in a cloud deployment

To use PowerShell scripts in a cloud deployment, upload them to the management portal:

Go to the Cloud Management Portal and log in as an administrator.
From the left-hand menu, select Environments.
Open the drop-down menu on the right of the selected environment and click the Connectivity Manager option.
In the Connectivity Manager tick the PowerShell upload option.
Click on the UPLOAD button and choose the PowerShell scripts you want to upload.
To finalize click the CLOSE button.
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.

Impersonation of script execution

By default, the PowerShell connector functions in the context of a user that the Omada Provisioning Service is set up to. Impersonation is not available in Omada Identity Cloud.

^on-prem Configuring the PowerShell connector in the context of a different user is enabled by the impersonation feature. The PowerShell connector supports impersonation when running a PowerShell script. The impersonation is enabled using the following settings:

impersonateUserDomain - provides domain name of the impersonated user.
impersonateUser - provides user name of the impersonated user.
impersonateUserPassword - provides password of the impersonated user. The password can be encrypted using, for example, StringEncrypter.exe tool.

Data model

The PowerShell connector has no fixed data model. Instead, it has a naming convention for the name of the PowerShell function that it must call for a given operation for a given object type:

<Operation>-<ObjectTypeName>

The <operation> can be one of the following: Create, Update, Delete, CreateOrUpdate or DeleteIfExists.

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 could handle the parameters as bundled attributes. See the section Bundled attributes below for more details. 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

If you must perform any kind of initialization in your script, for example to make a connection to a server or a database, define an Initialize function in your script. The function does not receive any parameters, for example:

 function Initialize{
    --do some initialization stuff
 }

The initialize method is only called 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 (for example, to verify if the connection to the database can be established from the script), while saving connector settings, define a PowerShell function named TestConnection. Include a validation code.The function doesn't receive any parameters.

function TestConnection{
  -- example validation
}

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 on the Param section of the function. For this feature to work, perform the following actions:

The bundledAttributes parameter should be declared on 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 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 for supporting the bundledAttributes. The fieldMapping name must be bundledAttributes and string as data type. 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>

Reading configuration settings

Configuration options that are prefixed with setting are available to use in your PowerShell script. 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 "settingFilename"

Controlling the provisioning result

You can control the result of a provisioning task in the PowerShell script. For this, you can then use the function OPS-Create-ReturnValue. 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.

Here is an example of how to use the function:

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

Using PowerShell scripts in a cloud deployment​

Impersonation of script execution​

Data model​

The Initialize method​

The Finalize method​

The TestConnection method​

Bundled Attributes​

Reading configuration settings​

Controlling the provisioning result​