Run PowerShell Script Activity
The Run PowerShell activity allows you to run a PowerShell 2.0 script and return script output to the executing workflow to be consumed in the subsequent child activities.
Optional. Name of the activity to be displayed on the MIMWAL workflow designer.
Optional. The condition which must be satisfied to for execution of this activity's core task (i.e. run the PowerShell script). This can be any WAL function expression resolving to a boolean value.
Optional.The username of the user account to use while constructing a PowerShell Credential object to pass the script. The credential object is passed as a $Credential session variable to the script. The username must be in the Domain\UserName format if "Impersonate PowerShell User" setting is selected.
Required when "PowerShell Script User" is specified. The password of the user account to use while constructing a PowerShell Credential objects to pass the script. The password value specified is an encrypted value using a certificate, DPAPI or RSA Machine Keys. Using a self-signed certificate is recommended due to ease of deployment. Please see EncryptedData.ps1 in the "SolutionOutput" folder that demonstrates how the password can be encrypted in the RunPowerShellScript Activity.
Optional. If this setting is selected, the PowerShell script is executed in the context of the specified RunAs user account. This option should be avoided, if the command-lets used in the script support a Credential parameter.
Optional. If this setting is selected, the user profile of the RunAs user is loaded during impersonation.
Optional. Logon type to use during impersonation. For more information, refer to the dwLogonType documentation. The default value is "Log on as a batch job".
Required. Specifies how the activity will locate the script for execution. The available options are:
- Include in the Workflow Definition
- Read from File
- Resolve from Lookup
Required when "Include in the Workflow Definition" option is selected for Script Location. In this case, the PowerShell script is stored as part of the workflow XOML.
Required when "Read from File" option is selected for Script Location. In this case, the full path of the script located on a network share accessible by all FIMService instances is specified.
Required when "Resolve from Lookup" option is selected for Script Location. In this case, a WAL Lookup expression which represents the script to be executed by the activity is specified.
Required when "Resolve from Lookup" option is selected for Script Location. Specifies whether or not the activity should generate an error when the script lookup resolves to a null value.
Optional. Specifies how the input should be provided to the PowerShell script. The available options are:
- None
- Named Parameters
- Arguments
Required when "Named Parameters" option is selected for script Input Type. When this option is selected, you can then define a list of parameter names expected by the script and corresponding WAL value expressions to be supplied to the script as the values of those parameters.
Required when "Arguments" option is selected for script Input Type. When this option is selected, you can define a list of WAL value expressions to be passed as unnamed arguments to the script. The arguments are passed in the order they are listed.
Optional. Specifies how the script output should be processed. The available options are:
- None
- Single Value
- Table of Values
The activity can capture a return value from the PowerShell script and publish it to a lookup. Alternatively, the PowerShell script may return a Hashtable of named values which can be published to the workflow data dictionary WorkflowData using corresponding key names.
It should be noted that, in contrast to a "return statement" in a C# function, the return value from a PowerShell script / function is not necessarily what is returned by a return statement. Hence, output from any command or function that is not the intended return value from the script should be ignored ("void"ed) or thrown away ("Out-Null"ed) so that it does not piped to the output stream which is what is "returned" by the script.
Required when "Single Value" option is selected for Script Return Type. When this option is selected, the script return value is published to the specified WAL Lookup expression.
With great power comes great responsibility :).The RunPowerShellScript activity is a "catch_all" activity in WAL. However, due to the obvious performance implications and the possibility of session throttling implemented by the remote systems such as Exchange, Lync/Skype, etc., use of this activity should be avoided in production environments and particularly so in large scale, high-transaction implementations. Instead you should look at exploiting other native WAL activities or take a Management Agent based approach as much as possible. If you think you can avoid the use of RunPowerShellScript activity if a feature were added to WAL, please submit a feature request to the WAL project team.
The RunPowerShellScript activity has no way of knowing which errors in your script are terminating errors and which ones can simply be ignored. To be safe than sorry, the activity will treat any errors as fatal errors and abort the workflow. Hence when developing your script take a "pessimistic" approach to the script development and test for the success of a command before issuing the command in your script.
All MIM/FIM workflows run in a .NET Framework 3.5 runtime. This .NET runtime environment cannot execute scripts and command-lets that need PowerShell 3.0 or above runtime. If there is a need to execute a script containing PowerShell 3.0+ command-lets, they can be run out-of-process. e.g. using PowerShell Remoting or launching a new "powershell.exe" session using Start-Process command-let.
The RunPowerShellScript activity passes the activity execution context as session variables AECWorkflowInstanceId, AECRequestId, AECActorId, AECTargetId and AECWorkflowDefinitionId). It also set ProgressPreference, DebugPreference and VerbosePreference as per trace levels in the app.config file of FIMService. It is recommended that you instrument your scripts using this information so that the workflow can be traced end-to-end. This is demonstrated in the sample script RunPSLoggingSample.ps1 copied to the "SolutionOutput" folder.