Missed DevDay24? Register for the Best of DevDay

User Onboarding Template

"Onboarding Template"

About this template

Personalize your onboarding experience by requiring additional information when a visitor creates an account to become a user of your application. This onboarding flow is useful for SaaS businesses that want to categorize their users or if you require specific information to provision a user account.

This "User onboarding" template includes the following:

  1. An initial step that requires the user to decide whether to sign up as a business or an individual.
  2. A router that evaluates the next step based on the user's choice.
    • If the user wants to sign up as a business, the form will render the company name and company size fields.
    • If the user wants to sign up as an individual, the form will render the full name and job title fields.
  3. When the user completes the form, a flow will update the user_metadata and resume the authentication flow.

How to configure this template

Visit the Auth0 Dashboard and then open the Forms Dashboard by clicking the Actions > Forms option from the sidebar. Once there, click the "Create form" button.

You have two options for creating this form: you can use a template or import a JSON file.

Use a template

  1. Click the "Use a template" option in the "Create form" modal.
  2. Click the "User onboarding" template.
  3. Click the "Continue" button to customize the template to fit your use case.

Import a JSON file

  1. Download the template JSON file.
  2. Click the link to import a JSON file at the bottom of the "Create form" modal.
  3. Either drag and drop the JSON file you downloaded or browse to its location and upload it.
  4. Provide a name to your form and its flow if the default values are not fitting.
  5. Click the "Continue" button to customize the template to fit your use case.

How to use this form

You can render a form with an Action using the api.prompt.render() method, which takes the form ID as an argument.

There are different ways in which you can find your form ID:

  • On the Forms Dashboard home page, you can see a list of your existing forms. Each entry includes a "Title" and "Form ID" field, which you can copy.
  • If you are using the Form Editor in the Forms Dashboard:
    • Click the "Render" tab to see the sample code that contains the FORM_ID value.
    • Alternatively, you can inspect the URL which follows this pattern:
https://forms.auth0.com/tenants/<REGION>/<TENANT>/forms/<FORM_ID>/render

Once you have located your Form ID, copy and paste it in the following field so that any code snippet that uses such value updates to reflect it:

It's best to render the "User onboarding" form during the login flow. As such, you need to create a Login Action to render it by following these steps:

  1. Visit the "Flows" section of the Auth0 Dashboard and select the "Login" flow.
  2. Locate the "Add Action" panel in the "Login" flow board and click the + icon button.
  3. Select the "Build from scratch" option.
  4. Provide a name to your Action and click the "Create" button.
Action name
User onboarding
  1. Replace the default code in the Actions editor with the following code:
    • Note: Ensure that you replace the AUTH0_FORM_ID placeholder with your form ID.
Action
/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {
  const FORM_ID = 'AUTH0_FORM_ID';
  
 if (!event.user.user_metadata.account_type) {
    api.prompt.render(FORM_ID);
  }
}


/**
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onContinuePostLogin = async (event, api) => {}
  1. Click the "Deploy" button.
  2. Next, click on the "Add to flow" link in the toast message that comes up, or click on the "Back to flow" link to return to the "Login" flow board.
  3. Locate the "Add Action" panel in the "Login" flow board, click the Custom tab, and drag-and-drop the "User onboarding" Action between the "Start" and "Complete" states in the board.
  4. Finally, click the "Apply" button in the top-right corner.

Now, when any user attempts to log in, this Action checks if the user has either an event.user.user_metadata.company_name or event.user.user_metadata.full_name property defined, depending on their chosen onboarding type (individual or business). If none of those properties is defined, this Action will render your "User onboarding" form and require the user to provide the necessary information before they can complete their login flow.