After creating a cloud template in Automation Assembler, versioning it, and importing it into your Automation Service Broker content, you can add a custom request form. Then you can use the form designer to edit and version the form, so that you can choose the version and use it later.

The following procedure assumes that your Automation Service Broker content includes a versioned Automation Assembler cloud template. Using the Catalog service API, you find the ID of the cloud template and get the cloud template schema for one of the template versions. To create a custom form from the schema, you use the Form Service API. Additional steps show how to customize and version the custom form, and how to list and restore a versioned form.

For more information about Custom Forms, see Learn more about Automation Service Broker custom forms.

Prerequisites

Procedure

  1. List the items in your catalog. 
    curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/catalog/api/admin/items?apiVersion=$api_version"  | jq "."
    Examine the response to find the catalog ID of the cloud template that you want to use.
  2. Assign a variable for the cloud template catalog ID. 
    item_id='<cloud_template_catalog_ID>'
  3. Get information about the catalog item. 
    curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/catalog/api/admin/items/$item_id?apiVersion=$api_version"  | jq "."
    Examine the result to choose the version of the template that you want to use for the custom form.
  4. Assign a variable for the cloud template version ID.
    The form that you create and customize a form will be associated with this cloud template version ID. 
    version_id='<your_cloud_template_version_ID>'
  5. Using the catalog ID and version ID, get the schema for the the cloud template. 
    $ schema='curl -k -X GET \
"$url/catalog/api/admin/items/$item_id/versions/$version_id \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' | jq -r .schema'
  6. Use the schema to create a custom form. 
    curl -k -X POST \
   "$url/form-service/api/forms/designer/request?sourceType=com.vmw.blueprint.version&sourceId=$item_id/$version_id&formType=requestForm" \
   -H "Authorization: Bearer $access_token" \   
   -H 'Content-Type: application/json' \
   -d '$schema' | jq "."
    You have a current version of your custom form.
  7. Customize the form. 
    curl -k -X POST \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' \
"$url/form-service/api/forms" \
-d '{
   "name":"Demo Blueprint / 2.0.0",
   "form":"<your_modified_form_json_as_string>",
   "styles":"<your_modified_styles_string>",
   "status":"ON", // set ON to enable the custom form, OFF to disable
   "type":"requestForm",
   "sourceId":"$item_id/$version_id",
   "sourceType":"com.vmw.blueprint.version"
 }' | jq "."
    A response with the status 201 'Created' indicates a successful form update.
  8. To save the current form with a new version name, you version the form. 
    curl -k -X POST \
"$url/form-service/api/forms/versions" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' \
-d '{
   "name":"<your_form_version_name>",
   "sourceId":"$item_id/$version_id",
   "sourceType":"com.vmw.blueprint.version",
   "formType":"requestForm"
}' | jq "."
    The form is saved with version name.

    To create more versions, you repeat the steps to customize and version the form. If you customize without versioning, the changes you make are only applied to the current form.

  9. (Optional) If you have at least one form version in addition to the current form, you can list and restore the version that you want to use.
    • To list form versions: 
      curl -k -X GET \
"$url/form-service/api/forms/versions?sourceType=com.vmw.blueprint.version&sourceId=$item_id/$version_id&formType=requestForm" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' | jq "."

      The response lists the names of stored form versions and their IDs or formVersionId.

    • To restore a previously versioned form, use the formVersionId: 
      curl -k -X PATCH \
"$url/form-service/api/forms/versions/$formVersionId/restore" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' | jq "."

Example: Edit and Version a Custom Form

Edit the custom form for a cloud template with the name Demo Blueprint. Then version the custom form it so that you can save it to use later.

Assign variables.

Note: If your organization uses an API service that is hosted outside of the United States, your URL variable must include a country abbreviation. See Regional Endpoints for VMware Aria Automation APIs. 
$ url='https://api.mgmt.cloud.vmware.com'
$ api_version='2020-08-25'

List the items in your catalog.

$ curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $access_token" "$url/catalog/api/admin/items?apiVersion=$api_version" | jq "."

Examine the response to find the cloud template named Demo Blueprint and get the catalog ID.

[
  {
    "id": "890275e3-cbc6-3778-af0d-d9eddf4664a0",
    "name": "Demo Blueprint",
    "description": "",
    "sourceId": "d4c24bba-68cc-4923-9155-338c4bf3e663",
    "sourceName": "template-content-source",
    "type": {
      "id": "com.vmw.blueprint",
      "link": "/catalog/api/types/com.vmw.blueprint",
      "name": "VMware Aria Automation Templates"
    },
    "createdAt": "2023-05-03T15:15:02.805617Z",
    "createdBy": "[email protected]",
    "lastUpdatedAt": "2023-05-03T15:15:02.805617Z",
    "iconId": "1495b8d9-9428-30d6-9626-10ff9281645e",
    "bulkRequestLimit": 1
  }
]

Assign the item ID variable with the catalog ID of the cloud template. 

$ item_id='890275e3-cbc6-3778-af0d-d9eddf4664a0'

Get catalog information about the cloud template.

$ curl -X GET \
   "$url/catalog/api/admin/items/$item_id?apiVersion=$api_version" \
   -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $access_token"  | jq .content

A snippet of the response lists the imported versions.

[
  {
    "id": "2.0.0",
    "description": "Added numberInput field",
    "createdAt": "2023-03-29T06:19:48.748349Z",
    "externalId": "/blueprint/api/blueprints/bbbb30b8-a73a-44bb-92db-27a504e0ec85"
  },
  {
    "id": "1.0.0",
    "description": "Added stringInput field",
    "createdAt": "2023-03-29T06:19:30.845516Z",
    "externalId": "/blueprint/api/blueprints/bbbb30b8-a73a-44bb-92db-27a504e0ec85"
  }
]

The cloud template in this example has two versions in the catalog. To get the schema and create a custom form for version 2.0.0, assign a variable.

$ version_id='2.0.0'

Use the catalog ID and the version ID to get the schema for the cloud template.

$ schema='curl -k -X GET \
"$url/catalog/api/admin/items/$item_id/versions/$version_id \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' | jq -r .schema'

Use the schema to create a custom form.

$ curl -k -X POST \
"$url/form-service/api/forms/designer/request?sourceType=com.vmw.blueprint.version&sourceId=$item_id/$version_id&formType=requestForm" \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' \
-d '$schema' | jq "."

The response shows the schema for Demo Blueprint version 2.0.0. It also shows the form ID or 4e383140-51a4-44a7-afcd-26296079596d. 

{
  "tenant": "733178c1-0620-478c-96b4-2b04ece1478d",
  "id": "4e383140-51a4-44a7-afcd-26296079596d",
  "name": "Demo Blueprint / 2.0.0",
  "form": "{\"layout\":{\"pages\":[{\"id\":\"page_general\",\"title\":\"General\",\"sections\":[{\"id\":\"section_project\",\"fields\":[{\"id\":\"project\",\"display\":\"dropDown\",\"signpostPosition\":\"right-middle\"}]},{\"id\":\"section_deploymentName\",\"fields\":[{\"id\":\"deploymentName\",\"display\":\"textField\",\"signpostPosition\":\"right-middle\"}]},{\"id\":\"section_stringInput\",\"fields\":[{\"id\":\"stringInput\",\"display\":\"textField\",\"state\":{\"visible\":true,\"read-only\":false},\"signpostPosition\":\"right-middle\"}]},{\"id\":\"section_e0bcefb5\",\"fields\":[{\"id\":\"numberInput\",\"display\":\"dropDown\",\"state\":{\"visible\":true,\"read-only\":false},\"signpostPosition\":\"right-middle\"}]}]}]},\"schema\":{\"project\":{\"label\":\"Project\",\"type\":{\"dataType\":\"string\",\"isMultiple\":false},\"valueList\":{\"id\":\"projects\",\"type\":\"scriptAction\"},\"constraints\":{\"required\":true}},\"numberInput\":{\"label\":\"numberInput\",\"type\":{\"dataType\":\"integer\",\"isMultiple\":false},\"valueList\":{\"id\":\"bdimov/actionThatReturnsLong\",\"type\":\"scriptAction\",\"parameters\":[]},\"constraints\":{\"required\":true}},\"stringInput\":{\"label\":\"stringInput\",\"type\":{\"dataType\":\"string\",\"isMultiple\":false},\"constraints\":{\"required\":true}},\"deploymentName\":{\"label\":\"Deployment Name\",\"type\":{\"dataType\":\"string\",\"isMultiple\":false},\"constraints\":{\"required\":true,\"max-value\":900}}},\"options\":{\"externalValidations\":[]}}",
  "sourceType": "com.vmw.blueprint.version",
  "sourceId": "890275e3-cbc6-3778-af0d-d9eddf4664a0/2.0.0",
  "type": "requestForm",
  "status": "ON",
  "formFormat": "JSON",
  "styles": ""
}

Update the form schema to change the visibility of the Deployment Name from true to false.

$ curl -k -X POST \
-H "Authorization: Bearer $access_token" \
-H 'Content-Type: application/json' \
"$url/form-service/api/forms" \
-d '{
   "name":"Demo Blueprint / 2.0.0",
   "form":'{"layout":{"pages":[{"id":"page_general","sections":[{"id":"section_project","fields":[{"id":"project","display":"dropDown","signpostPosition":"right-middle","state":{"visible":true,"read-only":false}}]},{"id":"section_deploymentName","fields":[{"id":"deploymentName","display":"textField","state":{"visible":"false","read-only":false},"signpostPosition":"right-middle"}]}]}]},"schema":{"project":{"label":"Project","type":{"dataType":"string","isMultiple":false},"valueList":{"id":"projects","type":"scriptAction"},"constraints":{"required":true}},"deploymentName":{"label":"Deployment Name","type":{"dataType":"string","isMultiple":false},"constraints":{"required":true,"max-value":900}},"options":{"externalValidations":[]}}}'
   "status":"ON", // set ON to enable the custom form, OFF to disable
   "type":"requestForm",
   "sourceId":"$item_id/$version_id",
   "sourceType":"com.vmw.blueprint.version"
 }'
If you want to see the updated form, use the form ID from the schema. 
curl -k -X GET "$url/form-service/api/forms/4e383140-51a4-44a7-afcd-26296079596d" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' | jq "."

Version the form and give it a name that will help you to identify it in a list later.

$ curl -k -X POST \
"$url/form-service/api/forms/versions" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json' \
-d '{
   "name":"Version1_Deployment_Visibility_FALSE",
   "sourceId":"$item_id/$version_id",
   "sourceType":"com.vmw.blueprint.version",
   "formType":"requestForm"
}' | jq "."
You can repeatedly update and version the form.
  • Each time you update the form, you are updating the current version.
  • Each time you version the form, you save the updated form with a new name.

If you want to restore a version of the form, list your form versions to find the version of the form that you want.

$ curl -k -X GET \
"$url/form-service/api/forms/versions?sourceType=com.vmw.blueprint.version&sourceId=$item_id/$version_id&formType=requestForm" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json'

The response includes the IDs and names of the custom forms.

[
  {
    "id": "4bfdd822-8975-4883-a8b2-22396ddf9395",
    "createdDate": "2023-05-17T14:54:07.187+0000",
    "createdBy": "[email protected]",
    "name": "Version1_Deployment_Visibility_FALSE"
  },
  {
    "id": "bed58877-e408-41ce-ad20-3bc48c569d84",
    "createdDate": "2023-05-17T14:39:16.267+0000",
    "createdBy": "[email protected]",
    "name": "Version2_TextField_Added"
  }
]

Assign the ID of the form you want to restore to the form version ID variable.

$ formVersionID='4bfdd822-8975-4883-a8b2-22396ddf9395'

Restore the form.

$ curl -k -X PATCH \
"$url/form-service/api/forms/versions/$formVersionId/restore" \
-H "Authorization: Bearer $token" \
-H 'Content-Type: application/json'

What to do next

You have learned how to create, update, version, and restore a custom form.