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:

1. Change the resources allocated for this VM using the Custom Profiles
2. Change the root user password on the VM
3. Create additional user account on the VM
4. Select lease time and see when the VM will expire
5. 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. 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:
  <p><strong>small:</strong> 1 CPU, 1024 MB RAM, 2 GB HDD<p>
  <p><strong>medium:</strong> 2 CPU, 2048 MB RAM, 4 GB HDD<p>
  <p><strong>large:</strong> 4 CPU, 4098 MB RAM, 6 GB HDD<p>

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.

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.