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');
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}

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 Render 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');
  }
}

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}

To learn more these objects, review:

• Event Object: Learn about the Event objects and properties.

• API object: Learn about the API objects and methods.

You can populate values for existing fields and hidden fields using the fields property as a second argument in your render method.

In the example below, the value Jane populates first_name field. 

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

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}

You can inject server-side variables using the vars property as a second argument in your render method. This can be used to inject sensitive information without exposing it to the client-side.

In the example below, the value 123456789 populates the variable external_user_id. 

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

exports.onContinuePostLogin = async (event, api) => {
  // Add your logic after completing the form
}

Fields and shared variables data collected, in your forms, is automatically available with the event.prompt in the resume function of the current action:

• The id property, with the prompt ID you're rendering.

• The fields object, which contains all your fields and hidden fields data.

• The vars object, which contains all your shared variables data.

{
  "id": "ap_fuVuFiiQWN3mTEujWTy966",
  "fields": {
    "first_name": "Jane",
    "company_name": "Okta"
  },
  "vars": {
    "external_crm_uuid": "f8f32e6f-2329-49bd-bf21-fa8b0bea2652",
    "api_hostname": "api.example.com"
  }
}

In the example below, the api.user.setUserMetadata populates the user_metadata company_name attribute with the event.prompt.fields.company_name property that was collected from your form.

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

exports.onContinuePostLogin = async (event, api) => {
  api.user.setUserMetadata('company_name', event.prompt.fields.company_name);
}

• 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.

• The api.prompt.render() method is available in the following triggers:

  • post-login

  • post-challenge