Setup Form

Use a setup form to collect configuration values in the Fivetran dashboard instead of requiring users to provide all values through configuration.json.

We store configuration values entered through the setup form securely, and we pass them to the schema(configuration) and update(configuration, state) methods at runtime.

When to use a setup form

Define a setup form when your connector needs users to provide credentials or connection-specific settings during connection setup.

Use a setup form if:

• You want users to enter values in the Fivetran dashboard.
• You want to define field labels, descriptions, required fields, placeholders, or selectable options.
• You want to run custom setup tests before users save and test the connection.
• You want to generate a local configuration.json file from the same fields for testing.

If your connector does not need a setup form, you can continue to provide configuration values with a manually created configuration.json file.

Define a setup form

Use ConfigurationForm to define the form, form_field to add fields, and Test to return setup test results.

from fivetran_connector_sdk import Connector
from fivetran_connector_sdk import ConfigurationForm
from fivetran_connector_sdk import Test
from fivetran_connector_sdk import form_field

def configuration_form():
    form = ConfigurationForm()
    form.add_field(form_field.TextField(
        name="api_base_url",
        label="API Base URL",
        field_type=form_field.TextField.plain_text,
        description="The base URL for your API.",
        required=True,
        placeholder="https://api.example.com/v1",
    ))
    form.add_field(form_field.TextField(
        name="api_key",
        label="API Key",
        field_type=form_field.TextField.password,
        description="Your API key.",
        required=True,
    ))
    form.add_test(label="Test connection", func=connection_test)
    return form

def connection_test(configuration: dict):
    # Validate credentials and return success or failure
    test = Test()
    if not configuration.get("api_key"):
        return test.failure("API key is required.")
    return test.success()

connector = Connector(
    update=update,
    schema=schema,
    configuration_form=configuration_form,
)

Register the method by passing it to the Connector object with configuration_form=configuration_form.

Supported field types

Values collected by the local fivetran configuration command are written to configuration.json as strings. For example, toggle values are written as true or false.

Text field

form.add_field(form_field.TextField(
    name="host",
    label="Host",
    field_type=form_field.TextField.plain_text,
    description="The source host name.",
    required=True,
    placeholder="api.example.com",
))

Use a password text field for secrets:

form.add_field(form_field.TextField(
    name="api_key",
    label="API Key",
    field_type=form_field.TextField.password,
    required=True,
))

Dropdown field

form.add_field(form_field.DropdownField(
    name="batch_size",
    label="Batch Size",
    fields=[
        form_field.DropdownFieldParam(value=10),
        form_field.DropdownFieldParam(value=100),
        form_field.DropdownFieldParam(value=500),
    ],
    required=True,
))

To add user-facing option labels and descriptions, provide label and description in DropdownFieldParam:

form.add_field(form_field.DropdownField(
    name="accountSyncMode",
    label="Account sync mode",
    fields=[
        form_field.DropdownFieldParam(
            value="syncAll",
            label="Sync all accounts",
            description="Automatically sync all accounts you access to. New accounts will automatically be synced.",
        ),
        form_field.DropdownFieldParam(
            value="syncSelected",
            label="Sync specific accounts",
            description="Select accounts you have access to sync. New accounts will be excluded, but can be added later.",
        ),
    ],
))

Toggle field

form.add_field(form_field.ToggleField(
    name="enable_metrics",
    label="Enable Metrics",
    description="Log extraction volume metrics during each sync.",
))

Setup tests

Use ConfigurationForm.add_test() to register setup tests. A setup test function must accept one configuration dictionary argument and return Test().success() or Test().failure("message").

def connection_test(configuration: dict):
    # Validate credentials and return success or failure
    test = Test()
    api_key = configuration.get("api_key")
    if not api_key:
        return test.failure("API key is required.")
    return test.success()

def configuration_form():
    form = ConfigurationForm()
    form.add_test(label="Test connection", func=connection_test)
    return form

Fivetran runs registered setup tests when users save and test the connection. You can also run them locally with:

fivetran configuration --test

Generate configuration locally

Run this command from the connector project root after implementing configuration_form() and registering it with configuration_form in the Connector object:

fivetran configuration

The command starts an interactive prompt based on the setup form fields returned by configuration_form() and writes configuration.json in the project directory. If configuration_form() is not registered, the command exits without generating configuration.json. If configuration.json already exists, the command asks for confirmation before overwriting it.

Run setup tests locally with:

fivetran configuration --test

This command reads configuration.json and runs the tests registered with add_test().

End-to-end setup form flow

Use this flow when you want to define setup form fields, test them locally, and then deploy the connector.

1. Implement configuration_form() and register it in the Connector object:

   connector = Connector(
       update=update,
       schema=schema,
       configuration_form=configuration_form,
   )
   

2. Generate local configuration values:

   fivetran configuration
   

   This command prompts for the setup form fields and writes the values to configuration.json.

3. Run setup tests locally:

   fivetran configuration --test
   

4. Deploy the connector with local configuration values using fivetran deploy:

   fivetran deploy --api-key <BASE_64_ENCODED_API_KEY> --destination <DESTINATION_NAME> --connection <CONNECTION_NAME> --configuration configuration.json
   

   Fivetran stores the values from configuration.json securely. In the dashboard, users see the setup form fields populated with those values. Secret values are masked.

5. Or, deploy the connector without local configuration values using fivetran deploy:

   fivetran deploy --api-key <BASE_64_ENCODED_API_KEY> --destination <DESTINATION_NAME> --connection <CONNECTION_NAME>
   

   For a new connection, users see the setup form fields in the dashboard but must enter values before setup tests or syncs can succeed. For an existing connection, omitting --configuration keeps the existing stored configuration values.

Deployment behavior

When you deploy or package a connector, the SDK includes the serialized setup form metadata in the connector package. Fivetran uses this metadata to render the setup form for the connection.

You can still deploy with --configuration configuration.json. Values from configuration.json are stored securely and can pre-populate or update the connection configuration.

For a complete working example, see the configuration_form example.