Customizing request forms using the new Custom Forms

Custom Forms is a new feature in vRA 7.4. They give you the opportunity to redesign and apply a new look and feel for vRA forms. They also provide a rich set of features, such as the ability to re-order the components in the form, many different types of field validations, the ability to use generic components that are not included in the blueprint, and many others.

In this blogpost, we will create one blueprint with both vSphere and XaaS Blueprint components. The user will be able to do the following:

Change the resources allocated for this VM using the Custom Profiles
Change the root user password on the VM
Create additional user account on the VM
Select lease time and see when the VM will expire
We will customize the form even further by applying custom CSS styles to the form, making the form look and feel different from the default coming from the form designer

This is what the final request form looks like:

Prerequisite:

vRA 7.4
vSphere server configured as an Infrastructure endpoint, and as Orchestrator endpoint (under vRA Administration Endpoints)
Linux Template on the vSphere server
VMWare Tools Installed on the Template VM

Downloadable content:

Composite Blueprint with all the dependent components Download
vRO Package Download
Custom Form for the Blueprint (JSON format) Download
CSS file for additional customization of the look and fill Download

Steps to install:

1. Download the contents above
2. Import vRO Package Contents using vRO Client
  - - Change the default root password for the VM template
3. Import the Blueprint using the cloud client
  - - Login to your vRA instance using the coudclient command “vra login userpass –tenant yourtenant_name“. If “–tenant” option is not used by default vsphere.local will be used as а tenat ID
    - Import the component profiles by executing these commands in the cloudclient
      - vra content import –path d:\forms\size_small-component-profile-value.zip –verbose true –precheck warn –resolution overwrite
      - vra content import –path d:\forms\size_medium-component-profile-value.zip –verbose true –precheck warn –resolution overwrite
      - vra content import –path d:\forms\size_large-component-profile-value.zip –verbose true –precheck warn –resolution overwrite
    - Import the XaaS blueprint and the Composite Blueprint
      - Run the cloudclient command: vra content import –path d:\forms\blogpost-composite-blueprint.zip –verbose true –precheck warn –resolution overwrite
      - Edit the imported blueprint and select the Clone Template which will be used to provision the catalog item ( The template should have 8GB disk and VMware Tools Installed )
    - Add the Blueprint to a service exposed in the Catalog
    - Now you have several options to crate and modify the request form
      - First select the Blueprint and open the Form Designer
        
        The first option is to use the form generator. This will generate the form for you. Click on Actions → Generate form.
        
        Default form layout is generated for you, with most of the blueprint components. The properties for every Blueprint component are placed on a different tab. You can delete unnecessary fields, reorder components, add validations and interactions between the components.
        
        The second option is to begin from a blank form page and add only the components that you need.
        
        The third option is to import existing JSON Form Definition ( we will use this to import the downloaded JSON form definition )
      - Activate the Form, by clicking on the toggle button in the upper right corner of the Form Designer.
      - Request the catalog item from the catalog to see how the new request form is looking
      - Now we can improve the look and fill of the form even further by adding custom CSS styles
        
        Open again the form in the Custom Forms Designer and click on Actions → Import CSS. Select the blogpost.css file
      - Request again the catalog item with the applied CSS styles. You can see that by using the CSS we changed the styling of few components. Now our request form is completed and ready for use.

In the next section you will see how the imported form was created in the Custom Form Designer.

Edit the Custom Form by selecting the Blueprint and clicking on the Edit form button

You can delete all the form components added to the Canvas and start from the beginning.

1. Adding Component Profile to the form and Imige component which will changed depending on the selected profile

Add the required components to the canvas

From the Generic Elements panel locate the Text component and add it to the canvas.
From the Generic Elements panel locate the Image component and add it to the canvas.
Expand the vm component in the Blueprint Elements tree and drag the size component in the same section (on the same row) like the Image component.

Change labels and add interaction between the components

Select the size dropdown and change the Label to VM Resources
Select the Image component, the details panel will be loaded.
Click on the values tab, expand Default value and for Value source select Conditional value
Now we can define default value for the Image based on the components added in the canvas or based on the Request Info Fields
When you add more components, you will have lager list of canvas components. Now define 3 conditions based on the selected component profile.
- - When small is selected for VM Resources the value for the icon should be https://png.icons8.com/dusk/64/virtual-machine2.png
  - When medium is selected for VM Resources the value for the icon should be https://png.icons8.com/dusk/64/hips.png
  - When large is selected for VM Resources the value for the icon should be https://png.icons8.com/dusk/64/server.png
    All icons are taken from: https://icons8.com/
Select the VM Resources and expand the Custom help panel
Set the Signpost help message to:
Choose resources for your environment:
small: 1 CPU, 1024 MB RAM, 2 GB HDD
medium: 2 CPU, 2048 MB RAM, 4 GB HDD
large: 4 CPU, 4098 MB RAM, 6 GB HDD

Note: (You can use HTML tags for the Signpost help message)

2. Adding the functionality for changing the root password

Add the required components to the canvas

From the Generic Elements drag and drop Text component under the Image
From the Generic Elements drag and drop Checkbox component on a new row under the Image
Expand the SetupUser component from the Blueprints Elements tree and add the rootPassword element on the canvas under the Checkbox
From the Generic Elements drag and drop Password component under the rootPassword

Change labels

Select the Text component, and change the Label to Add or Change user credentials
Select the Checkbox component, and change the Label to Change root password
Select the rootPassword, and change the label to New root password
Select the Password component, and change the label to Confirm root password

Add regular expressions validation for the root password

Select New root password
In the Details panel click on the Constraints tab
Paste this regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$@$!%*?&])[A-Za-z\d$@$!%*?&]{8,10} into the Regular expression field.

For the custom forms you can use JavaScript formatted regular expressions. For more information you can check the documentation at: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
If you want to test your regular expressions you can open https://regex101.com/
Select the JavaScript FLAVOR and start creating your regex.
Expand the Regular expression field, and in the Validation error message type the text which will be displayed when the entered password is not matching the regex ( The password should be minimum eight and maximum 10 characters, at least one uppercase letter, one lowercase letter, one number and one special character ). If you leave this empty the default error message will be displayed.

Add validation for the “Confirm root password” field

Select the Confirm root password field
In the Details panel click on the Constraints tab
For the Match field select New root password. This will stop the form submission and will show error message if the values of the two password fields does not match.

To show and hide the password fields depending on the checkbox selection do the following steps for both fields

Select the field
Expand the Visibility section of the Appearance tab
For Value source select Conditional value
Add Expression which sets the visibility value to Yes if the Change root password equals Yes

Currently we have only the functionality to show and hide the fields. If the user enters new root password and uncheck the checkbox, the passwords fields will be hidden, and the value will be send with the request. Because we don’t want such behavior, we will add default value Empty for the password fields if the checkbox is unchecked.

For both password fields click on the Values tab
Expand the Default value and for Value source select Conditional value
Add expression, by leaving the Set value empty and select if Change root password – Equals – No

3. Adding the functionality to create a new user account.

Add the required components to the canvas

From the Generic Elements drag and drop Checkbox component
Expand the SetupUser component from the Blueprints Elements tree and add the newUser field
Add the newPassword field
From the Generic Elements drag and drop a Password component

Change labels

- For the Checkbox change the label to Add new user
- For the newUser field change the label to Username
- For the newPassword field change the label to Password
- For the Password component from the Generic Elements change the label to Confirm password

Add validation for the username. The username should be minimum 3 letters and maximum 12 letters long
- Select the Username and click on the Constraints tab
- Set Minimum value to 3 and Maximum value to 12

Add regular expressions validation for the Password field (same as the one for the root password)

Add validation for the Confirm password field (same as the one for the root password)

Add a visibility constraint for the Username, Password, and for the Confirm password field (same as the one for the root password but depending on the Add new user checkbox)

Add a default Empty value for the Username, Password, and for the Confirm password field (same as the one for the root password but depending on the Add new user checkbox)

4. Adding the deployment type.

Drag and drop Text component under the Confirm Password, and change it’s label to Environment configuration
To add the deployment type, drag a Radio group component from the Generic Elements, and change its label to Deployment type
Click on the Values tab and expand the Value options. Leave the Value source field to Constant and paste client|Client Setup,server|Server Setup in the text area below. The radio group is now defined with 2 options. (You can populate the values for the Radio group also by using VRO actions)
Add default selected option by typing client in the Default value field

Note: Later this component will be used to define custom validation for the Lease time depending on the Deployment Type selection

5. Adding lease time selection for the VM, and calculating the expire date.

Add the required components to the canvas

Expand the General component in the Blueprint Elements and add the Lease days under the Deployment Type radio group
From the Generic Elements panel locate the Date Time component and add it on the same row as the Lease days

Add validation

Select the Lease days component and click on the Constraints tab
Set 1 for Minimum value and 365 for Maximum value

Calculate the expiration date

Select the Date Time component and change its label to Your environment will expire on:
On the Appearance panel change the Read-only field value to Yes
Click on the Values tab, expand Default value and select External source
In the Select action type getLeaseDate. Dropdown with the founded VRO actions will appear. Select the getLeaseDate action
Action inputs will appear. Select the Lease days field for the leaseDays input parameter. This action will be invoked when the value of the Lease days is changed, and will calculate the date value by adding the number of days to the current date. This value will be set to the Date Time component. You can write your own VRO actions to set the default values of form components based on the selected values of other components, request info fields or other parameters accessible from the VRO action.

6. Adding custom validation for the form.

To add specific validation which will be triggered when the form is submitted, you can create VRO Action which returns String. The value of the String is the returned Error message. If the returned String is null or Empty the form is considered as Valid. You can add different Input parameters to the action. Later you can configure how these parameters will be populated from the form components. In our example we will use the Deployment Type selection and the Lease days to validate the Lease date value.

Click on the External Validations tab in the upper left corner
From the Validations Type panel add Orchestrator validation in the canvas
Select the added component and change the Validation label value to Validate Lease
Expand the Define validation and in the Select action field type validateLease
Select the validateLease action from the dropdown
Two Action input parameters will appear
For deploymentType parameter select Deployment Type field
For leaseDays parameter select Lease Days field
Expand the Highlighted fields section and add the Lease days field. Here you can add all the fields which should be highlighted with the error message, returned by the custom validation.

7. Creating the CSS file

The style of one Custom Request Forms can be modified using CSS styles attached to the form. The definition of such file requires good knowledge of HTML, CSS and good Debugging skills. To create the CSS file, I’m using the Firebug plugin for Firefox or Inspecting the HTML elements in Chrome. With this plugin you can see rendered HTML form with the applied CSS styles.

When you are adding new styles it’s good to start your locators with the IDs of the components added in the form. These IDs is less likely to be changed. These IDs can be changed if you export the form, change them, and import the form.

The IDs for the form components can be located also in the Form Designer. Note that you should NOT CHANGE IDs of the blueprint components (IDs like: vm~cpu, vm~memory). If you change them the Blueprint will stop working.

Note: The structure of the Forms HTML may change between this and newer version of vRA, and the support of CSS styles is not backward compatible. Have in mind that if you upgrade vRA, your styles may need some modifications to work again. That’s why we don’t encourage a lot of layout changes using CSS.

Summary

You have seen some of the capabilities of the custom forms, but there are others like adding Tabs, Value picker used for selecting vRO object types ( like AD:USER, AD:GROUP) and tables. For more details take a look at the reference documentation page.

Learn More

Not using vRealize Automation yet? Visit our product page to learn more.
Get more hands-on experience with vRA using our Hands-on Labs.

Prerequisite:

Downloadable content:

Steps to install:

In the next section you will see how the imported form was created in the Custom Form Designer.

1. Adding Component Profile to the form and Imige component which will changed depending on the selected profile

Note: (You can use HTML tags for the Signpost help message)

2. Adding the functionality for changing the root password

3. Adding the functionality to create a new user account.

4. Adding the deployment type.

Note: Later this component will be used to define custom validation for the Lease time depending on the Deployment Type selection

5. Adding lease time selection for the VM, and calculating the expire date.

6. Adding custom validation for the form.

7. Creating the CSS file

Summary

Learn More

Related Posts:

Related Articles

Deploying VMware Avi Load Balancer resources with VMware Aria Automation Templates

Enabling Load Balancer as a Service for VCF-based Private Cloud

Announcing VMware Aria Automation 8.16.0 Release

Image mapping management in Aria Automation with idem provider for Aria Automation.

Aria Automation Content Staging