README.md

# MasterPromptPS
MasterPromptPS is a Light Touch build menu generator. Values selected in the form are stored as SCCM task sequence variables.

[[_TOC_]]
  
![](images/sample.png)

## Usage

`MasterPromptPS.ps1 [[-SettingsFile] ] [-HideProgressBar] [-Test] []`

### PARAMETERS
    -SettingsFile 
        Specifies the json file with the settings and menu definition.

        Required?                    false
        Position?                    1
        Default value                "$PSScriptRoot\MasterPromptPS.json"
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -HideProgressBar []
        Hide the SCCM task sequence progress bar.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Test []
        Test GUI generation only, do not attempt to create Task Sequence variables.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  false

    
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters [https:/go.microsoft.com/fwlink/?LinkID=113216](https:/go.microsoft.com/fwlink/?LinkID=113216).

### Examples

    -------------------------- EXAMPLE 1 --------------------------

    C:\ PS>.\MasterPromptPS

    Display a prompt as defined by the MasterPromptPS.json file (default) located in the current directory, store results in task sequence variables




    -------------------------- EXAMPLE 2 --------------------------

    C:\ PS>.\MasterPromptPS -HideProgressBar

    Hide the SCCM progress bar, then display a prompt as defined by the MasterPromptPS.json file (default) located in the current directory, store results in
    task sequence variables




    -------------------------- EXAMPLE 3 --------------------------

    C:\ PS>.\MasterPromptPS -SettingsFile .\server.json

    Display a prompt as defiend by .\server.json, store results in task sequence variables

## Settings File
Settings and menu definition are stored in a .json file. If a file named MasterPromptPS.json is found in the current directory, MasterPromptPS will use that.

MasterPromptPS supports the following field types:

* Informational labels using WMI as the data source
* Text fields with max length parameter and WMI data as source for default text
* Dropdown lists and cascade dropdown lists
* Masked password fields which store data as encrypted text
* Checkboxes and Radio buttons

### Global Settings

The settings file contains a number of global properties and settings:

* **width**: The width of the dialog box
* **height**: The height
* **rowheight**: The height of each field row
* **labelcolumnX**: The initial horizontal position of the label column in pixels 
* **fieldcolumnX**: The initial horizontal position of the field column in pixels
* **rowy**: The vertical position of the first field row in pixels
* **textboxsize**: The length of text boxes, password fields and select fields in pixels
* **radiobuttonwidth**: The width of radio button labels in pixels
* **title**: The window title
* **header**: Text to appear beside the logo in the header of the form
* **footer**: Text to appear in the footer of the form (not currently enabled)
* **errorcolor**: Set the background of text, password and select field if they do not validate

### Field Types

#### Common Parameters

All field types require the following three parameters

* **type**: [info | text | password | select | check | radio]
* **name**: The name of the variable to store the resulting selection; **NOTE**: select and radio also store the value of the label in %VAR%_label named task sequence variables 
* **label**: The label to display beside the field

#### info

* **query**: A WQL query as data source

#### text

* **required**: [ true | false] specifies if the field is mandatory
* **default**: a WQL query to provide a default value
* **maxLength**: the maximum allowed length of the field

#### password

* **required**: [ true | false] specifies if the field is mandatory

#### check

* **checked**: specifies if the field is checked by default

#### radio

* **default**: specifies the default selection
* **options**: a json object array of value/label pairs to define radio buttons

#### select

* **options**: a json object array of value/label pairs to define dropdown menu options

#### cascade

* **dependsOn**: The select field to base the selection options on
* **options**: a nested json object array with select values and sub options per dependent selection menu item

### Example Settings File

```
{
	"__version__": "0.1.3",
	"__description__": "Sample settings file",
	"width": 500,
	"height": 555,
	"rowheight": 25,
	"labelcolumnX": 10,
	"fieldcolumnX": 150,
	"rowy": 90,
	"textboxsize": 320,
	"radiobuttonwidth": 80,
	"title": "Build Prompt",
	"header": "",
	"footer": "Warning: This system is about to be rebuilt resulting in the loss of all data. If you DO NOT wish to proceed, immediately power off and remove any thumb drives.",
	"errorcolor": "#FFFF77",
	"headercolor": "#47154A",
	"fields": [{
			"type": "info",
			"name": "INFIPADDRESS",
			"label": "IP Address",
			"query": "SELECT IPAddress FROM Win32_NetworkAdapterConfiguration WHERE IPEnabled = True AND DHCPEnabled = True"
		},
		{
			"type": "info",
			"name": "INFMACADDRESS",
			"label": "MAC Address",
			"query": "SELECT MACAddress FROM Win32_NetworkAdapterConfiguration WHERE IPEnabled = True AND DHCPEnabled = True"
		},
		{
			"type": "text",
			"name": "OSDComputerName",
			"label": "Computer Name",
			"default": "SELECT SerialNumber FROM Win32_BIOS",
			"required": true,
			"maxLength": 15
		},
		{
			"type": "select",
			"name": "BUILD",
			"label": "Build",
			"options": {
				"Standard": "Standard",
				"Finance": "Finance",
				"CaseStudy": "Case Study"
			}
		},
		{
			"type": "password",
			"name": "PASSWORD",
			"label": "Password",
			"required": true
		},
		{
			"type": "check",
			"name": "OPTION1",
			"label": "Option 1?",
			"checked": true
		},
		{
			"type": "radio",
			"name": "RADIOEX",
			"label": "Radio Example",
			"default": "standard",
			"options": {
				"Standard": "Standard",
				"Finance": "Finance",
				"CaseStudy": "Case Study"
			
			}
		},
		{
			"type": "radio",
			"name": "RADIOEX2",
			"label": "Radio Example 2",
			"default": "rexo2",
			"options": {
				"rexo1": "Rex Opt 1",
				"rexo2": "Rex Opt 2",
				"rexo3": "Rex Opt 3"
			
			}
		},
		{
			"type": "cascade",
			"name": "CASCADEEX",
			"label": "Cascade Example",
			"dependsOn": "BUILD",
			"options": {
				"Standard": {
					"std1": "Std 1",
					"std2": "Std 2",
					"std3": "Std 3"
				},
				"Finance": {
					"fin1": "Fin 1",
					"fin2": "Fin 2",
					"fin3": "Fin 3"
				},
				"CaseStudy": {
					"cs1": "CS 1",
					"cs2": "CS 2",
					"cs3": "CS 3"
				}
			}
		}
	]
}
```

## Validation

Text, password and select fields are validated for non empty, non null values by default.

### Custom Validation

To add custom validation, add a PowerShell script to the customvalidators folder named the same as the Text or Password fields you wish to validate.
The script must return a boolean value indicating if the field is valid and display any corrective messages if required.

Custom validation scripts can also be used as a warning only (i.e. will not halt processing) if all exit paths are set to $True.

#### Example Script

This script will confirm if the OSDComputerName field begins with any of a set of allowed prefixes. If not it displays a popup message and returns boolean $False.

```
Param(
    [string]$Value
)

$Allowed = @(
    "BJ",
	"DB",
	"DU",
	"FL",
	"HK",
	"HU",
	"LN",
	"MA",
	"MB",
	"MP",
	"NY",
	"PR",
	"SF",
	"SG",
	"SH",
	"SL",
	"SY",
	"TK",
	"UE"
)

$Buttons = [System.Windows.Forms.MessageBoxButtons]::OK
$Icon = [System.Windows.Forms.MessageBoxIcon]::Error# <-- Change to' Warning' to use as a 'warning' only prompt
$Message = "The computer name must begin with one of the following: $($Allowed -join ', ')"
$Title = "Error"


If(($Value[0..1] -join '').ToLower() -notin $Allowed){
    [System.Windows.Forms.MessageBox]::Show($Message,$Title,$Buttons,$Icon) | Out-Null
    $false # <-- Change to $true to use as a 'warning' only prompt
}else{
    $true
}
```

## Known Issues

* ~~This script currently only supports 1 set of radio buttons per settings file.~~
* ~~This script will error if executed outside of an SCCM task sequence environment. The dialog can still be previewed~~ You can now use the -Test Parameter to test GUI creation when operating outside of a Task Sequence environment.

## To-Do

* ~~Add cascading select menus~~
* ~~Add custom validation~~
* ~~Add radio button groups~~
* ~~Add footer field~~
* Add datafile validation (added version validation only for starters)

Document Actions