Share via

Using Activities in Script Workflows

  • Article

 

Applies To: Windows Server 2012, Windows Server 2012 R2

This topic lists the Windows PowerShell Workflow activities and workflow activity parameters. It lists the Windows PowerShell cmdlets that are implemented as activities for Windows PowerShell Workflow and those that are excluded.

Script Workflow Activities

The following table lists activities that are add to Windows PowerShell for Windows PowerShell Workflow. They are valid only in workflows.

Activity

Description

Topic Reference

CheckPoint-Workflow (alias = PSPersist)

Takes a checkpoint. Saves the state and data of a workflow in progress. If the workflow is interrupted or rerun, it can restart from any checkpoint.

Use the Checkpoint-Workflow activity along with the PSPersist workflow common parameter and the PSPersistPreference variable to make your workflow robust and recoverable.

about_Checkpoint-Workflow, Adding Checkpoints to a Script Workflow

ForEach -Parallel

Runs the statements in the script block once for each item in a collection. The items are processed in parallel. The statements in the script block run sequentially.

about_Foreach-Parallel

Parallel

All statements in the script block can run at the same time. The order of execution is undefined.

about_Parallel

Sequence

Creates a block of sequential statements within a parallel script block. The Sequence script block runs in parallel with other activities in the Parallel script block. However, the statements in the Sequence script block run in the order in which they appear. Valid only within a Parallel script block.

about_Sequence

Suspend-Workflow

Stops a workflow temporarily. To resume the workflow, use the Resume-Job cmdlet.

about_Suspend-Workflow

Cmdlet Activities

All cmdlets in the following Windows PowerShell included modules are available as activities, except for those listed in the Excluded Cmdlets section. All other cmdlets and functions in Microsoft.PowerShell.* modules are implemented as activities for use in a workflow.

  • Microsoft.PowerShell.Core

  • Microsoft.PowerShell.Host

  • Microsoft.PowerShell.Diagnostics

  • Microsoft.PowerShell.Management

  • Microsoft.PowerShell.Security

  • Microsoft.PowerShell.Utility

  • Microsoft.Wsman.Management

If a cmdlet is not in a Windows PowerShell Core module, but it is not specifically excluded, Windows PowerShell Workflow automatically runs the cmdlet in an InlineScript activity and returns the output to the workflow.

Activities that Differ from Cmdlets

The following Windows PowerShell Core cmdlets are implemented as activities for use in Windows PowerShell Workflow. However, the behavior of the activity differs somewhat from the behavior of the cmdlet.

  • Invoke-Expression

    You can use the Invoke-Expression cmdlet to include inline XAML in a script workflow. In workflows, the Invoke-Expression cmdlet has a Language parameter that takes a value of "XAML". Use the Command parameter to specify the path to the XAML file, as shown in the following example.

    Workflow Test-Workflow
{
    Invoke-Expression -Language XAML -Command C:\ps-test\Get-AssetData.xaml
}

    For more information about the Invoke-Expression cmdlet, see Invoke-Expression.

     

  • New-Object

    In workflows, only the Typename and Argument parameters are valid.

    For more information about the New-Object cmdlet, see New-Object.

  • Restart-Computer

    In workflows, the Wait parameter is valid when restarting the local computer, as well as remote computers.

Excluded Cmdlets

The following Windows PowerShell cmdlets have not been implemented as workflow activities. Because they are excluded, Windows PowerShell Workflow does not automatically run these cmdlets in an InlineScript activity automatically. Typically, these cmdlets are not well suited to workflow tasks.

To run these cmdlets, include them in an inlineScript activity. The following example shows a call to the Get-Variable cmdlet in an inlineScript activity.

Workflow Test-Workflow
{
     InlineScript { Get-Variable}
}

Excluded Cmdlets

Add-History

Invoke-History

Add-PSSnapin

New-Alias

Clear-History

New-Variable

Clear-Variable

Out-GridView

Complete-Transaction

Remove-PSBreakpoint

Debug-Process

Remove-PSSnapin

Disable-PSBreakpoint

Remove-Variable

Enable-PSBreakpoint

Set-Alias

Enter-PSSession

Set-PSBreakpoint

Exit-PSSession

Set-PSDebug

Export-Alias

Set-StrictMode

Export-Console

Set-TraceMode

Get-Alias

Set-Variable

Get-History

Start-Transaction

Get-PSBreakpoint

Start-Transcript

Get-PSCallStack

Stop-Transcript

Get-PSSnapin

Trace-Command

Get-Transaction

Undo-Transaction

Get-Variable

Use-Transaction

Import-Alias

 

Activity Common Parameters

Windows PowerShell Workflow adds the activity common parameters to activities that are derived from the PSActivity base class. This category includes the InlineScript activity and Windows PowerShell cmdlets that are implemented as activities, such as Get-Process and Get-WinEvent.

The activity common parameters are not valid on the Suspend-Workflow and Checkpoint-Workflow activities and they are not added to cmdlets or expressions that Windows PowerShell Workflow automatically runs in an InlineScript or similar activity. The activity common parameters are available on the InlineScript activity, but not on commands in the InlineScript script block.

The following table lists the activity common parameters, showing the parameters that are shared with the workflow common parameters and with the Windows PowerShell common parameters, as well as the parameters that are unique to activities.

For information about the workflow common parameters, see about_WorkflowCommonParameters. For information about the Windows PowerShell common parameters, see about_CommonParameters. The parameters that are unique to activities are described in this topic.

The activity common parameters are extremely useful. For example, you can use the PSComputerName parameter to run particular activities on only a subset of the target computers. Or, you might use the PSConnectionRetryCount and PSConnectionRetryIntervalSec parameters to adjust the retry values for particular activities.

The following example shows how to use the workflow common parameters as variables in the workflow and as parameters at the activity level. This command runs the Get-Eventlog cmdlet only on computers in the User01 domain.

Workflow Test-Workflow
{
     $User01Domain = Get-Content -Path .\User01Computers.txt
     $Log = (Get-EventLog -LogName "Windows PowerShell" -PSComputerName $UserDomain}
     if ($Log) ...
}

Workflow Common Parameters

PSAllowRedirection

PSApplicationName

PSAuthentication

PSCertificateThumbprint

PSComputerName

PSConfigurationName

PSConnectionRetryCount

PSConnectionRetryIntervalSec

PSConnectionURI

PSCredential

PSPersist

PSPort

PSSessionOption

PSUseSSL

 

Windows PowerShell Common Parameters

Debug

ErrorAction

Verbose

WarningAction

Activity-Specific Common Parameters

Name

Definition

AppendOutput <SwitchParameter>

Adds the output of the activity to the value of the variable. By default, assigning a value to a variable replaces the variable value.

For example, the following commands add a process object to the service object in the $x variable.

workflow Test-Workflow { $x = Get-Service; $x = Get-Process -AppendOutput }

DisplayName <String>

Specifies a friendly name for the activity. The DisplayName value appears in the progress bar while the workflow runs and in the value of the Progress property of the workflow job. When the PSProgressMessage parameter is also included in the command, the progress bar content appears in <DisplayName>:<PSProgressMessage> format.

Input <Object[]>

Submits a collection of objects to an activity. This is an alternative to piping objects to the activity one at a time.

MergeErrorToOutput <SwitchParameter>

Adds errors to the output stream. Use this parameter with Parallel and ForEach -Parallel keywords to collect errors and output from multiple parallel commands in a single collection.

PSActionRetryCount <Int32>

Tries repeatedly to run the activity if the first attempt fails. The default value, 0, does not retry.

PSActionRetryIntervalSec <Int32>

Determines the interval between action retries in seconds. The default value, 0, retries the action immediately. This parameter is valid only when the PSActionRetryCount parameter is also used in the command.

PSActionRunningTimeoutSec <Int32>

Determines how long the activity can run on each target computer. If the activity does not complete before the timeout expires, Windows PowerShell Workflow generates a terminating error and stops processing the workflow on the affected target computer.

PSDebug <PSDataCollection[DebugRecord]>

Adds debug messages from the activity to the specified debug record collection, instead of writing the debug messages to the console or to the value of the Debug property of the workflow job. You can add debug messages from multiple activities to the same debug record collection object.

To use this activity common parameter, use the New-Object cmdlet to create a PSDataCollection object with a type of DebugRecord and save the object in a variable. Then, use the variable as the value of the PSDebug parameter of one or more activities, as shown in the following example.

workflow Test-Workflow
{
   $debugCollection = New-Object -Type System.Management.Automation.PSDataCollection[System.Management.Automation.DebugRecord]
   InlineScript {\\Server01\Share01\Get-AssetData.ps1} -PSDebug $debugCollection -Debug $True
   InlineScript {\\Server01\Share01\Set-AssetData.ps1} -PSDebug $debugCollection -Debug $True
   if ($debugCollection -like "*Missing*") { ...}
}

PSDisableSerialization <Boolean>

Directs the activity to return "live" (not serialized) objects to the workflow. The resulting objects have methods, as well as properties, but they cannot be saved when a checkpoint is taken.

PSDisableSerializationPreference <Boolean>

Applies the equivalent of the PSDisableSerialization parameter to all activities in a workflow, not just one activity. Adding this parameter is generally not recommended, because a workflow that doesn’t serialize its objects cannot be resumed or persisted. Valid values are True or False.

PSError <PSDataCollection[ErrorRecord]>

Adds error messages from the activity to the specified error record collection, instead of writing the error messages to the console or to the value of the Error property of the workflow job. You can add error messages from multiple activities to the same error record collection object.

To use this activity common parameter, use the New-Object cmdlet to create a PSDataCollection object with a type of ErrorRecord and save the object in a variable. Then, use the variable as the value of the PSError parameter of one or more activities, as shown in the following example.

workflow Test-Workflow
{
   $errorCollection = New-Object -Type System.Management.Automation.PSDataCollection[System.Management.Automation.ErrorRecord]
   InlineScript {\\Server01\Share01\Get-AssetData.ps1} -PSError $errorCollection
   InlineScript {\\Server01\Share01\Set-AssetData.ps1} -PSError $errorCollection
   if ($errorCollection.Count -gt 2) { ...}
}

PSProgress <PSDataCollection[ProgressRecord]>

Adds progress messages from the activity to the specified progress record collection, instead of writing the progress messages to the console or to the value of the Progress property of the workflow job. You can add progress messages from multiple activities to the same progress record collection object.

PSProgressMessage <String>

Specifies a friendly description of the activity. The PSProgressMessage value appears in the progress bar while the workflow runs. When the DisplayName is also included in the command, the progress bar content appears in <DisplayName>:<PSProgressMessage> format.

This parameter is particularly useful for identifying activities in a ForEach -Parallel script block. Without this message, activities in all parallel branches are identified by the same name.

PSRemotingBehavior <RemotingBehavior>

Specifies how remoting is managed when the activity is run on target computers. PowerShell is the default value.

Valid values are:

None: The activity is not run on remote computers.

PowerShell: Windows PowerShell remoting is used to run the activity on target computers.

Custom: The activity supports its own type of remoting. This value is valid when the cmdlet that is being implemented as an activity sets the value of the RemotingCapability attribute to SupportedByCommand and the command includes the ComputerName parameter.

PSRequiredModules <String[]>

Imports the specified modules before running the command. Enter the module names. The modules must be installed on the computer that is running the workflow.

Modules that are installed in a path specified in the PSModulePath environment variable are automatically imported on first use of any command in the module. Use this parameter to import modules that are not in a PSModulePath location.

Because each activity in a workflow runs in its own session, an Import-Module command imports a module only into the session in which it runs. It does not import the module into sessions in which other activities run.

PSVerbose <PSDataCollection[VerboseRecord]>

Adds verbose messages from the activity to the specified verbose record collection, instead of writing the verbose messages to the console or to the value of the Verbose property of the workflow job. You can add verbose messages from multiple activities to the same verbose record collection object.

PSWarning <PSDataCollection[WarningRecord]>

Adds warning messages from the activity to the specified warning record collection, instead of writing the warning messages to the console or to the value of the Warning property of the workflow job. You can add warning messages from multiple activities to the same warning record collection object.

Result

This parameter is valid only in XAML workflows.

UseDefaultInput <Boolean>

Accepts all workflow input as input to the activity by value.

For example, the Get-Process activity in the following sample workflow uses the UseDefaultInput activity common parameter to get input that is passed to the workflow. When you run the workflow with input, that input is used by the activity.

workflow Test-Workflow
{
   Get-Service -UseDefaultInput $True
}
 
PS C:\>Test-Workflow -InputObject WinRm
 
Status Name DisplayName PSComputerName
------ ---- ----------- --------------
Running winrm Windows Remote Management (WS-Manag... localhost