Validation

Overview

There are currently 2 types of validation that are supported for templates:

• Schema-based validation
• Custom broker-based validation

Schema-based validation

The values provided by the user are validated against the schema defined by the broker author in the broker catalog using JSEN. This is often the easiest way to include validation of user entered properties as it doesn't involve any code.

This type of validation currently only runs only on the template setup page, after the Create button is pressed.

Here is a link to the JSON Schema spec and this is the link that deals with schema validation.

Here is an excellent guide to JSON Schema.

Custom broker-based validation

There are also cases where the template needs to interact with the broker to validate parameters or provide a set of values to display in the UI.

For these cases we provide a mechanism to talk to the broker that provides the integration - it is called APV (stands for "authorize, populate and validate").

APV describes the steps of the validation protocol - first a check for authorization occurs, then the broker is given a chance to populate the form with some values and finally the broker is given the opportunity to validate the contents of a form.

There are 2 parts to enabling custom validation for a service:

• adding the validator to the broker catalog service definition
• implementing the apv protocol in the broker code to handle your service's needs

Adding validator to broker catalog

To add a validator to the broker catalog you must add the following JSON to the form declaration for your broker:

"form": [
{		
  "type": "validator",		
  "source": "broker",		
  "version": "1"		
},
etc.

Implementing the apv protocol

As mentioned previously, the APV protocol consists of 3 different parts: authorize, populate and validate. APV authors are free to implement as much of the protocol as is useful for their particular needs. If they wish to skip over any part of the protocol, they can simply return a 200 for a particular stage.

The cycle for APV is controlled by the UI on the template creation and add tool pages, and always works in the following manner:

Authorize -> if response is 200, proceed to Populate step. If response is 401, render authorize button for OAuth flow. The authorize flow only runs once when the page is initially rendered. Once the auth has been completed it doesn't run again.

Populate -> the schema + contents are sent down to the broker. The broker has a chance to add/modify values and send them back to the form.

Validate -> the schema + contents are sent down to the broker. The broker can mark fields as invalid and provide an error message to display in the UI.

The populate and validate steps are run continuously upon any updates in the UI, once a pause is detected in the input of data.

APV broker endpoint

In order to receive calls from the UI, your broker needs to handle a POST to the /[SERVICE_ID_URL]/v1/form endpoint. The value for SERVICE_ID can be found in the broker-catalog.json entry for your service - under the url property. For example, here is an excerpt from the todolist-broker entry in the catalog:

"url": "/todolist-broker/api",
"brokerName": "todoListBroker",
"type": "service_broker",
"services": [{

To handle the apv calls for this instance, you must add a handler for /todolist-broker/api/v1/form.

APV Request

The apv request always contains the following parameters:

Name	Located in	Description
service_id	body	the service id that this call is meant for. This is useful if you have packaged multiple services into one broker and want to be able to differentiate between apv calls.
type	body	the type of request. Value must be authenticate, populate or validate.
userInfo	body	the user making the request.

The userInfo object looks like this:

{
 "email": "[email protected]",
 "name": "John Smith",
 "tiam_id_token": [a tiam id token string].
 "user-id": [some id string],
 "user_name": "johnsmith"
}

This is provided to allow brokers a way to validate that the user making the request is allowed to make the request. How (and if) the brokers make use of this info is up to them.

Authenticate

The authenticate call allows the broker to check if a user is authenticated. If 200 is received in the response, it will proceed to call populate.

If no authentication is needed, the broker should just return a 200.

Parameters

Name	Description
service_id	the service id
type	"authenticate"
userInfo	userInfo

Responses

Response	Description
200	The user is authenticated
401	The user is not authenticated

Populate

The populate call happen initially when the page loads and after any subsequent changes to the form values. The current form properties are passed to the broker. The broker can make modifications to the properties and send them back in the response and they will be reflected in the UI. This provides a mechanism to populate fields etc.

At a minimum, the broker must respond with 200 and the same list of properties sent in.

Upon receiving a 200 from the populate call, validate is called.

The properties object is a JSON object. Here is an example with two properties:

{
   "dashboard_url":{  
      "description":"some description",
      "title":"A title",
      "type":"string",
      "value":"Some value"
   },
   "user_login":{  
      "description":"some login desc",
      "type":"string",
      "value":""
   }
}

Parameters

Name	Description
service_id	the service id
type	"populate"
userInfo	userInfo
properties	properties

Responses

Note that the 200 returned here only indicates that the populate cycle was completed - it doesn't have any special meaning about the contents of the returned object.

Response	Description
200	Populate completed

Validate

Validate is called on the initial page load and after any subsequent changes to the form values. The current form properties are passed to the broker.

The broker can then proceed to validate each property. If a problem is found with a property, a validationMessage describing what is wrong with the property is added. This message will be displayed in the UI and should be NLS-enabled.

If all of the properties pass validation, the broker must return the properties without any modifications. Receiving a JSON object with no modification indicates to the UI that there is nothing to report.

For example, here is how you would indicate that there is a problem with a property named myField:

var propertiesData = req.body.properties;
//Do some validation on properties, determine that myField is incorrect
propertiesData.myField.validationMessage = "Not a valid entry";
return res.status(200).json({properties: propertiesData});

Using the properties example from the populate section, this is what the would look like if there was a validation problem with the user_login property:

{
   "dashboard_url":{  
      "description":"some description",
      "title":"A title",
      "type":"string",
      "value":"Some value"
   },
   "user_login":{  
      "description":"some login desc",
      "type":"string",
      "value":"",
      "validationMessage": "No login value provided"
   }
}

At a minimum, the broker must respond with 200 and the same list of properties sent in.

Parameters

Name	Description
service_id	the service id
type	"validate"
userInfo	userInfo
properties	properties
validationType	"create"

Responses

Note that the 200 returned here only indicates that the validate cycle was completed - it doesn't have any special meaning about the contents of the returned object.

Response	Description
200	Validation completed