Pages allow you to create basic websites that do not require any coding of the user interface. You can drag and drop UI components on to the designer and set properties of each component. Components can interact with APIs and Scripts that are defined within Universal.

Adding a Page

To add a page, navigate to User Interfaces \ Pages within the admin console. Click the Create New Page button to create a page.

The name of the page will also be the URL used to access the page.

Pages can take advantage of role based access. You can turn on authentication for a page and limit the access to the page to users based on role. This feature requires a license.

Editing a Page

To edit the content of the page, you can view the page as an administrator. When you view the page, you will have access to an edit button for managing the components and layout of the page.

Adding a Component

To add a component, click the Toolbox button and select the component to add. Properties for a component can be set by clicking the properties button on the component and editing the required and optional properties.

Layouts

Layouts are setup by resizing and dragging components around the designer surface. Layouts are responsive. If you want to setup layouts for smaller screens, reduce the width of your window and setup a new layout.

Invoking Scripts and APIs

Certain components can interact with scripts or API endpoints. These include buttons, forms, statistics and tables. You can configure the script or API that is invoked as well as the parameters that are passed to those targets.

This example uses a script to populate a table.

This example invokes a script when a button is clicked.

Grouping Pages

Grouping pages will create nested navigation within the page section. Select a group in the page properties. Matching pages will be displayed in that group.

Page URLs

By default, the page URL will be the Name of the page. So for example, if the page's name was Services the URL will be /Services.

You can customize the URL in the page properties.

Default URL

You can change the default URL of the PowerShell Universal instance by setting the page URL to / . When users login or visit the server name directly, they will not be directed to /admin but rather the page defined with /.

Configuration Files

Pages are stored as XML. Unlike dashboards, they do not allow for direct programmatic configuration. The layout and components are static but can interact with APIs and scripts.

<?xml version="1.0" encoding="utf-8"?>
<Page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" Name="Page1" Description="This is a great page. " Authenticated="false" Icon="SkypeOutlined" ShowInNavigation="false">
  <Components>
    <Button Id="c2ca3c4a-d729-40cd-818e-528c2991ff10" Text="Button" Icon="ContactsFilled" ToastOnSuccess="true" ToastOnFailure="true" RefreshComponents="false">
      <Target Name="Simple.ps1" Type="script">
        <Parameters />
      </Target>
    </Button>
    <Form Id="a7bf92a3-4d44-4db0-88ab-d24c5992b9b1" Title="Form" Description="asdfadsf" RefreshComponents="false">
      <Target Name="Simple.ps1" Type="script">
        <Fields>
          <Field Name="Nice" Type="textbox" Required="false" />
        </Fields>
      </Target>
    </Form>
    <Table Id="9dc0c2b4-7d51-48bd-9676-72a480e44126" Title="Table" DataSourceType="api" DataSource="/test">
      <Columns />
    </Table>
    <Statistic Id="932c6746-d810-49a3-b3f1-676672c82267" Title="Statistic" DataSourceType="api" DataSource="/random" Precision="0" AutoReload="true" AutoReloadSeconds="4" />
    <Text Id="4acc622e-7bfa-475a-b9e8-5382735c8f54" Value="What the heck!!!?????" Code="false" Copyable="false" Ellipsis="false" Keyboard="false" Marked="false" Bold="false" Italic="false" type="warning" Underline="false" />
    <Statistic Id="071e2a46-55ee-49f4-bfab-6a3ec26e5089" Title="Statistic" DataSourceType="api" DataSource="/random" Prefix="asdfasdfa" Suffix="asdfsafas" Precision="0" AutoReload="true" AutoReloadSeconds="15" />
    <Title Id="2411846c-6d95-4a58-af4b-fe65e882acff" Value="Title" Code="true" Copyable="false" Ellipsis="false" Keyboard="false" Marked="false" Bold="false" Italic="false" Underline="false" Level="2" />
    <Paragraph Id="c99786a9-4e49-4ef0-a4b7-33ec5a5ea9b4" Value="Paragraph" Code="true" Copyable="false" Ellipsis="false" Keyboard="false" Marked="false" Bold="false" Italic="false" type="success" Underline="false" />
  </Components>
  <Layout>
    <Lg>
      <LayoutItem Id="c2ca3c4a-d729-40cd-818e-528c2991ff10" X="0" Y="0" W="4" H="4" />
      <LayoutItem Id="a7bf92a3-4d44-4db0-88ab-d24c5992b9b1" X="0" Y="35" W="14" H="12" />
      <LayoutItem Id="9dc0c2b4-7d51-48bd-9676-72a480e44126" X="0" Y="14" W="50" H="21" />
      <LayoutItem Id="932c6746-d810-49a3-b3f1-676672c82267" X="21" Y="0" W="29" H="7" />
      <LayoutItem Id="4acc622e-7bfa-475a-b9e8-5382735c8f54" X="5" Y="0" W="16" H="7" />
      <LayoutItem Id="071e2a46-55ee-49f4-bfab-6a3ec26e5089" X="36" Y="7" W="14" H="7" />
      <LayoutItem Id="2411846c-6d95-4a58-af4b-fe65e882acff" X="14" Y="35" W="15" H="5" />
      <LayoutItem Id="c99786a9-4e49-4ef0-a4b7-33ec5a5ea9b4" X="14" Y="40" W="27" H="4" />
    </Lg>
  </Layout>
  <AccessControls>All</AccessControls>
</Page>

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.

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.

1..10 | % { 
    Write-Progress -Activity "Processing..." -PercentComplete ($_ * 10)
    Start-Sleep 1
}

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

Read-Host "Enter some feedback"

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 = $Body | ConvertFrom-Json
$Fields.txtName
$Fields.txtLastName

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.

param(
    $FirstName,
    $LastName
)

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.

$Fields = $Body | ConvertFrom-Json
$Fields.FirstName
$Fields.LastName

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

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

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.

$Fields = $Body | ConvertFrom-Json
if ($Fields.Name -eq 'Adam')
{
     New-PSUValidationResult -Success
}
else 
{
     New-PSUValidationResult -ErrorMessage 'Incorrect name'
}

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.

@{
    column = @{
       type = "link"
       url = "https://ironmansoftware.com"
       text = "Ironman Software"
    }
}

Images

You can include images by using a hashtable with the image type and specifying any valid img HTML attributes.

@{
    column = @{
       type = "image"
       src = "https://ironmansoftware.com/logo.png"
       height = "10px"
    }
}

Display a chart from an API

An API that provides data to a chart needs to return a single number between 0.0 and 1.00.

This example returns a random percentage.

Select an API from the list of available APIs.

The liquid chart will display the value.

Display a chart from a Script

You can display a liquid chart with data from a script. You should return a single value between 0.0 and 1.00.

This script we are executing in this example returns a random percentage.

Select the script as the data source.

The chart will display based on the data returned.

Properties

Cards contain a title and content text.

Data Source

You can load data from an API endpoint or job. The data properties will be available as variables within your text.

For example, if you may have an endpoint that returns data like the following.

You could then use the following variables within the title and content text.

About

Line charts can retrieve output from scripts and APIs to display the data in a chart.‌

Display Data from an API

You will need to return an array of JSON objects from your API in order to use a bar chart. An example would be returning a list of hashtables serialized to JSON.

In this example, you would configure the data source to an API and select your API endpoint.

You would then specify Name as the X axis and Value as the Y axis.​​

The resulting chart contains the data from the API. Each time the page is loaded, the API is called.​

Display Data from a Script

You will need to return PSCustomObjects, objects or hashtables from your script in order to display a chart from a script.

You will need to set the data source to script and select the script you want to retrieve data for.​

You will need to set the Y and X axis to the properties of the object returned from the script.​‌

The chart will appear on the page like this. Loading the page will not call the script again. It will load the result of the last time the script ran.​

‌

Properties

Images are simple components that just display an image on the page.

Invoke a Script with a Button

You can invoke a script with a button. This will allow you to specify arguments, environment and run as credentials for the script.

Set the target of the button to script and select the script you would like to use. You can then select the environment and run as credentials. Finally, specify parameters to pass to the script.

Clicking the button will run the script and show a toast notification after the click.

Invoke an API with a Button

Set the target to API and select the endpoint that you want to invoke. The endpoint must be a POST endpoint. Parameters can be specified. Parameters will be passed as part of a JSON object.

Customize the Button

Buttons support customizing the text and icon shown within the button.

Properties

About

Bar charts can retrieve output from scripts and APIs to display the data in a chart.

Display Data from an API

You will need to return an array of JSON objects from your API in order to use a bar chart. An example would be returning a list of hashtables serialized to JSON.

In this example, you would configure the data source to an API and select your API endpoint. You would then specify Name as the Y axis and Value as the X axis.

The resulting chart contains the data from the API. Each time the page is loaded, the API is called.

Display Data from a Script

You will need to return PSCustomObjects, objects or hashtables from your script in order to display a chart from a script.

You will need to set the data source to script and select the script you want to retrieve data for.

You will need to set the Y and X axis to the properties of the object returned from the script.

The chart will appear on the page like this. Loading the page will not call the script again. It will load the result of the last time the script ran.

Properties

Properties

Iframes provide the ability to nest another website within the page. The is especially useful if you wish to embed a dashboard within a page.

Embed a Dashboard in a Page

To embed a dashboard in a page, assume we have a dashboard that is defined such as this. This dashboard returns a table of services. It uses the -Blank parameter on New-UDPage to remove the header. This dashboard is configured with a base URL of /embed

New-UDDashboard -Title "Services" -Pages @(
    New-UDPage -Name 'Table' -Content {
        New-UDTable -Data (Get-Service)
    } -Blank
)

Add a new IFrame component to the page and within the properties of the page, set the URL to the base URL of the dashboard.

When the page loads, it will load the dashboard and display it within the page.

Limitations

When you embed multiple dashboards within a page they will be treated an individual dashboards and will not communicate event handling code. This means that display toasts and modals will appear within the IFrame and not in the parent code.

Paragraphs display text with different styles depending on properties.

Properties

Tables allow you to display the output of APIs and scripts in rows and columns. Each object returned by the data source will create a row within the table. You can customize the columns of the table.

Selecting a Data Source

Both APIs and Scripts are supported by tables. When selecting an API, the API will be executed each time the page is loaded. When selecting a script, the last job run of the script will provide the output.

When columns are not defined, all the properties of the objects will be displayed.

Customizing Columns

You can customize the columns that are selected when displaying data.

Basic

Basic columns will select the properties defined and display the text.

In this example, we are selecting the name and service type from a call to Get-Service.

The resulting table only has these two properties displayed.

Buttons

Buttons can be added to columns to provide functionality for each row. Clicking the button will provide the target with the row data via the $InputObject parameter.

Numeric statistics can return data from scripts and APIs and display values with some amount of formatting options.

Display a statistic from an API

APIs should return a single value to display as a statistic. An example API could look something like this.

You can then select the API under the data source tab.

Each time the page is loaded, the API is called and the random value is shown.

Display a statistic from a Script

Statistics shown from scripts will display the value return by the last job run for the script. Loading the page will not run the script again.

We will use this script as an example.

Select the script on the data source tab.

The statistic will be shown on the page based on the output of the script. You'll notice that refreshing the page does not change the value of the statistic unless the job is run again.

Customizing the Statistic

You can customize features such as the prefix, suffix, precision and whether to auto-reload the statistic on an interval.

Properties

Variables allow you modify the functionality of a page depending on factors such as the user name or URL route. Variable-based routes allow you to create dynamic pages based on the URL the user is visiting.

Variables that are defined with Platform \ Variables will also be available to pages.

Viewing Variables

Variables can be viewed when editing a page. To view variables, click Edit and then Variables.

A drawer will appear with the variables for the current page.

Using Variables

Variables can be used anywhere you can type a property value. For example, if you have an Alert, you could use the $pagename variable within the title property.

When the page is rendered, the variable will be replaced.

You can also use variables within targets and data sources. This allows you to call URLs that will change based on the variable.

You can also use variables to provide hidden input fields to APIs and scripts.

Page Variables

You can load additional data when the page is loading by providing a data source to in the page properties. The data source should return a single PSCustomObject or hashtable. The properties of the object will become variables within the page.

For example, assume you have an API that returns the following hashtable.

@{
    Name = "My Name"
    Title = "My Title"
}

Selecting this API as the data source for the page would then create the variables $Name and $Title within the page.

You can also use Route Variables within the data source to customize which API is called based on the route visited.

Route Variables

Route variables need to be defined when creating the URL for the page. Each section of the URL that starts with : will be treated as a variable.

For example, this page defines a single route variable.

Within the page, the route variables will appear within the variable drawer.