Form
Forms that can be invoked to call scripts and APIs.
Last updated
Forms that can be invoked to call scripts and APIs.
Last updated
Copyright 2024 Ironman Software
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.
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.
You can view the output as the script runs by using the Show Output check box.
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.
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.
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
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.
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 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 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.
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 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.
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.
You can customize the text of numerous features of a field including the success and failure text, waiting on feedback text and button text.
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.
