Create UI Definition

Create and test a UI definition file.

Introduction

When a user deploys your Azure Application via the portal, they will walk through the creation experience. As part of the process, the user will be asked to provide a number of parameters related to the deployment (eg the target subscription, resource group, location).

It is possible for publishers to modify and extend the core application creation experience through a file called createUiDefinition.json. This file must be included as part of every Azure Application offer. The Azure portal uses it to define the user interface when creating an Azure application.

Create a createUiDefinition.json file

We will create a very simple createUiDefinition.json file to demonstrate the principles
The basic structure of a createUiDefinition.json file is as follows:

{
    "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
    "handler": "Microsoft.Azure.CreateUIDef",
    "version": "0.1.2-preview",
    "parameters": {
        "config": {
            "isWizard": false,
            "basics": {}
        },
        "basics": [],
        "steps": [],
        "outputs": {},
        "resourceTypes": []
    }
}

Add an additional parameter

Additional parameters are added to the basics element after config
Add a websiteName parameter and some constraints
Note the outputs property which which is used to map elements from basics to the parameters defined in the ARM template
In this case we map the websiteName field in our UI to a template parameter called siteName
See modified file below:

{
    "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
    "handler": "Microsoft.Azure.CreateUIDef",
    "version": "0.1.2-preview",
    "parameters": {
        "config": {
            "isWizard": false,
            "basics": {}
        },
        "basics": [
            {
                "name": "websiteName",
                "type": "Microsoft.Common.TextBox",
                "label": "Website Name",
                "constraints": {
                    "required": true,
                    "validations": [
                        {
                            "regex": "^[a-z0-9A-Z]{5,25}$",
                            "message": "Between 5-25 alphanumeric characters are allowed."
                        }
                    ]
                },
                "visible": true
            }
        ],
        "steps": [],
        "outputs": {
            "websiteName": "[basics('siteName')]"
        },
        "resourceTypes": []
    }
}

Override the core application creation experience

Overrides are done within the config element
Add a customised description
Force the creation of a new resource group
Change the location label (just for kicks) and constrain the allowed values
See modified file below:

  {
      "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
      "handler": "Microsoft.Azure.CreateUIDef",
      "version": "0.1.2-preview",
      "parameters": {
          "config": {
              "isWizard": false,
              "basics": {
                  "description": "You can enter a customised description of your solution with **markdown** support.",
                  "resourceGroup": {
                      "allowExisting": false
                  },
                  "location": {
                      "label": "Custom label for location",
                      "allowedValues": [
                          "westeurope",
                          "uksouth"
                      ],
                      "visible": true
                  }
              }
          },
          "basics": [
              {
                  "name": "websiteName",
                  "type": "Microsoft.Common.TextBox",
                  "label": "Website Name",
                  "constraints": {
                      "required": true,
                      "validations": [
                          {
                              "regex": "^[a-z0-9A-Z]{5,25}$",
                              "message": "Between 5-25 alphanumeric characters are allowed."
                          }
                      ]
                  },
                  "visible": true
              }
          ],
          "steps": [],
          "outputs": {
              "siteName": "[basics('websiteName')]"
          },
          "resourceTypes": []
      }
  }

Save and test the createUiDefinition.json file in the sandbox

Save createUiDefinition.json in a suitable location
Open the Create UI Definition Sandbox
Replace the empty definition with the contents of your createUiDefinition.json file
Select Preview
The form you created is displayed
Step through the user experience and fill in the values
Confirm that you can see the custom description, you cannot deploy to an existing resource group etc