Appendix A

This appendix describes the form definition format for the endpoint-schema.json file contents.

The form definition is a declarative means expressing the user interface controls used to render form fields, the validations to perform, form field values dependencies, where predefined list of values are retrieved from, and so on. The form renderer generates HTML and JavaScript. Scripts can also include calls to VMware Aria Automation backend services for retrieving dynamic data.

Custom Form Definition (Updated)

{
    "layout": {
        "pages": [{
            "id": "page_1",
            "title": "First page title",
            "sections": [{
                "id": "secion_1",
                "fields": [{
                    "id": "field_1"
                    "display": ...
                    ...
                }, {
                    "id": "field_2"
                }]
            }, {
                "id": "section_2",
                "fields": []
            }]
        }, {
            "id": "page_2",
            "title": "Second page title",
            "sections": []
        }]
    },
    "schema": {
    "field_1": {},
    "field_2": {}
    },
    "options": {
        "externalValidations": [
        ...
        ]
    }

Layout (Updated)

The layout part of the form definition can have pages and/or sections. Each section can be hidden based on a constant or on a field value. Sections usually have one or more input fields, which can initially be hidden or read-only until something on the form is changed.

"layout": {
    "pages": [{
        "id": "general",
        "title": "General",
        "sections": [{
            "id": "section_1",
            "fields": [{
                "id": "description",
                "display": "textField"
            }, {
                "id": "reason",
                "display": "textField"
            }]
        }, {
            "id": "section_2",
            "fields": [{
                "id": "deployments",
                "display": "integerField"
            }, {
                "id": "leaseDate",
                "display": "textField"
            }]
        }]
    },
    {
        "id": "serviceInformation",
        "title": "Service Information",
        "sections": []
    }]
}

UI Controls (Updated)

The display property specifies which UI control is rendered. If not set, the default value is "text."

Drop-Down	"dropDown"
Checkbox	"checkbox"
Radio Group	"radio"
Data Grid	"datagrid"
MultiSelect	"multiSelect"
Datetime Picker	"dateTime"
Value Picker	"valuePicker"
ComboBox	"combobox"
Multi-value Picker	"multiValuePicker"
Dual List	"dualList"
Link	"link"
Slider	Not Defined

Submit (Updated)

"layout": {
    "pages": [{
        "id": "page_1",
        "title": "First page title",
        "sections": [{
            "id": "secion_1",
            "fields": [{
                "id": "form_label"
                "display": "text"
                "submit": false
            }]
        }]
    }]
}

Decimal step (updated)

The "step" property in the schema specifies the legal number intervals for the decimal field.

"schema": {
    "storage": {
        "type": {
            "dataType": "decimal"
        },
        "label": "Storage (GB)",
        "step": 0.1
    }
}

Integer step (updated)

The "step" property in the schema specifies the legal number intervals for the integer field.

"schema": {
    "memory": {
        "type": {
            "dataType": "integer"
        },
        "label": "Memory (MB)",
        "step": 1024
    }
}

Image description (updated)

The "description" property in the schema specifies alternate text for an image.

"schema": {
    "clarity": {
        "type": {
            "dataType": "string"
        },
        "default": "https://cto.vmware.com/wpcontent/uploads/2016/11/Picture1.png",
        "placeholder": "Clarity logo"
    }
}

Drop down option label (updated)

The "placeholder" property in the schema specifies a placeholder for the dropdown field.

"schema": {
    "vm-size": {
        "type": {
            "dataType": "string"
        },
        "label": "Deployment size:",
        "valueList": [{
            "label": "Small",
            "value": "small"
        }, {
            "label": "Medium",
            "value": "medium"
        }, {
            "label": "Large",
            "value": "large"
        }, {
            "label": "Custom",
            "value": "custom"
        }],
        "placeholder": "Select deployment size..."
    }
}

Data grid (updated)

The "size" property in the layout specifies the number of items displayed per page. The default is 10.

The "placeholder" property in the schema specifies placeholder text when there is no data displayed.

"layout":
    ...
    {
        "id": "properties",
        "display": "datagrid",
        "size": 20
    }

"schema": {
    "properties": {
    "type": {
        "dataType": "complex",
        "fields": [{
            "label": "Name",
            "id": "column_1",
            "type": {
                "dataType": "string"
            }
        }, {
            "label": "Value",
            "id": "column_2",
            "type": {
                "dataType": "string"
            }
        }]
    },
        "placeholder": "No items exist.",
        "default": [{
            "column_1": "first_prop",
            "column_2": "first"
        }, {
            "column_1": "second_prop",
            "column_2": "second"
        }]
    }
}

Multi-value data picker (updated)

The "size" layout property specifies the number of items displayed per page. The defaults is 10. The "placeholder" schema property specifies placeholder text when there is no data displayed. The "shortValueName" schema property specifies which fields display in the multi-value picker list.

"layout":
    ...
    {
        "id": "networks",
        "display": "multiValuePicker",
        "size": 20
    }

"schema": {
    "networks": {
        "type": {
            "dataType": "complex",
            "fields": [{
                "label": "Name",
                "id": "name",
                "type": {
                    "dataType": "string"
                }
            }, {
                "label": "Zone",
                "id": "zone",
                "type": {
                    "dataType": "string"
                }
            },
            {
                "label": "Network Domain",
                "id": "network-domain",
                "type": {
                    "dataType": "string"
                }
            }, {
                "label": "Support Public IP",
                "id": "support-public-ip",
                "type": {
                    "dataType": "boolean"
                }
            }]
        },
        "shortValueName":["name","zone"],
        "placeholder": "No items exist.",
        "default": [{
                "name": "appnet-isolated-dev",
                "zone": "us-east-1a",
                "network-domain": "rainpole-dev",
                "support-public-ip": false
            },
            {
                "name": "public-subnet-us-east-1b",
                "zone": "us-east-1b",
                "network-domain": "Public VPC",
                "support-public-ip": true
            }
        ]
    }
}

Constant Visible State (Updated)

{
    "id": "cpu",
    "display": "integerField",
    "state": {
        "visible": false
    }
}

Expression Visible State (Updated)

[{
    "id": "environment",
    "display": "dropDown"
},
{
    "id": "backup-options",
    "display": "dropDown",
    "state": {
        "visible": [{
            "equals": {
                "environment": "production"
            },
            "value": true
        }]
    }
}]

Constant Read Only State (Updated)

{
    "id": "vsphere-tag",
    "display": "textField",
    "state": {
        "read-only": true
    }
}

Schema

The "schema" part of the form definition describes the input data that is expected to be entered in the form. The schema consists of a list of fields with the following properties:

• label - label for the input field
• description - short text that will be displayed as a tooltip
• signpost - additional information that will be displayed in a separate popup box
• type - data type of the field
• default - default value
• valueList - a list of predefined values
• constraints - field constraints
  • required
  • min-value
  • max-value
  • pattern
  • match

Schema (Updated)

"schema":{
    "description": {
        "label": "Description",
        "type": {
            "dataType": "string"
        }
    },
    "reason": {
        "label": "Reason for request",
        "signpost": "Specify a reason for this request.",
        "type": {
            "dataType": "string"
        },
        "constraints":{    
            "required": true
        }
    },
    "deployments": {
        "label": "Deployments",
        "type": {
            "dataType": "integer"
        },
        "default": 1,
        "constraints":{
            "required": true,
            "min-value": 1,
            "max-value": 100
        }
    },
    "leaseDate": {
        "label": "Lease Date",
        "type": {
            "dataType": "string"
        }
    }
}

Signpost

The “signpost” property is the help content that appears in a popup box. Signpost can be plain text or HTML that contains text, links, and images.

"signpost": "<a href='https://vmware.github.io/clarity/'>Clarity</a>"
"signpost": "Plain text"

Field data type

The field data “type” property value can be string, integer, decimal, boolean, secure string, complex, or reference. If not set, the default value is string. Use the “type” property when calculating expression field state or constraints.

Field data type	Field value
String	"type": { "dataType": "string"}
Integer	"type": { "dataType": "integer"}
Decimal	"type": { "dataType": "decimal"}
Boolean	"type": { "dataType": "boolean"}
Secure string	"type": { "dataType": "secureString"}
Date Time	"type": { "dataType": "dateTime"}
Multiple	"type": { "dataType": "string", "isMultiple":true}
Complex	"type": { "dataType": "complex", "fields": []}
Reference	"type": { "dataType": "reference", "referenceType": "AD:User"}

Operators

Each field state type supports different operator types

Field type	Operator type
String, Secure string, Reference	"equals", "notEqual", "contains", "endsWith", "startsWith", "within"
Integer, Decimal, Date Time	"equals", "notEqual", ">", ">=", "<", "<="
Boolean, Complex	"equals", "notEqual"
Multiple	"contains"

Field Constraints

Each field can have multiple constraints that are evaluated in the rendered form:

• required
• min-value
• max-value
• pattern
• match

Deployments field constraints

"fields": {
    "numberOfDeployments": {
        "type": {
            "dataType": "integer"
        },
        "constraints": {
            "required" : "true",
            "min-value" : "1",
            "max-value": {
                "type": "scriptAction",
                "id": "com.vmware.vra.endpoint.azure/getReservationLimit"
            }    
        }
    },
    "email": {
        "type": {
            "dataType": "string"
        },
        "constraints": {
            "required" : "true",
            "pattern": {
                "value": "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$",
                "message": "Must be valid e-mail address."
            }
        }
    },
    "confirm-email": {
        "label": "Confirm Email:",
        "constraints": {
            "match": "email"
        }
    }
}

Constant Required Constraint

"deployments": {
    "label": "Deployments",
    "type": {
        "dataType": "integer"
    },    
    "constraints":{    
        "required": true
    }

Expression Required Constraint (Updated)

"reason": {
    "label": "Reason for request",
    "constraints": {
        "required": [{
            ">": {
                "deployments": 10
            },
            "value": true
        }]
    }
}

Constant min-value Constraint

A min-value constraint can be set with constant or expression value. If field type is string min-value will specify minimum value of characters length.

"password": {
    "label": "Password",
    "type": {
        "dataType": "secureString"
    },
    "constraints": {
        "min-value": 8
    }
}

Expression min-value Constraint (Updated)

A min-value constraint can be set with constant or expression value. If field type is string min-value will specify minimum value of characters length.

"deployments": {
    "label": "Deployments:",
    "type": {
        "dataType": "integer"
    },
    "constraints": {
        "min-value": [{
            "equals": {
                "environment": "production"
            },
            "value": 4
        }]
    }
}

Constant max-value Constraint

A max-value constraint can be set with constant or expression value. If field type is string max-value will specify maximum value of characters length.

"description": {
    "label": "Description",
    "type":{
        "dataType": "string"
    },
    "constraints": {
        "max-value": 50
    }
}

Expression max-value Constraint

A max-value constraint can be set with constant or expression value. If field type is string max-value will specify maximum value of characters length.

"deployments": {
    "label": "Deployments:",
    "type": {
        "dataType": "integer"
    },
    "constraints": {
        "max-value": [{
            "equals": {
                "environment": "test"
            },
            "value": 2
        }]    
    }
}

Pattern constraint

A pattern constraint is an object with two properties - value and message. Value property is constant regular expression value. Message property is custom error message which will be displayed in the tooltip in case of error.

"email": {
    "label": "Email",
    "constraints": {
        "pattern": {
            "value": "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$",
            "message": "Must be valid e-mail address."
        }
    }
}

Match constraint

A match constraint can be set with a constant value. This value must be other field id.

"password": {
    "label": "Password"
},
"confirm-password": {
    "label": "Confirm password:",
    "constraints": {
        "match": "password"
    }
}

Constant default value

The field “default” value can be constant value, option from valueList property, bind to other field value or string concatenation. Default values can also be the result of add, subtract or multiply operations.

"cpu": {
    "label": "CPU"
    "type": {
        "dataType": "integer"
    },
    "default": "2"
}

Default value from valueList (Updated)

"environment": {
    "label": "Environment:",
    "valueList": [{
        "label": "Development",
        "value": "development"
    }, {
        "label": "Test",
        "value": "test"
    }, {
        "label": "Production",
        "value": "production"
    }],
    "default": "production" // Set default value from predefined value list
}

Bind default value (Updated)

"storage": {
    "label": "Storage",
    "type": {
        "dataType": "integer"
    },
    "default": {
        "bind": "cpu" //Bind storage value to cpu field
    }
}

String concatenation

Note: When the value is surrounded with back quotes (for example, "`_machine`") the value is constant.

"vsphere-tag": {
    "label": "Tag:",
    "default": {
        "bind": {
            "values": ["environment", "`_machine`"] // Bind field value with
string concatenation
        }
    }
}

Add operation (Updated)

"sum-field": {
    "label": "Sum:",
    "default": {
        "bind": {
            "values": [ "field_1", "field_2", "`100`"],
            "operator": "add"
        }
    }
}

Subtract operation (Updated)

"subtract-field": {
    "label": "Difference:",
    "default": {
        "bind": {
            "values": [ "field_1", "field_2"],
            "operator": "subtract"
        }
    }
}

Multiply operation (Updated)

"storage": {
    "type": {
        "dataType": "decimal"
    },
    "label": "Storage (GB)",
    "default": {
        "bind": {
            "values": [ "storage_mb", "`0.001`"],
            "operator": "multiply"
        }
    }
}

vRO Action (Updated)

"memory": {
    "type": {
        "dataType": "integer"
    },
    "default": {
        "type": "scriptAction",
        "id": "com.vmware.vra.endpoint.azure/getDefaultMemorySize"
    }
}

Value lists (updated)

Lists of values can be assigned to a form field as either static (value is specified in the field schema) or dynamic (value is retrieved from an external data source like a VMware Aria Automation database, Automation Orchestrator action, or a REST API service). To populate the valueList property with an Automation Orchestrator action, the return type must be array of string, properties or array of properties.

Deployment size values – static (Updated)

"fields": [
    "deploymentSize": {
        "type": {
            "dataType": "string"
        },
        "valueList": [{
            "label": "Small",
            "value": "small"
        }, {
            "label": "Medium",
            "value": "medium"
        }, {
            "label": "Large",
            "value": "large"
        }, {
            "label": "Custom",
            "value": "custom"
        }]
    }
}

Deployment size values – dynamic (Updated)

"fields": {
    "deploymentSize": {
        "type": {
            "dataType": "string"
        },
        "valueList": {
            "type": "scriptAction",
            "id": "com.vmware.vra.endpoint.azure/getVmSizes",
            "parameters": [
                {
                    "param_1": "field1",
                    "$type": {
                        "dataType": "boolean"
                    }
                },
                {
                    "param_2": "`2`",
                    "$type": {
                        "dataType": "integer"
                    }
                },
                {
                    "param_3": "field2",
                    "$type": {
                        "dataType": "string"
                    }
                }
            ]
        }
    }
}

Options

The "options" part of the form additional form functionalities and it is not required unless these functionalities are used. The options consist of the following properties:

• externalValidations - list of external validations applied on form
  • label
  • source
    • type - type of the external source
    • id- unique identifier of the external source
    • parameters - parameters for the external source
  • target - array of fields in which the returned error message is applied (optional)

"options": {
    "externalValidations": [
    {
        "label": "Amazon form validation",
        "source": {
            "type": "scriptAction",
            "id": "com.zzz.vra.endpoint.aws/myFormExternalValidation1",
            "parameters": []
        },
        "target": []
    },
    {
        "label": "Amazon field validation with params",
        "source": {
            "type": "scriptAction",    
            "id":
"com.zzz.vra.endpoint.aws/myInputExternalValidationWithParams",
            "parameters": [
                {
                    "param_1": "field1",
                    "$type": {
                        "dataType": "boolean"
                    }
                },
                {
                    "param_2": "`2`",
                    "$type": {
                        "dataType": "integer"
                    }
                },
                {
                    "param_3": "field2",
                    "$type": {
                        "dataType": "string"
                    }
                }
            ]
        },
        "target": [
            "field_1",
            "field_1"
        ]
        }
    ]
}