Render Forms using Actions

Once you create a form, you can render it with Actions using the api.prompt.render() method:

// Example using the post-login trigger

exports.onExecutePostLogin = async (event, api) => {
  api.prompt.render(':form_id');
}

Replace form_id with the ID of the Form. You can locate the ID in the URL of the Form, for example:  ap_pUMG... or select it from the Form editor Embed tab. In the Actions Code editor, you can define the business logic to decide when and how to render the Form.

exports.onExecutePostLogin = async (event, api) => {

  // Only render the form if user is missing company_name metadata
  if (!event.user.user_metadata.company_name) {
    api.prompt.render(':form_id');
  }
}

To learn more about the event object and its contextual information, read Action Triggers: post-login - Event Object.

The api.prompt.render() method lets you add a second argument to populate fields and hidden fields values using the  fields object. In the example below, the field with the ID first_name will be populated with the value Jane. 

exports.onExecutePostLogin = async (event, api) => {
    api.prompt.render(':form_id', {
    fields: {
      first_name: 'Jane',
    }
  });
}

The api.prompt.render() method passes the information to the form on the client-side. To ensure integrity of the data,  sign it with a JSON Web Token (JWT).

exports.onExecutePostLogin = async (event, api) => {
  const context_token = api.redirect.encodeToken({
    secret: event.secrets.MY_SECRET_VALUE, // Use your own secret key with a long random value
    expiresInSeconds: 60,
    payload: {
      user_id: event.user.user_id
    }
  });

  api.prompt.render(':form_id', {
    fields: {
      context_token,
    }
  });
}

• You cannot redirect a user and render a form in the same Action. If you need to use both, consider using different Actions.

• You can only render one form per Action. If you need to render more than one form, you need to render the forms in different Actions.

• The same form can not be rendered more than once across the same trigger. For example, if you have a post-login trigger with two Actions, you can not render the same form in both Actions, you need to create different Forms for each Action.

• The fields property size limit is 24 KB.