Process forms

6 min

While Optimizely Connect Platform (OCP) renders settings forms, your app is responsible for processing and saving the data users submit through the form. Your app's lifecycle handler includes an `onSettingsForm method` to handle form submission from the settings form.

When your app receives a request to handle actions on the settings form, you should verify the data, perform any remote configuration required at that time, and, if everything is successful, save the data to the settings store. Or, if there are errors, create helpful error messages for the user.

Users can only edit one section of a form at a time, so you do not have to worry about validating across sections simultaneously. However, you may wish to use the configuration from other sections when validating user selections. As with any other functions, you have complete access to the settings store to read any other configuration saved by the user if needed.

Return responses and errors

The onSettingsForm handler is expected to return a `LifecycleSettingsResult``LifecycleSettingsResult`. You can provide error messages and toast notifications to the user and even send them to another next section of your settings form through the LifecycleSettingsResult.

Use addError to display an error below a particular form element or addToast to display a toast notification to the user.

Direct users to another section

When handling a submission through onSettingsForm, you can move the user to a new form section. For example, after a user submits their credentials in an auth section, if successful, you should move them to a configuration section so they know there is more to do before the integration starts working.

if (Authorized(formData)) {
  result.addToast('success', 'Authenticated!');
  result.redirectToSettings('configure');
} else {
  result.addToast('error', 'Invalid username or password. Please check your credentials and try again.');
}

Set the default section

The most useful section for a user to see is not always the first one. When a user opens the Settings tab of your app in the OCP App Directory, you may want to display another section by default. For example, after authentication is complete, there is no reason to show the auth section even if it makes sense as the first section. You can change the default section at any time by using `Form.setDefaultSection`.

With the following example, the next time the user opens the Settings tab of your app in the OCP App Directory, the Configure section displays by default:

await Form.setDefaultSection('configure');

Best practices

Provide meaningful feedback in both success and error cases. For example, say "Successfully scheduled your import job. You will see new data populate within the next hour." or "Authorization successful" instead of relying on generic success messages.

Use form predicates to display instructions to the user. For example, you can display instructions inline in the form after authorization is complete using a visibility predicate and a page property rather than trying to provide lengthy instructions in a toast notification.

Save necessary form data when successful to ensure the form remains updated and the user can visually see their changes.

Direct users to the section they need. For example, separate authentication from other configuration options. Set the default section to guide users. When a user completes a section, redirect them to the next most useful section.

Example

/**
   * Handle a submission of a form page/section. You are responsible for performing any validation or
   * changes to the form data and then writing it to the settings store for the page.
   * @param page the name of the page/section submitted
   * @param action the action of the button that triggered the call, or 'save' by default
   * @param formData the data for the section as a hash of key-value pairs
   * @param result the response to return. Add any errors or toasts to the result before returning it.
   * @returns {LifecycleSettingsResult} with any errors that should be displayed to the user
   */
  public async onSettingsForm(
    section: string, action: string, formData: SubmittedFormData
  ): Promise<LifecycleSettingsResult> {
    const result = new LifecycleSettingsResult();
    try {
      switch (section) {
        // handle each section and action separately
        case 'authentication':
          if (await validateCredentials(formData.username, formData.password)) {
            // you can augment the form data before saving to aid form logic
            formData.authorized = true;
            // Redirect the user to the next section and let them know it was successful
            result.AddToast('success', 'Authenticated!');
            result.redirectToSettings('configure');
            await Form.setDefaultSection('configure');
          } else {
            return result
              .addError('username', 'Your username must be the email address you use to log in to <integration>')
              .addToast('error', 'Invalid username or password. Please check your credentials and try again.');
          }
          break;
      }

      // if you did not produce any errors, you should save the form data to the settings store
      storage.settings.put(section, formData);
      return result;

    } catch (e) {
      logger.error(e);
      return result.addToast('error', 'An unexpected error occurred. Please try again at a later time');
    }
  }