Tray Embedded / Core Topics / Config Wizard data validation

Config Wizard data validation

When presenting the Config Wizard in either a pop-up or an iframe, it is possible to perform validation on the data being submitted by the End User.

To enable validation the customValidation queryString can be appended to the Config Wizard url:

https://embedded.tray.io/external/solutions/${embeddedId}/configure/${solutionInstanceId}?code=${authorizationCode}&customValidation=true

In the above url remember that ${embeddedId} is the value that you set when configuring your Config Wizard CSS

You can remove the tray.io domain and whitelabel the Config Wizard url. If you have done so then embedded.tray.io will be replaced with e.g. acme.integration-configuration.com

The validation process

The process for validating data being entered by an End User is as follows:

  • The data input on each screen is validated when the End User clicks 'Next' - i.e. not in one payload after the final screen
  • When the End User clicks 'Next' on a screen, the Configuration Wizard will send a tray.configPopup.validate post message event to your application which indicates that you should start the validation process
  • When this event is received you should respond immediately that in progress is true. At this point all inputs will be disabled and the Config Wizard will display a 'loading' message. This will allow for any longer data checks on your Back End
  • As soon as you have finished your validation, you should respond with a tray.configPopup.client.validation post message event which states that in progress is false. This message should include an array of the error messages resulting from your validation, which can be empty

To manage the above, the following data types are available:

type CustomValidationErrors = {
[externalId: string]: string
};
export type CustomValidation = {
inProgress: boolean;
errors?: CustomValidationErrors
};
export type CustomValidationAuthValues = {
[externalId: string]: string | undefined;
};
export type CustomValidationConfigValues = {
[externalId: string]: any;
};
export type CustomValidationFormData = {
visibleValues: string[]; // soon to be deprecated
visibleAuths: string[];
visibleConfigs: string[];
authValues: CustomValidationAuthValues;
configValues: CustomValidationConfigValues;
};

Your custom error messages can then be displayed in the app thus:

Note: the use of visibleValues will soon be deprecated

Our demo app shows how the validation process can be managed in the src/lib/configWindow.js, src/components/ConfigWizard.js and src/components/Instance.js files.

Inspection of src/lib/configWindow.js will show a way of using the above data types to handle the 2 key validation events:

  1. The tray.configPopup.validate event from the Config Wizard, when the validation process is started

  2. The tray.configPopup.client.validation event from your app, when the validation has completed

And inspection of src/components/Instance.js shows the setup of an openPopup method which can be used to set the customValidation queryString mentioned above:

Debugging note

When possible, all events will send one or more of the following identifiers:

  • solutionId
  • solutionInstanceId
  • solutionReleaseId
  • userId

This will assist you in debugging issues by identifying exactly what config wizard you want to activate when performing validation.