Skip to content

Guided setup

An app can ship a Studio wizard that walks someone through configuring the bot after install. The wizard is a Bubblescript file named guided_setup. If that file exists, Studio shows a Guided setup item in the bot menu for users who can edit the bot.

The file is part of the app, so it is copied onto the installed bot with the rest of the scripts. It runs in that bot's context. It does not share functions, constants, or dialogs with other files; keep everything the wizard needs in guided_setup itself.

Create the file in the native app (title guided_setup, type Bubblescript). Studio fills in a template that only shows the channels step. That is a complete wizard. Change setup_init when you need more steps.

Leave guided_setup out of editable_scripts unless you want people who installed the app to edit the wizard.

Callbacks

Three functions drive the wizard:

  • setup_init() is called once when the user opens Guided setup. It must return a setup built with Setup.new/1.
  • setup_step(setup, step) is called every time the user completes a step. It receives the setup as it currently stands and the completed step, including the data the user filled in. The step is not part of the setup yet: putting it back with Setup.replace_step/2 accepts the change; returning the setup without it rejects the change. Returning a further modified setup is how steps are added, removed, skipped or pre-filled while the wizard is running.
  • setup_finish(setup, per_step_data) is called after the last step is accepted. per_step_data is a map keyed by step id. This is where you write scripts and call APIs. The return value is ignored; the call must succeed. Raise or fatal to fail the finish.

Every step is rendered as a header with the title and description, an optional list of best practices, the form described by the step's schema and ui_schema, and a button to continue. Disabled steps are skipped.

A minimal wizard:

function setup_init() do
  return Setup.new(
    steps: [
      Setup.step(
        id: "greeting",
        name: "Greeting",
        title: "Greeting",
        description: "How the bot says hello",
        schema: %{"type" => "string"},
        ui_schema: %{}
      ),
      Setup.channels_step()
    ]
  )
end

function setup_step(_setup, _step) do
  return Setup.replace_step(_setup, _step)
end

function setup_finish(_setup, _data) do
  write_script("settings", yaml_build(%{"greeting" => _data.greeting}), type: "text/yaml+data")
end

write_script is allowed during guided setup. It writes the draft; a publish is still required to put the change live.

After a successful finish, Studio shows that setup is complete and returns to the bot home.

Platform steps

The platform provides three steps you can drop in. Their IDs are fixed. You can override name, title, description, and best_practices; the form itself is owned by the platform, and so is the data setup_step receives.

  • Setup.channels_step() ("$channels"). The user enables and configures channels. Data: %{"channel_names" => ["phone", "email"]}.
  • Setup.knowledgebase_step() ("$knowledgebase"). The user picks or creates knowledge bases and uploads documents. Data:

%{ "knowledge_bases" => [ %{ "id" => "example", "label" => "Example", "strategy" => "managed_vertex_rag" } ] }

  • Setup.review_step() ("$review"). Recap of steps that have a review field. Submitting it runs setup_finish. This step has no data of its own.

Custom steps

Setup.step/1 builds a form from a JSON schema and a uiSchema. Forms use the same stack as the CMS; see Content management for widgets.

id is how setup_step recognises the step. name is the breadcrumb label and is required. title and description are the heading on the page.

Callouts between the header and the form:

Setup.best_practice(
  icon: "tick",
  title: "Keep instructions concise",
  description: "Focus on clear rules instead of a broad brief."
)

icon is a Blueprint icon name.

To show a step on the review page, set _step.review in setup_step, or pass :review when you build the step:

_step.review = Setup.review(
  title: "Greeting",
  icon: "chat",
  value: _step.data,
  ui_schema: %{}
)

Review is not a form. Supported widgets: markdown, channels (or channel), tags (or tag, badge, badges), icon. Objects are shown as labeled fields; ui:title overrides the label; horizontal: true in ui:options lays them out in a row.

Changing steps while the wizard runs

setup_step can return a different list of steps than setup_init did. Setup.insert_after/3, Setup.insert_before/3, Setup.append_step/2, Setup.delete_step/2, Setup.set_disabled/3, and Setup.set_data/3 are the usual tools. Disabled steps are skipped.

If the user goes back and changes an earlier step, setup_step runs again for that step. Prefills you apply then will overwrite later steps unless you check.

Trying it

On the native app, the same Guided setup menu item runs the wizard against the bot you are editing. Publish the app and install it to see the copy that ships to customers.

The Setup.* functions are listed in the Guided setup reference.