Validating user configuration

If a custom integration is configurable, it can check if the user-supplied data is valid and, if it's not, prompt the user to provide new data.

This topic explains how to validate the user's configuration.

Prerequisites

  • You have an integration that supports user configuration.
  • You understand TypeScript.

Step 1: Enable installation validation

The feature that validates a user's configuration is known as installation validation. (This is a bit of a misnomer, as validation also occurs when the user changes the integration's configuration.)

To enable installation validation, create a TypeScript file in the same directory as a manifest.json file:

touch installationValidation.ts

(The name of the file isn't important.)

Then, in the manifest.json file, add an installationValidation.tsFile property to the features object:

{
  "features": {
    "installationValidation": {
      "tsFile": "installationValidation.ts"
    }
  }
}

This property should contain a relative path to the TypeScript file.

Step 2: Get the user's configuration

In the TypeScript file, create a function named validationInstallation:

function validateInstallation(config) {
  // code goes here
}

FL0 calls this function at the following points in time:

  • When the user attempts to install an integration.
  • When the user attempts to update the integration's configuration.

The function itself receives a config object as its only parameter. This object contains the user-supplied data. Each property corresponds to one of the items in the installation.configurationItems array.

For example, if the manifest.json file contains the following installation property:

{
  "installation": {
    "configurationItems": [
      {
        "key": "websiteName",
        "name": "Website Name",
        "description": "The name of Online Store website",
        "dataType": "string"
      }
    ]
  }
}

Then the config object contains a websiteName property:

function validateInstallation(config) {
  console.log(config.websiteName);
}

Step 3: Validate the user's configuration

In the validateInstallation function, write the logic that validates the user-supplied data. This could be as simple as checking if a value exists:

function validateInstallation(config) {
  if (!config.websiteName) {
    // Invalid
  }

  // Valid
}

But the validation can be more sophisticated. For example, FL0 provides methods for sending HTTP requests, which an integration could use to check the user-supplied data against the values in a database.

Step 4: Return a validation result

The validateInstallation function must return a ValidationResult object. This object indicates if the validation was successful or not.

At a minimum, the ValidationResult object must have an isValid property, which can contain a value of true or false.

If the isValid property is false, the object must also contain a human readable error message in an errorMessage property.

The following snippet demonstrates the usage of a ValidationResult:

function validateInstallation(config) {
  if (!config.websiteName) {
    return {
      isValid: false,
      errorMessage: "Please provide a name for the website",
    };
  }

  return { isValid: true };
}