Setup Wizard Guide

The Setup Wizard provides a guided onboarding experience for users installing your extension. Instead of dumping users on a configuration page, the wizard walks them through each step with context and validation.

Why Use a Setup Wizard?

• Better User Experience: Step-by-step guidance reduces confusion
• OAuth Flow Integration: Built-in OAuth popups and token storage
• Validation: Ensure credentials work before activation
• Progress Tracking: Users can see what's done and what's next
• Skippable Steps: Optional steps can be deferred for later

Defining a Wizard

Add a setup array to your extension manifest:

model_version: "1.0"
extension:
  id: dev.mycompany.slack-notifier
  name: Slack Notifier
  version: 1.0.0

  setup:
    - secrets:
        title: Connect to Slack
        description: Authorize Kiket to send messages to your Slack workspace.
        fields:
          - key: slack_oauth
            label: Slack Connection
            type: oauth_token
            required: true
            obtain:
              type: oauth2
              provider: slack
              scopes: ["chat:write", "channels:read"]
              store_as: org.slack_access_token

    - configure:
        title: Choose Channel
        description: Select which channel should receive notifications.
        fields:
          - key: default_channel
            label: Default Channel
            type: string
            placeholder: "#general"
            required: true

    - test:
        title: Test Connection
        description: We'll send a test message to verify everything works.
        check_endpoint: /api/v1/extensions/health

    - info:
        title: You're All Set!
        markdown: |
          ## Slack Notifier is Ready

          You'll now receive notifications in **{{ configuration.default_channel }}** when:
          - Issues are created
          - Issues are assigned to you
          - Comments are added to watched issues

          [View Documentation](https://docs.example.com/slack)

Step Types

Secrets Step

Collects OAuth tokens, API keys, and other credentials.

- secrets:
    title: Connect Your Account
    description: Optional description text.
    fields:
      - key: oauth_connection
        label: OAuth Connection
        type: oauth_token
        required: true
        obtain:
          type: oauth2
          provider: zoom
          client_id: ext.zoom_client_id
          client_secret: ext.zoom_client_secret
          authorization_url: https://zoom.us/oauth/authorize
          token_url: https://zoom.us/oauth/token
          scopes: ["meeting:read", "meeting:write"]
          store_as: org.zoom_access_token

Obtain Types:

Type	Use Case
oauth2	Standard OAuth 2.0 flow (user authorization)
oauth2_client_credentials	Server-to-server OAuth (no user)
api_key	Manual API key entry
token	Manual token paste
input	Free-form text
basic	Username + password
auto_generate	Platform generates (e.g., webhook secrets)

Configure Step

Collects non-sensitive configuration values.

- configure:
    title: Notification Settings
    fields:
      - key: notify_priority
        label: Minimum Priority
        type: select
        options:
          - { value: all, label: All Issues }
          - { value: high, label: High and Critical }
          - { value: critical, label: Critical Only }
        default: all

      - key: include_comments
        label: Include Comment Notifications
        type: boolean
        default: true

      - key: custom_prefix
        label: Message Prefix
        type: string
        placeholder: "[Kiket]"
        showWhen:
          field: include_comments
          value: true

Field Types:

Type	Renders As
string	Text input
text	Textarea
boolean	Toggle/checkbox
number	Number input
select	Dropdown
url	URL input with validation
email	Email input with validation

Test Step

Verifies credentials and connectivity.

- test:
    title: Verify Connection
    description: Testing your credentials...
    check_endpoint: /api/v1/extensions/health
    timeout: 10000
    on_failure:
      message: |
        Connection failed. Please check:
        - Your API credentials are correct
        - The Slack app has the required scopes
      retry: true
    on_success:
      message: Connected successfully!

The test step calls your extension's health endpoint with the configured credentials. Return a 2xx status to pass, or 4xx/5xx to fail.

Info Step

Displays information using Markdown.

- info:
    title: Setup Complete
    icon: bi-check-circle-fill
    markdown: |
      ## You're all set!

      Your integration is now active. Here's what to expect:

      - Notifications will appear in Slack within seconds
      - Use `/kiket` slash command for quick actions

      ### Next Steps
      1. [Configure notification rules](https://docs.example.com/rules)
      2. [Set up team mentions](https://docs.example.com/mentions)

Conditional Fields

Use showWhen to show/hide fields based on other field values:

fields:
  - key: auth_type
    label: Authentication Type
    type: select
    options:
      - { value: oauth, label: OAuth 2.0 }
      - { value: api_key, label: API Key }
      - { value: basic, label: Basic Auth }

  # Only shown when auth_type is "api_key"
  - key: api_key
    label: API Key
    type: string
    required: true
    showWhen:
      field: auth_type
      value: api_key

  # Shown for multiple values
  - key: api_region
    label: API Region
    type: select
    showWhen:
      field: auth_type
      values: [api_key, basic]

Credential Scopes

Credentials are prefixed to indicate who provides them:

Prefix	Provider	Storage Location
ext.*	Extension developer	Publisher Dashboard
org.*	Organization admin	Extension Settings
user.*	Individual user	User Settings

Example flow for ext.* + org.*:

1. Developer creates Zoom OAuth app
2. Developer enters ext.zoom_client_id and ext.zoom_client_secret in Publisher Dashboard
3. User installs extension
4. Wizard initiates OAuth flow using developer's app
5. User authorizes, token stored as org.zoom_access_token

CLI Commands

Preview your wizard locally:

# Validate wizard configuration
kiket extensions lint

# Preview wizard steps in terminal
kiket extensions wizard:preview

Best Practices

1. Start with OAuth: If your extension needs OAuth, make that the first step
2. Group Related Fields: Keep configuration steps focused on one area
3. Provide Defaults: Use sensible defaults to reduce friction
4. Test Step Matters: Always include a test step to validate before activation
5. Clear Info: End with an info step summarizing what was configured
6. Help Links: Include links to documentation for complex setups

Troubleshooting

Issue	Solution
OAuth popup blocked	Ensure popups are allowed; wizard retries automatically
Test step fails	Check your extension health endpoint returns 2xx
Fields not saving	Verify field key values are unique within the step
Wizard not showing	Ensure setup array is under extension in manifest

See Also

• Manifest Specification - Full schema reference
• Secret Store - How credentials are stored
• Partner Credentials - Setting up ext.* credentials