In the Dev Dashboard, you may provide a validation URL for a step, which Envoy will hit after that step is complete, but before saving the config values. This validation URL allows you to control what gets saved. For example, you may only want a subset of the values to be saved, or you may want to do some processing or validation of the values before saving.

📘
Note that for OAuth2 and Popup step types, a validation URL is required in order to save the results of that step. For the Form step type, it is optional, and the results of the form will be saved automatically in the absence of a validation URL.

Accessing step results

The results of a step will be in the validation URL's request payload. In the Node.js SDK, you can access this under req.envoy.payload.

For form step types, the payload will be an object whose keys match the keys you set for each form element in the Dev Dashboard. The values for each key will be the user input.
For OAuth2 step types, the payload will be the exact results of the OAuth2 flow. This is typically an access_token and usually a refresh_token.
For Popup step types, the payload will be whatever query params were passed to the Callback URL.

Saving values

To save specific values for a step, simply respond to the validation URL request with a JSON object containing the values you wish to save. This object will get merged with the existing config object, ignoring the initial payload's values. If a user returns to a previously completed step, these saved values are used to populate the fields.

Stopping a step

You can also validate that the values conform to what you expect. If they are invalid, you can return a 4xx HTTP status, along with an object that has a message attribute. If you're using the Node.js SDK, you can use res.sendFailed. This will display the message to the user and prevent them from advancing to the next step.

Config usage

Once items have been saved in the plugin's config, the config object is accessible in any future route or worker. In the Node.js SDK, it is available under req.envoy.meta.config.

If necessary (for example in non-Envoy requests), you can get or set the items in the config at any time via API calls in the Plugin API.

The response to this should also be a JSON object of data you wish to save in the installation config.

app.post('/validate-me', (req, res) => {
  const {
    envoy: {
      payload: {
        foo,
      },
    }
  } = req;
  res.send({
    foo, // we will save the original "foo" from the payload
    bar: 'hello world', // along with a new "bar" variable
  });
});

You may also choose to not to save any data in the config, and instead opt for storage instead.

app.post('/validate-me', async (req, res) => {
  const {
    envoy: {
      installStorage,
      payload: {
        password,
      },
    }
  } = req;
  await installStorage.set('password', password);
  res.send({});
});

You can also fail the validation by sending back a 4xx or 5xx error, along with a message to display to the installer.

app.post('/validate-me', (req, res) => {
  res.status(400).send({ message: 'These values are bad.' });
});

For convenience, the Node.js SDK has a helper function for this.

app.post('/validate-me', (req, res) => {
  res.sendFailed('These values are bad.');
});