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

  • 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.

  • 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.

  • 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