PowerShell Logo Small

about_WorkflowCommonParameters



This is the built-in help made by Microsoft for the document 'about_WorkflowCommonParameters', in PowerShell version 5 - as retrieved from Windows version 'Microsoft Windows Server 2012 R2 Standard' PowerShell help files on 2016-06-24.

For PowerShell version 3 and up, where you have Update-Help, this command was run just before creating the web pages from the help files.

Search powershellhelp.space

TOPIC
about_Workflow_Common_Parameters

SHORT DESCRIPTION
This topic describes the parameters that are valid on all Windows
PowerShell workflow commands. Because the Windows PowerShell engine
adds them to workflows, you can use these parameters on any workflow
and they are automatically enabled on the workflows that you author.

LONG DESCRIPTION
Windows PowerShell Workflow common parameters are a set of cmdlet
parameters that you can use with all Windows PowerShell workflows
and activities. They are added by the Windows PowerShell Workflow
engine, not by the workflow author, and they are automatically
available on every workflow and activity.

All workflow parameters are optional and named (not positional).
They do not take input from the pipeline.

Most of the workflow common parameters have a PS prefix, such as
PSComputerName and PSCredential. The PS-prefixed parameters configure
the connection and the execution environment for the target computers,
also known as "remote nodes."

Many of the workflow common parameters, such as PSAllowRedirection and
AsJob, have names that are similar to parameters used in Windows PowerShell
remoting and background jobs. These parameters work in the same way as
the similarly-named remoting and job parameters, so you can use the
knowledge that you developed in remoting and jobs to manage workflows.

Workflows are introduced in Windows PowerShell 3.0.

PARAMETER DESCRIPTIONS
This section describes the workflow common parameters.

-AsJob <SwitchParameter>
Runs the workflow as a workflow job. The workflow command
immediately returns an object that represents a parent job. The
parent job contains the child jobs that are running on each of
the target computers. To manage the job, use the Job
cmdlets. To get the job results, use the Receive-Job cmdlet
(http://go.microsoft.com/fwlink/?LinkID=113372).

-JobName <String>
Specifies a friendly name for the workflow job. By default, jobs are
named "Job<n>", where <n> is an ordinal number.

If you use the JobName parameter in a workflow command, the workflow is run
as a job and the workflow command returns a job object, even if you do not
include the AsJob parameter in the command.

For more information about Windows PowerShell background jobs, see
about_Jobs (http://go.microsoft.com/fwlink/?LinkID=113251).


-PSAllowRedirection <SwitchParameter>
Allows redirection of the connection to the target computers.

When you use the PSConnectionURI parameter, the remote destination can
return an instruction to redirect to a different URI. By default, Windows
PowerShell does not redirect connections, but you can use the
PSAllowRedirection parameter to allow redirection of the connection to the
target computer.

You can also limit the number of times that the connection is redirected by
setting the MaximumConnectionRedirectionCount property of the
$PSSessionOption preference variable, or the
MaximumConnectionRedirectionCount property of the value of the
PSSessionOption parameter. The default value is 5. For more information,
see the description of the PSSessionOption parameter and
the New-PSSessionOption cmdlet
(http://go.microsoft.com/fwlink/?LinkID=135237).


-PSApplicationName <String>
Specifies the application name segment of the connection URI that is used
to connect to the target computers. Use this parameter to specify the
application name when you are not using the ConnectionURI parameter in the
command.

The default value is the value of the $PSSessionApplicationName preference
variable on the local computer. If this preference variable is not defined,
the default value is WSMAN. This value is appropriate for most uses. For
more information, see about_Preference_Variables
(http://go.microsoft.com/fwlink/?LinkID=113248).

The WinRM service uses the application name to select a listener to service
the connection request. The value of this parameter should match the value
of the URLPrefix property of a listener on the remote computer.


-PSAuthentication <AuthenticationMechanism>
Specifies the mechanism that is used to authenticate the user's credentials
when connecting to the target computers. Valid values are Default, Basic,
Credssp, Digest, Kerberos, Negotiate, and NegotiateWithImplicitCredential.
The default value is Default.

For information about the values of this parameter, see the description of
the System.Management.Automation.Runspaces.AuthenticationMechanism
enumeration in MSDN.

CAUTION: Credential Security Service Provider (CredSSP) authentication, in
which the user's credentials are passed to a remote computer to be
authenticated, is designed for commands that require authentication on more
than one resource, such as accessing a remote network share. This mechanism
increases the security risk of the remote operation. If the remote computer
is compromised, the credentials that are passed to it can be used to control
the network session.


-PSAuthenticationLevel <AuthenticationLevel>
Specifies the authentication level for the connections to
the target computers. The default value is Default.

Valid values are:

Unchanged: The authentication level is the same as the previous
command.
Default: Windows Authentication.
None: No COM authentication.


Connect: Connect-level COM authentication.
Call: Call-level COM authentication.
Packet: Packet-level COM authentication.
PacketIntegrity: Packet Integrity-level COM authentication.
PacketPrivacy: Packet Privacy-level COM authentication.


-PSCertificateThumbprint <String>
Specifies the digital public key certificate (X509) of a user account that
has permission to perform this action. Enter the certificate thumbprint of
the certificate.

Certificates are used in client certificate-based authentication. They can
only be mapped to local user accounts; they do not work with domain
accounts.

To get a certificate, use the Get-Item
(http://go.microsoft.com/fwlink/?LinkID=113319) or
Get-ChildItem (http://go.microsoft.com/fwlink/?LinkID=113308) cmdlets
in the Windows PowerShell Cert: drive.


-PSComputerName <String[]>
Specifies the list of computers that are the target nodes of the workflow.
Commands or activities in a workflow are run on the computers that are
specified by using this parameter. The default is the local computer.

Type the NETBIOS name, IP address, or fully-qualified domain name of one or
more computers in a comma-separated list. To specify the local computer,
type the computer name, "localhost", or a dot (.).

To include the local computer in the value of the PSComputerName parameter,
open Windows PowerShell with the "Run as administrator" option.

If this parameter is omitted from the command, or it value is $null or an
empty string, the workflow target is the local computer and Windows
PowerShell remoting is not used to run the command.

To use an IP address in the value of the ComputerName parameter, the
command must include the PSCredential parameter. Also, the computer must be
configured for HTTPS transport or the IP address of the remote computer
must be included in the WinRM TrustedHosts list on the local computer. For
instructions for adding a computer name to the TrustedHosts list, see "How
to Add a Computer to the Trusted Host List" in about_Remote_Troubleshooting
(http://go.microsoft.com/fwlink/?LinkID=135188).


-PSConfigurationName <String>
Specifies the session configurations that are used to configure sessions on
the target computers. Enter a session configuration on the target computers
(not the workflow server computer). The default is
Microsoft.PowerShell.Workflow.


-PSConnectionRetryCount <UInt>
Specifies the maximum number of attempts to connect to each target computer
if the first connection attempt fails. Enter a number between 1 and
4,294,967,295 (UInt.MaxValue). The default value, zero (0), represents no
retry attempts.

-PSConnectionRetryIntervalSec <UInt>
Specifies the delay between connection retry attempts in seconds. The
default value is zero (0). This parameter is valid only when the value of
PSConnectionRetryCount is at least 1.


-PSConnectionURI <System.Uri>
Specifies a Uniform Resource Identifier (URI) that defines the connection
endpoint for the workflow on the target computer. The URI must be fully
qualified.

The format of this string is as follows:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

The default value is http://localhost:5985/WSMAN.

If you do not specify a PSConnectionURI, you can use the PSUseSSL,
PSComputerName, PSPort, and PSApplicationName parameters to specify the
PSConnectionURI values.

Valid values for the Transport segment of the URI are HTTP and HTTPS. If
you specify a connection URI with a Transport segment, but do not specify a
port, the session is created with standards ports: 80 for HTTP and 443 for
HTTPS. To use the default ports for Windows PowerShell remoting, specify
port 5985 for HTTP or 5986 for HTTPS.


-PSCredential <PSCredential>
Specifies a user account that has permission to run a workflow on the
target computer. The default is the current user. This parameter is valid
only when the PSComputerName parameter is included in the command.

Type a user name, such as "User01" or "Domain01\User01", or enter a
variable that contains a PSCredential object, such as one that the
Get-Credential cmdlet returns. If you enter only a user name, you will be
prompted for a password.


-PSElapsedTimeoutSec <UInt32>
Determines how long the workflow and all related resources are maintained
in the system. When the timeout expires, the workflow is deleted, even if
it is still processing. Enter a value between 10 and 4,294,967,295. The
default value, 0 (zero), means that there is no elapsed timeout.


-PSParameterCollection <Hashtable[]>
Specifies different workflow common parameter values for different target
computers.

Enter a comma-separated list of hash tables with one hash table for each
target computer. In each hash table, the first key is PSComputerName and
its value is the name of the target computer. Wildcard characters are
permitted in the computer name. For the remaining keys in the hash table,
the key is the parameter name and the value is the parameter value.

For example:
-PSParameterCollection @{PSComputerName="Server01";
PSElapsedTimeoutSec=10; PSConnectionRetryCount=6},
@{PSComputerName="*"; PSElapsedTimeoutSec=20}




-PSPersist <Boolean>
Adds checkpoints to the workflow, in addition to any
checkpoints that are specified in the workflow.

This parameter cannot suppress the checkpoints
in a workflow, such as those specified by using the
PSPersist activity common parameter, the Checkpoint-Workflow
activity, or the $PSPersistPreference variable.

A "checkpoint" or "persistence point" is a snapshot of the
workflow state and data that is captured while the workflow
runs and is saved to a persistence store on disk or in a SQL
database. Windows PowerShell Workflow uses the saved data to
resume a suspended or interrupted workflow from the last
persistence point, rather than to restart the workflow.

Valid values:

-- (Default) If you omit this parameter, a checkpoint is
added to the beginning and end of the workflow, in addition
to any checkpoints that are specified in the workflow.

-- $True. Adds a checkpoint to the beginning and end of the
workflow and a checkpoint after each activity, in addition
to any checkpoints that are specified in the workflow.

-- $False. No checkpoints are added. Checkpoints are taken
only when specified in the workflow.



-PSPort <Int32>
Specifies the network port on the target computers. The default ports are
5985 (the WinRM port for HTTP) and 5986 (the WinRM port for HTTPS).

Do not use the PSPort parameter unless you must. The port set in the
command applies to all computers or sessions on which the command runs. An
alternate port setting might prevent the command from running on all
computers. Before using an alternate port, you must configure the WinRM
listener on the remote computer to listen at that port.


-PSPrivateMetadata <Hashtable>
Provides customized information to workflow jobs. Enter a hash table.
The keys and values are customized for each workflow. For information
about the private metadata of a workflow, see the help topic for the
workflow.

This parameter is not processed by the Windows PowerShell Workflow
engine. Instead, the engine passes the hash table directly to the
workflow.


-PSRunningTimeoutSec <UInt32>
Specifies the running time of the workflow in seconds, excluding any
time that the workflow is suspended. If workflow execution is not
complete when the time expires, the Windows PowerShell Workflow engine
forcibly stops the execution of the workflow.


-PSSessionOption <PSSessionOption>
Sets advanced options for the sessions to the target computers. Enter
a PSSessionOption object, such as one that you create by using the
New-PSSessionOption cmdlet.

The default values for the session options are determined by the value
of the $PSSessionOption preference variable, if it is set. Otherwise, the
session uses the values specified in the session configuration.

For a description of the session options, including the default values,
see the help topic for the New-PSSessionOption cmdlet
(http://go.microsoft.com/fwlink/?LinkID=144305). For information about the $PSSessionOption preference variable, see about_Preference_Variables
(http://go.microsoft.com/fwlink/?LinkID=113248).


-PSUseSSL <SwitchParameter>
Uses the Secure Sockets Layer (SSL) protocol to establish a connection
to the target computer. By default, SSL is not used.

WS-Management encrypts all Windows PowerShell content transmitted over
the network. UseSSL is an additional protection that sends the data
across an HTTPS, instead of HTTP. If you use this parameter, but SSL
is not available on the port used for the command, the command fails.


KEYWORDS
about_Workflow_Common_Parameters
about_Workflow_CommonParameters

SEE ALSO
about_ActivityCommonParameters
about_Workflows
Invoke-AsWorkflow
New-PSWorkflowExecutionOption
New-PSWorkflowSession