This is not the latest version of Identity Director documentation.
View available documentation.

Icon

Execute PowerShell Script

Use the Execute PowerShell Script action to integrate PowerShell scripts in your business workflow. For example, this can be used to update attributes or to check passwords within a compromised passwords database. This action is available in the Subroutine category.

Please note that this feature requires PowerShell 5.1.

Setting up your encryption key

Before using the Execute PowerShell Script workflow action, you must configure an encryption key, which is used to secure script execution. You can create an encryption key or add a previously generated key during the installation process or afterward.

The encryption key can be generated both during the installation process of the Transaction Engine and from the Management Portal, at Setup > Datastore.

Generating the encryption key during Transaction Engine installation Generating the encryption key from the Management Portal

  • When installing the Transaction Engine component of Identity Director, you have the possibility to Generate or Add a previously generated encryption key.

    That key will be used to encrypt some of your PowerShell data, especially related to credentials used for the script execution.

  • Please only use encryption keys that were generated using the Transaction Engine installer or the Management Portal.
    Using a key that was not generated using Identity Director components is not supported.

  • Make sure you save your encryption key and store it in a safe place.

  • Transaction Engine:

    • In the Windows Registry, go to HKEY_LOCAL_MACHINE\SOFTWARE\RES\ITStore\Transaction Engine\DBEncryptionKey.

    • Add the previously generated key.
      Example: cQLZvNLyaw2LAvSKMACKyJnVvO+cv7NCaWE2omNr3p8=

    • Restart the Transaction Engine.
      The key will be encrypted and ready to use.

  • Management Portal:

    Before applying the encryption key for the Management Portal, make sure that the Load User Profile option is set to True.

    1. Open the IIS Management Console.

    2. Navigate to Application Pools > IT Store Management.

    3. Open the Advanced Settings for IT Store Management.

    4. In the Process Model section, make sure that the Load User Profile is set to True.

    5. If the Load User Profile is set to False, set it to True and click Recycle.

      • If you have to change the configuration, make sure to exit the Management Portal first.


    Option 1:     Set the encryption key from the Management Portal

    • Open the Management Portal, go to Setup > Datastore and add the existing encryption key, or generate a new one.

    • Press the Test Connection button. If the test passes, you can press Save.

    Option 2: Set the encryption key in WebConsole.config

    • Browse to C:\Program Files (x86)\RES Software\IT Store\Web Console\Config.

    • Within this folder, locate the WebConsole.config file, open it and go to webConsoleConfiguration > managementService > database > encryptionKey.

    • Add the generated key.
      Example: cQLZvNLyaw2LAvSKMACKyJnVvO+cv7NCaWE2omNr3p8=

    • Once you restart the Application Pool or perform an IIS reset, the key will be encrypted and ready to use.

  • The encryption key is not visible in the Management Portal, at Setup > Datastore for security reasons.
  • Applying a new encryption key when a key has already been configured in the Transaction Engine will cause existing scripts to fail.
    • To see if an encryption key has been configured, look in your WebConsole.config file, in the section webConsoleConfiguration > managementService > database > encryptionKey.
  • Remember to use the same encryption key for all Identity Director components.
    • Seeing different values among the stored keys of the Transaction Engine and the Management Portal from the above locations does not necessarily mean that the encryption keys are different, only that they are encrypted differently.

  • If the encryption key is configured during upgrades, it does not automatically update on all the machines/components.

In some situations, you will have to re-enter the Password information for your workflow actions, in order to re-encrypt your data:

  • Changing the encryption key;
  • Changing the user under which the Management Portal Application Pool runs;
  • Changing the user under which the Transaction Engine service runs.

Workflow Action Fields and Configuration

Field

Explanation and Tips

Action Name

Optionally specify a friendly name for the action. If no name is specified, the workflow action type will be displayed instead.

  • This name must be unique in the workflow and will be displayed in the workflow overview.

User Name

Specify the user name of the account that will execute the script (run as). For local accounts, the machine name is not required, while for domain accounts you need to specify the domain name (i.e. domain\user).

  • The user name defined for the action needs to have proper permissions to execute the script. For example, if your script should create a file on the disk, the user name should at least have Modify permissions for that folder.

Please note that this is a required field.

Password

Specify the password of the account stated at User Name, above.

  • When duplicating the service or the workflow action, the Password field information will not be copied, for security reasons.

Please note that this is a required field.

Script

Specify the actual script that will be executed. The execution is handled by the engine responsible for the transactions.

  • To avoid waiting for long-running scripts, this workflow action execution is isolated from other actions. This allows transactions that do not contain any Execute PowerShell Script action to execute in parallel with no impact on performance.

  • Execute PowerShell Script actions are executed one at a time. If you have multiple pending transactions that contain Execute PowerShell Script actions, they will wait for the previous ones to be executed or aborted before starting their own execution.

    Consider the following scenario:

    1. Two services are started shortly after each other; Service A has an Execute PowerShell Script action at step 2, while Service B has an Execute PowerShell Script action at step 7.

    2. Service A starts, runs into the Execute PowerShell Script workflow action, and starts working on it.

    3. Service B starts and reaches the Execute PowerShell Script workflow action while the PowerShell Script from Service A is still running. It now has to wait until the PowerShell Script action is complete for Service A.

    Note that Service B only needs to wait for the PowerShell Script within Service A to complete, and not for the entire service.

  • The action can be aborted at any time, from the Transaction section of the Management Portal. By doing this, you stop the script execution thread and allow the next pending Execute PowerShell Script action to start its execution.

Notes

Specify a description of this action.
Input Parameters

Used for mapping attributes from Identity Director to PowerShell variables.

  • All the input parameters will be serialized upon compilation. This means that, if you need to perform certain operations on the parameters, you might need to cast them to the appropriate type. For example: $n = [int]#Service[n.Value]+1

    • Casting only works for basic types of parameters, such as integers.

      In the case of complex types, such as arrays, you must construct them instead of casting.

      1. Set the service attribute of type text you want to configure as array to 6;9;7;7;10;10.

      2. Construct the array in the PowerShell workflow action editor using the line below:

        $a = #Service[manualScores.Value].split(';') | % {iex $_}

  • The attributes can be used in cmdlets or in advanced scripts. For example, the following command will create a file at the specified path: New-Item-Path #Global[RootFolder.Value]\#Service[FileName.Value] - ItemType File

  • Attributes or other placeholders that contain space, dash, or underline characters are allowed. Any other special characters used in the attribute name are not supported.

  • The script allows the use of any attribute.
Output Parameters

Used for mapping variables from PowerShell to Identity Director attributes.

  • The script only allows the mapping of Service Attributes of type Text.

  • In order to map variables, you need to prefix the Identity Director parameter with $global:. For example, the following command will map the PowerShell output to the psVersion service attribute: $global:psVersion = [System.Environment]::OSVersion.Version

  • To map a PowerShell value to a service attribute with spaces, enclose the attribute with curly brackets. For example: ${global:Job Title} = 'engineer'

Logging and Error Handling

This action can handle both compile and runtime errors.

  • All the errors will be visible in the Transaction Engine log.

  • For user-handled errors, we recommend the use of Write-Error.
    For example: Write-Error "Something went wrong!".

  • Aborting the action will also be logged, together with an expected error that results from script interruption.

PowerShell Script Comments

Only multiline comments are supported. This means that, for single line comments, you should use the same pattern. For example: <# this is a comment #>.
See also