Form
Forms that can be invoked to call scripts and APIs.
Invoke a Script with a Form
Forms can be used to invoke scripts. The form component ties directly into the automation features to allow for the display of output, progress and respond to feedback.
To invoke a script, select the target of Script and the script you'd like to invoke.
![](https://docs.powershelluniversal.com/~gitbook/image?url=https%3A%2F%2F620394196-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-legacy-files%2Fo%2Fassets%252F-M6jY7sXTmhiAIMGYw_m%252F-Mj0WtCfo4yQm6ntZDnL%252F-Mj0XRQshof1MttoiwNE%252Fimage.png%3Falt%3Dmedia%26token%3Df8f1c4d3-940c-4be3-981e-23dfbeb65e20&width=768&dpr=4&quality=100&sign=e90d2487&sv=1)
By default, no output or progress will be shown. The form will simply consist of a Save button.
If the script succeeds, you'll see a success result. If it fails, it will return a failure result.
Viewing Output
You can view the output as the script runs by using the Show Output check box.
Viewing Progress
To view the output of cmdlets like Write-Progress
, you can use the Show Progress check box. While the script executes, you'll see the progress messages.
The script in this example simply shows progress.
Viewing Output after the script has run
To view the output of the script after it has run, you can use the Result Type drop down. The Text result type, will display output as text.
To view output as a table, select the result type of Table.
Responding to Feedback
Scripts that request feedback will prompt the user to enter more information.
An example of a script that may request feedback is one that uses Read-Host
Invoke an API with a Form
Invoking an API with a form can be done by selecting API from the Target Type and then selecting the API endpoint you wish to call.
API endpoints do not support progress, feedback, or output while running the API. They do support returning results as text or tables. APIs that return 200 will show a Success result and other status codes will return Failure.
Fields provided to an API endpoint will be sent as a single JSON object with properties for each field.
For example, if you had a form with a field named txtName and txtLastName, you could access those properties by deserializing the $Body
variable.
Fields
You can specify fields for each form. Currently forms support text boxes, checkboxes and hidden values. Fields can have a tooltip description and marked as required.
Fields in Scripts
Fields are provided to scripts as parameters. You can use a param
block to capture these field values.
For example, if you had a FirstName and LastName field, you would define the following param block in your script.
Fields in APIs
Fields are provided to APIs as a JSON body to the POST endpoint. Each field will be a property of the JSON object passed to the API.
Field Types
Checkbox
The checkbox field provides a checkbox the user can select and $true
or $false
will be sent to the target.
Date
Allows the user to select a date. The value will be passed as a string.
Hidden
Hidden fields provide a value to the target that is not shown to the user. The value will be a string.
Number
Allows the user to select a number. The value will be passed as an integer.
Password
Available in PowerShell Universal 2.5 or later
A textbox with a mask to prevent you from seeing the characters typed.
Select
Allows the user to select an option from a drop down. The value will be passed as a string.
Switch
Allows the user to provide a true or false. The value will be passed as a boolean.
Textbox
The textbox field allows the user to enter any text into the field and it will be submitted to the target. The value will be a string.
Time
Allows the user to select a time. The value is passed as a string.
Rating
Allows the user to select a rating between 0 and 5. The value is passed as a float.
Text
You can customize the text of numerous features of a field including the success and failure text, waiting on feedback text and button text.
Validation
Available in PowerShell Universal 2.9 or later.
You can validate a form by selecting an API endpoint from the Validation API field. The validation endpoint must be a POST method. Use the New-PSUValidationResult
parameter to return whether the validation is successful.
Smart Properties
Smart properties are hashtables included in the data returned from APIs and Scripts. Tables will automatically translate these hashtables to rendered components when displaying them.
Links
You can include links by using a hashtable with the link
type and providing a url
and text
property.
Images
You can include images by using a hashtable with the image
type and specifying any valid img
HTML attributes.
Last updated