Autobuild & Build Mode

configure your data import experience with AI assistance and no-code tools

This feature is available only for Projects.
For more information or to upgrade your plan, please reach out to Support.

Overview

Flatfile’s Autobuild and Build Mode features provide powerful tools to configure your data import experience without writing code. These features allow you to:

• Autobuild: Automatically generate a data model from sample files or AI prompts
• Build Mode: Fine-tune your configuration with a visual interface
• Build Mode Chat: Get AI assistance to modify your configuration through natural language

These tools work together to streamline the process of creating and refining your data import experience, making it accessible to both technical and non-technical users.

Autobuild

Autobuild is a feature that automatically generates a data model for your Flatfile space based on sample files or AI prompts. This is an excellent starting point for creating your data import experience.

Starting Autobuild

You can initiate Autobuild from the dashboard or via the API.

From the Dashboard

1. Navigate to your application in the dashboard.
2. Select “Create from Template” or “Autobuild” option.
3. Choose one of the following input methods:
   • Upload a sample file: Provide a CSV, Excel, or other supported file format
   • Enter field names: Manually specify the fields you need
   • Use AI prompt: Describe your data model in natural language
   • Start empty: Begin with a blank configuration

From the API

1. Obtain your Secret Key from the API Keys page.
2. Make an authenticated request to the autobuild endpoint.

file upload

curl -X POST https://api.x.flatfile.com/v1/apps/{appId}/autobuild?environmentId={environmentId} \
  -H "Authorization: Bearer sk_123" \
  -F "file=@sample.csv"

Autobuild Process

When you initiate Autobuild, Flatfile performs the following steps:

1. Analysis: Examines your input (file, fields, or prompt) to understand the data structure
2. Model Generation: Creates a data model with appropriate fields, types, and validations
3. Space Creation: Sets up a working space with the generated model
4. Agent Deployment: Deploys a constraints agent to handle validation rules
5. Transition to Build Mode: Opens the working space in Build Mode for further refinement

The Autobuild process typically takes a few seconds to complete, depending on the complexity of your input.

Build Mode

Build Mode is a visual interface for configuring your Flatfile space. It allows you to modify workbooks, sheets, fields, and other aspects of your data model without writing code.

Accessing Build Mode

You can access Build Mode in two ways:

1. After Autobuild: Build Mode opens automatically after Autobuild completes
2. From an existing Space: Click the “Enter Build Mode” toggle in the sidebar

Build Mode Interface

The Build Mode interface consists of several components:

Header

The header provides navigation and context for your current Build Mode session:

• Mode Selector: Switch between Configuration and Assistant modes
• View Selector: Toggle between Blueprint and Data Preview views
• Done Button: Exit Build Mode when finished

Blueprint View

The Blueprint view displays a hierarchical representation of your data model:

• Workbooks: Collections of related sheets
• Sheets: Individual data tables
• Fields: Columns within sheets, including their types and properties

Data Preview

The Data Preview shows how your data will appear to users, allowing you to:

• View sample data in your configured sheets
• Test field validations and transformations
• Verify the overall user experience

Configuration Sidebar

The Configuration sidebar provides tools for modifying your data model:

Blueprint Configuration

The Blueprint tab allows you to:

• Add, edit, or remove workbooks, sheets, and fields
• Configure field types, validations, and transformations
• Set up relationships between sheets
• Define custom actions and hooks

Show Field Configuration Options

type

string

The data type for the field (e.g., string, number, date)

label

string

Display name for the field

description

string

Helpful text explaining the field’s purpose

required

boolean

Whether the field must have a value

unique

boolean

Whether values must be unique across records

constraints

array

Validation rules for the field

Theme Configuration

The Theme tab lets you customize the visual appearance of your space:

• Set primary and accent colors
• Configure typography and spacing
• Customize component styles
• Preview changes in real-time

Sidebar Configuration

The Sidebar tab allows you to configure the sidebar that users see in your space:

• Add or remove sidebar sections
• Configure custom links and actions
• Set up document sections
• Arrange the order of sidebar elements

Build Mode Chat

Build Mode Chat provides AI assistance for configuring your Flatfile space through natural language. This feature makes it easy to make complex changes without understanding the underlying technical details.

Build Mode Chat requires the buildModeChat entitlement. If you don’t see this feature, contact your account administrator.

Accessing Build Mode Chat

To access Build Mode Chat:

1. Enter Build Mode for your space
2. Select “Assistant” from the mode dropdown in the header

Using Build Mode Chat

The Build Mode Chat interface provides a conversational way to modify your configuration:

1. Ask Questions: Inquire about your current configuration or how to make changes
2. Request Changes: Ask the assistant to modify workbooks, sheets, fields, or other elements
3. Get Explanations: Learn about best practices and configuration options
4. Preview Changes: See the effects of your changes in real-time

Show Example Chat Interactions

Add a field

request

“Add a phone number field to the Contacts sheet with proper validation”

Modify validation

request

“Make the email field required and ensure it’s properly validated”

Create relationships

request

“Set up a relationship between the Orders sheet and the Customers sheet”

Theme changes

request

“Change the primary color to match my brand (#3366FF)“

Chat Sessions

Each chat session is associated with a unique thread ID, allowing you to:

• Start new conversations for different tasks
• Maintain context within a conversation
• Reference previous changes and discussions

To start a new chat session, click the “New Chat” button in the header.

Advanced Capabilities

Workbook Management

Workbooks are the primary containers for your data model in Flatfile. The Build Mode Chat provides powerful capabilities for managing workbooks:

Workbook Structure

• Create and Modify Workbooks: Define new workbooks or modify existing ones through natural language
• Sheet Organization: Arrange sheets within workbooks in a logical order
• Metadata Configuration: Add custom metadata to workbooks for integration with external systems
• Sheet Relationships: Establish relationships between sheets for data integrity

Workbook Operations

• Update Workbook Properties: Change workbook names, slugs, and descriptions
• Sheet Ordering: Rearrange the order of sheets within a workbook
• Composite Unique Constraints: Create multi-field unique constraints across sheets
• Toggle Field Properties: Make fields required or unique with simple commands

Sheet Management

Sheets represent individual data tables within workbooks. Build Mode Chat provides comprehensive tools for sheet management:

Sheet Operations

• Create and Delete Sheets: Add new sheets or remove existing ones
• Update Sheet Properties: Modify sheet names, slugs, and metadata
• Field Management: Add, remove, or modify fields within sheets
• Data Validation: Configure validation rules at the sheet level

Sheet Configuration

• Field Ordering: Arrange fields in a logical sequence
• Sheet Metadata: Add custom metadata for integration purposes
• Sheet-level Actions: Configure actions that operate on entire sheets
• Sheet Visibility: Control which sheets are visible to users

Field Management

Fields are the individual data elements within sheets. Build Mode Chat provides detailed control over field configuration:

Field Types and Properties

• Data Types: Configure appropriate data types (string, number, date, boolean, etc.)
• Field Labels: Set user-friendly display names for fields
• Field Descriptions: Add helpful descriptions for users
• Required Fields: Mark fields as required or optional
• Unique Fields: Enforce uniqueness constraints on field values
• Default Values: Set default values for fields

Field Validation

• Validation Rules: Create custom validation rules for fields
• Format Validation: Enforce specific formats (email, phone, etc.)
• Range Validation: Set minimum and maximum values for numeric fields
• Pattern Matching: Use regular expressions for advanced validation
• Custom Error Messages: Define user-friendly error messages for validation failures

Custom Actions

Actions allow users to perform operations on data within Flatfile. Build Mode Chat provides tools for creating and managing actions:

Action Types

• Workbook Actions: Actions that operate on entire workbooks
• Sheet Actions: Actions that operate on specific sheets
• Field Actions: Actions that operate on individual fields
• Document Actions: Actions that operate on documents

Action Configuration

• Operation Definition: Define what the action does
• Action Triggers: Configure when actions are available (button click, automatic, etc.)
• Confirmation Requirements: Set whether actions require user confirmation
• Action Modes: Configure how actions behave (primary, secondary, etc.)
• Custom Icons: Set custom icons for actions
• Action Descriptions: Add helpful descriptions for users

Action Listeners

• Custom Logic: Implement custom business logic for actions
• Data Transformation: Transform data during action execution
• External Integration: Connect actions to external systems
• Progress Updates: Provide feedback during long-running actions
• Error Handling: Implement robust error handling for actions

Data Transformation

Build Mode Chat provides tools for configuring data transformation capabilities:

Extractors

• Data Extraction: Configure extractors to pull data from specific sources
• Format Conversion: Transform data between different formats
• Data Cleaning: Remove unwanted characters or formatting
• Value Normalization: Standardize data values for consistency

Automapping

• Field Mapping: Automatically map source fields to destination fields
• Value Transformation: Transform values during mapping
• Default Values: Set default values for unmapped fields
• Mapping Rules: Create custom rules for complex mapping scenarios

Autocasting

• Data Type Conversion: Automatically convert data types
• Format Standardization: Standardize date formats, number formats, etc.
• Value Normalization: Normalize values to a standard format
• Error Handling: Configure how type conversion errors are handled

Document Management

Documents provide additional context and guidance for users. Build Mode Chat offers tools for document management:

Document Types

• Guides: Step-by-step instructions for users
• Reference Materials: Additional information about data requirements
• Help Documentation: Assistance for common tasks
• Custom Documents: Any additional documentation needed for your use case

Document Operations

• Create Documents: Add new documents to your space
• Update Documents: Modify existing documents
• Delete Documents: Remove unnecessary documents
• Document Actions: Configure actions that operate on documents

Publishing Your Configuration

After configuring your space in Build Mode, you can publish your configuration to make it available for production use:

1. Click the “Done” button in the Build Mode header
2. Review your changes in the summary view
3. Click “Publish” to finalize your configuration

Publishing creates a snapshot of your configuration that can be used as a template for creating new spaces.

Technical Architecture

The Build Mode Chat system is powered by a sophisticated orchestration layer that manages interactions between the user interface and the underlying Flatfile API:

Component Architecture

• Chat Interface: Provides a natural language interface for users
• Orchestrator Agent: Processes user requests and coordinates tool execution
• Tool System: Provides specialized tools for different operations
• Language Models: Powers the natural language understanding and generation
• Flatfile API Client: Communicates with the Flatfile API to make changes

Tool Categories

• Reference Tools: Provide information without making changes

  • loadBlueprint: Retrieves the current configuration
  • getRecords: Retrieves data from sheets
  • getRules: Retrieves validation rules
  • listDocuments: Lists available documents
  • flatfileAPIDocumentation: Provides API documentation
  • flatfileGeneralDocumentation: Provides general documentation
  • tavilySearch: Searches for relevant information
  • currentDatetime: Provides the current date and time
  • customerKBAssistant: Provides customer-specific knowledge

• Action Tools: Make changes to the configuration

  • updateWorkbook: Updates workbook properties
  • updateSheet: Updates sheet properties
  • deleteSheet: Removes a sheet
  • renameField: Renames a field
  • generateRule: Creates validation rules
  • addExtractor: Adds data extractors
  • deployActionListener: Deploys custom action handlers
  • deployAutomap: Configures field mapping
  • deployAutocast: Configures data type conversion
  • deployWebhookEgress: Sets up webhook integrations
  • generateActionConfig: Creates action configurations
  • generateGuide: Creates user guides
  • createDocument: Adds new documents
  • updateDocument: Modifies existing documents
  • deleteDocument: Removes documents
  • deleteRecords: Removes data records
  • deleteRule: Removes validation rules

Tips & Best Practices

1. Start with a representative sample file that includes all the fields and data types you need
2. Use descriptive field names and labels to make your configuration more intuitive
3. Add field descriptions to provide context for users
4. Test your configuration with sample data before publishing
5. Use Build Mode Chat for complex changes or when you’re unsure how to implement something
6. Create a consistent theme that matches your brand identity
7. Configure appropriate validations to ensure data quality
8. Organize related fields into logical sheets and workbooks
9. Implement custom actions for common operations to improve user efficiency
10. Create comprehensive documentation to guide users through the data import process
11. Use composite unique constraints for complex uniqueness requirements
12. Configure field relationships to maintain data integrity
13. Implement data transformations to standardize incoming data
14. Set up webhooks for integration with external systems
15. Use action listeners to implement custom business logic

For complex configurations, consider breaking down your changes into smaller steps and testing each change incrementally.

Troubleshooting

Issue	Solution
Autobuild fails to analyze file	Verify your file is in a supported format (CSV, Excel, etc.) and contains valid data
Field types are incorrectly detected	Manually adjust field types in Build Mode Blueprint configuration
Build Mode Chat doesn’t appear	Reach out to Support to enable Projects on your account
Changes aren’t reflected in preview	Refresh the Data Preview view or toggle between Blueprint and Data Preview
Configuration can’t be published	Ensure all required fields and validations are properly configured

Common Issues

1. Action Deployment Failures: Ensure your action code is valid and follows the required format
2. Validation Rule Errors: Check that your validation rules use the correct syntax and field references
3. Field Type Mismatches: Verify that field types are appropriate for the data being imported
4. Relationship Configuration Issues: Ensure that related fields have compatible types
5. Performance Problems: Optimize complex validation rules and action handlers

Getting Help

If you encounter issues with Build Mode or Build Mode Chat:

1. Check Documentation: Review the Flatfile documentation for guidance
2. Ask the Assistant: Use Build Mode Chat to ask for help with specific issues
3. Contact Support: Reach out to Flatfile support for assistance with complex problems
4. Community Forums: Engage with the Flatfile community for advice and best practices