Skip to main content

Setup forms

Setup forms transform complex JSON configuration into intuitive, step-by-step user interfaces. These forms guide users through structured input screens that automatically generate proper configuration for applications, eliminating the need to manually construct configuration objects.

The forms use declarative config maps to define structure, validation rules, and UI components, providing a seamless configuration experience for end users.

Core components​

Setup forms integrate several specialized components that work together to provide user-friendly configuration interfaces:

📋

Config Maps

JSON schemas that define form structure, validation rules, and UI widgets for each configuration field

🎨

UI Widgets

Specialized form components like credential selectors, SQL trees, and preflight check validators

📝

Steps Organization

Logical groupings that organize related fields into manageable, sequential configuration phases

⚡

Conditional Logic

Dynamic form behavior that shows or hides fields based on user selections and validation rules

How it works​

Setup forms operate through a declarative configuration system that automatically generates user interfaces from JSON schemas:

  1. Config map definition: Define a JSON schema that specifies form fields, validation rules, UI widgets, and step organization
  2. Schema-driven generation: The Atlan Apps Framework reads the config map and automatically generates the corresponding form with proper validation and styling
  3. User interaction: Users complete the form through guided steps with real-time validation and contextual help
  4. Configuration transformation: The framework validates input and transforms form data into the structure the workflow expects
  5. Workflow execution: The workflow receives the normalized configuration through the standard workflow_config parameter
  6. Setup script integration: The setup script automates the integration process by:
    • Downloading the latest JavaScript and HTML bundle containing setup form components
    • Placing the bundle files in the appropriate directory within your application structure
    • Configuring routing so the form UI automatically loads when users visit the application's homepage

Design principles​

Setup forms follow key design principles that provide consistent, user-friendly configuration experiences:

  • Progressive disclosure: Complex configuration is broken into logical steps, revealing information gradually to prevent cognitive overload
  • Schema-driven consistency: All forms follow the same underlying JSON schema structure, ensuring predictable behavior across different applications
  • Contextual validation: Real-time feedback helps users understand requirements and correct errors immediately rather than after form submission
  • Declarative configuration: Form structure and behavior are defined through configuration rather than code, enabling rapid iteration and customization

See also​

  • Config maps - Complete technical specification for config maps and form configuration
  • Build custom app - Step-by-step implementation of setup forms in a complete application
  • Widget properties - Shared properties available across all form widgets
  • Build UI widgets - Complete widget library and component reference