Custom Forms with vRealize Automation Cloud

This post in my series on VMware vRealize Automation Cloud (formerly known as Cloud Automation Services (CAS)) introduces custom forms for Service Broker. We are using data lookups and form validation heavily in vRA 7.x to provide multi-tenancy to our customers. We have put vRAC to the test and I am going to report the outcome of our evaluation in detail.

VMware documentation for Custom Forms

Service Broker Documentation
External values and validation are not covered entirely but have a look at the vRA docs: Custom Forms in vRA 7.6
You’ll find also some blogs covering this topic at least for vRA 7.x.

Service Broker

The Service Broker is intended to provide the end user access to published and customized blueprints. That might be the reason why the custom forms designer is accessible only in this part of vRealize Automation Cloud and not in Cloud Assembly.

Apart from creating and adopting input forms for the blueprints created in Cloud Assembly or imported via other “sources”, it is possible to perform data lookup and external validation with vRealize Orchestrator.

In order to test the custom forms you have to import your blueprints into Service Broker.

vRealize Orchestrator

A vRO appliance can be downloaded and installed creating a vRO integration in Cloud Assembly. We have tested the latest version (7.6). vCAC and vCACCAFE plugins are working with vRA 7.6 but there is no library for the new vRealize Automation Cloud (vRA 8.x) APIs. I implemented two vRO actions setting up and triggering the login and API endpoints for vRAC. You can download my package and run the workflow “installLibrary”. Please adjust organization id and refresh token in the configuration element with the externalized config.

I am using the Cache Plugin I found here; I’m using an updated version. Alternative: you check for 401 Not Authorized error on each call and get a new token. To speed up processing by reducing login calls, static variables would be needed – the cache plugin is used for this purpose. The token gets stored with an automatic expiry – if no cache element is found for an organization the login is performed and the token gets cached. It uses a distributed cache framework (hazlecast) and can be used in vRO clusters.

My Use Case for a Custom Form

I have a cloud agnostic blueprint with

  • a region name tag to control the placement
  • a hostname for the VM
  • a password entry field for the refresh token

Let’s start to create a custom form in Service Broker. Navigate to “content” and select the blueprint you want to enhance:

 

Select “Customize form”

Region Tags

 

 

The initial custom form contains all the fields that are defined in the Cloud Assembly blueprint. I select the field I want to enhance – Region Tag Name – and switch to “External source”. I enter the name of the vRO action I want to trigger to fetch the values of the dropdown list “getRegions”. The form designer will lookup the actions in vRO and prompt the matches for selection. The parameters of the action will be automatically added. I use here the fields you can also find shown in the “Request Inputs” in the upper left box. I select the organization (to fetch the correct refresh token for a multi organization installation) and the project.

The vRO action can be found in the package I’m offering for download above:

 

 

Field Level Validation

For each of the form fields some trivial validation can be defined like min/max values, field comparison (password) or regex validation. In my test I’m validating the hostname by a regex:

^([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]{0,61}[a-zA-Z0-9])(\\\\.([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9\\\\-]{0,61}[a-zA-Z0-9]))*$

Hidden Fields

In my use case I need the organization also for the form validation and could not directly use the one offered in the “Request Inputs” as for the “Region Name Tags”. I consider this a bug, but I tried to make the best out of it and use a hidden form field (something you find often in HTML) to work around the issue:

 

 

If you bind the field to this hidden field, you can consume it also for form validation:

 

 

I changed the action afterwards and the current code does not really make use of the organization. I left it as an example for hidden fields.

Form Validation

On the left top corner of the grey canvas you find two icons. Per default you will be in the designer for the form and its field. Select the second one and you can add validation functions.

 

 

Configure the call to „validateForm“ action on vRO.

 

 

The action on vRO looks like this:

 

 

Test the Custom Form

Lookup Data: Region Name Tags

The vRO action gets all region tags from vRealize Automation Cloud and sorts them.

 

 

Regex Validation: Hostname

The regex is beeing tested for each key stroke in this entry field. Any input that does not comply will be marked with the red exclamation mark that expands to the error message if clicked.

 

 

Form Validation: Check Refresh Token

Submitting the form is triggering the form validation action. It is trying to login with the given refresh token and reports errors. If the token is valid, the form is finally submitted and gets processed for provisioning.

 

 

API Access

Swisscom is automating infrastructure and customer configuration as much as possible. A blueprint configuration for a customer will contain:

  • blueprint
  • actions
  • event subscriptions
  • icons
  • customized form
  • templates
  • binaries
  • credentials

For a in depth discussion of these requirements please see my blog post “A Wish List for Configuration Management with the vRealize Suite”. vRealize Automation Cloud has already heavily improved in this regard as we will show case in our VMwold breakout session HBO3559BE in Barcelona. I want to describe in weekly posts more on the details of our CICD process implemented in Code Stream and publish the code of my test applications after the breakout session.

In this blog I put the focus on the API calls for publishing custom forms. Currently not all API docs are available, some starting points can be found at code.vmware.com or in one of my older posts. For undocumented APIs I use the Chrome Developer Tools to trace what the angular UI is using, there are a lot of handy functions that help you to copy requests as curl or responses for further inspection.

Fetch Content (Published Blueprint)

In Service Broker the catalog items are referred as “content” imported from a “source”. If you do not already know the content ID

curl -X GET \
https://api.mgmt.cloud.vmware.com/catalog/api/admin/items/<contentId> \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>'

, you can also perform a search by name:

curl -X GET \ 
'https://api.mgmt.cloud.vmware.com/catalog/api/admin/items?sort=name,asc&size=20&page=0&search=<name>' \

-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>'

The result contains the property “schema” containing the input schema of the underlying blueprint.

Fetching the form if you do not know its ID can be done with this call:

curl -X POST \
'https://api.mgmt.cloud.vmware.com/form-service/api/forms/designer/request?sourceType=com.vmw.blueprint&sourceId=<itemId>&formType=requestForm' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>' \
-d '<content of property “schema”>

If you get 200 OK you are fetching an already existing custom form, 201 Created indicates that you have created the default custom form with the defaults from the blueprint schema

In the response you get the form ID that can be used to read or delete the form directly:

curl -X GET \
https://api.mgmt.cloud.vmware.com/form-service/api/forms/<formId> \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>'

curl -X DELETE \
https://api.mgmt.cloud.vmware.com/form-service/api/forms/<formId> \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>'

You can download the json of the form I was testing. It comes as stringified JSON in the “form” property in the following structure:

{
    "id": "<your form id>",
    "name": "esc-event-subscriber",
    "form": "<stringified form JSON>",
    "styles": null,
    "sourceType": "com.vmw.blueprint",
    "sourceId": "<your source id>",
    "type": "requestForm",
    "tenant": "<your organization>",
    "status": "ON",
    "createdDate": 1571083155043,
    "modifiedDate": 1571083155043,
    "formFormat": "JSON"
}

This form property does not contain any references to the blueprint or the content item, so you can store and post it to any blueprint that has the same input schema and to any environment with a vRO installation that has the vRO actions installed under the same path:

curl -X POST \
https://api.mgmt.cloud.vmware.com/form-service/api/forms \
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json' \
-d '{
  "name": "esc-event-subscriber",
  "form": "<stringified form JSON>",
  "status": "on",  //enable/disable the form
  "type": "requestForm",
  "sourceId": "<your content item ID>",
  "sourceType": "com.vmw.blueprint"
}'

There is an additional call to fetch the metadata and valid field content you might want to use if you do not simply create the form directly in the designer and export it over the UI:

curl -X POST \
'https://api.mgmt.cloud.vmware.com/form-service/api/forms/designer/elements?sourceId=<itemId>' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer <your token>' \
-H 'Content-Type: application/json' \
-d '<content of property “schema”>'   

VMworld Barcelona

If you’re attending please join us for the Breakout Session HBO3559BE .