Action Step Type: Windows Command
The Windows command action step type executes a command on the client device. This step type can be defined to wait for the command to complete execution, to capture the return code of the external process, and to display an error message based on a non-zero return code. The Windows command step type is also used to display external files on the client device by setting the full path and file name as the command. This will result in the file being opened by the default application for the file type.
The command executed by the Windows command step must include the full path and file name of the executable to be run or file to be opened. When waiting for the command to return, the step will block action execution until the command completes, or until the defined wait period expires. An expired wait periods is treated as a timeout error by the Windows command step.
Additional error conditions include a non-zero return value by the command to the operating system. If a non-zero value is returned, the Windows command step will treat this as an error condition.
The timeout and the error conditions each have associated messages that may be displayed as defined in the Windows command step. This step type allows for providing the user with the option to continue or cancel the parent action’s execution. Alternately, the step can be defined to not allow action execution to continue, or to not allow the user to cancel the action regardless of the error.
- Step Name: Contains the unique internal name for the step definition. This value must be unique among all step definitions within the same action.
- Command Line: This attribute contains the command to execute or pass to the operating system. This may be a string value set within the attribute field, or it may be returned from a rule definition. The command may contain one or more format strings consisting of the property names for the object passed to the command step form the action. These format strings take the form %propertyName. Note for properties of type External Data, the format string will return the full path and file name of the file referenced by the property. If a rule is referenced for the command, it may not return a string containing format strings. The rule is evaluated in the context of the object passed to the Windows command step by the action. The rule is expected to return a string value.
- Wait: This attribute specifies whether the Windows command step should wait for the command it executes to return. The default is to not wait, in which case the command line will be executed and the step will end execution. The timeout message will not be displayed. The only error captured by the step will be if the command line cannot be executed by the operating system, e.g. if the command referenced does not exist, or the file cannot be found. When the Wait attribute is set to true, the Wait Period Limit attribute is enabled.
- Wait Period Limit: This attribute is enabled only when the Wait attribute is set to true. In this case, the Wait Period Limit specifies the duration of time the Windows command step should wait for the command it executes to complete processing and return. If this duration is exceeded without a return from the command, the step’s defined Timeout Message will be displayed.
- Error Message: This attribute contains the text to display when an error occurs. This may be displayed if the command fails to execute, or if the command returns a non-zero value after completing execution.
- Timeout Message: This attribute contains the text to display when the Wait Period Limit is exceeded without a return from the command executed by the step. This behavior also requires the Wait attribute to be set to true.
- Continue Label: This attribute contains the label for the Continue button that is a part of the dialog that displays the Error Message and Timeout Message. At run time, when this button is clicked the Windows command step will complete execution and the action will execute the next defined step. This button may be hidden by selecting the option Not Allowed, preventing the user from allowing the action to continue the action’s execution when an error occurs executing the defined command.
- Cancel Label: This attribute contains the label for the Cancel button that is a part of the dialog that displays the Error Message and Timeout Message. At run time, when this button is clicked the Windows command step will complete execution and the parent action will be canceled. This button may be hidden by selecting the option Not Allowed, preventing the user from cancelling the action when an error occurs executing the defined command.