Setup Form Private Preview

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.

configuration_form() method

Optional method that defines the setup form shown for your Connector SDK connection. Use this method when you want users to provide configuration values in a connection setup form in the Fivetran dashboard instead of relying only on a manually created configuration.json file.

Signature

configuration_form()

Returns

Returns a ConfigurationForm object containing form fields and optional setup tests.

Example

def configuration_form():
    form = ConfigurationForm()
    form.add_field(form_field.TextField(
        name="api_key",
        label="API Key",
        field_type=form_field.TextField.password,
        required=True,
    ))
    form.add_test(label="Test connection", func=connection_test)
    return form

connector = Connector(
    update=update,  # required; add schema=schema if you define a schema
    configuration_form=configuration_form,
)

Notes

• The configuration_form() method is optional.
• Pass it to the Connector object using configuration_form=configuration_form, as shown in the example above.
• Field values are passed to schema() and update() through the configuration dictionary.

Required imports

Import the following when you define a setup form:

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

• ConfigurationForm — defines setup form fields and setup tests.
• form_field — provides supported setup form field types.
• Test — returns success or failure results from setup test functions.

If you implement an optional setup form, declare the Connector object as follows:

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

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.

For a complete working example, see the configuration_form example.

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

fivetran configuration command

Interactively collects configuration values from setup form fields and writes them to configuration.json. Use --test to run setup tests registered with ConfigurationForm.add_test().

Signature

fivetran configuration [OPTIONS]

Parameters

Example

fivetran configuration
fivetran configuration --test
fivetran configuration --disable-encryption
fivetran configuration --test --disable-encryption

Notes

• Requires a connector that defines a setup form using the configuration_form method. If the connector does not define one, this command exits without generating configuration.json.

• fivetran configuration writes configuration.json to the project directory (current directory by default). If configuration.json already exists there, it overwrites the file only after confirmation.

• fivetran configuration --test reads configuration.json and runs the tests registered with add_test().

• The configuration.json file generated by the fivetran configuration command stores password field values in encrypted form. Fivetran decrypts these values automatically when it reads the configuration.

• Editing an encrypted password value directly in configuration.json causes decryption errors. Password values added manually to configuration.json are not encrypted, and Fivetran treats them as plaintext.

• Fivetran adds the fivetran_encrypted: prefix to encrypted password values and uses this prefix to identify which values to decrypt when reading the configuration. fivetran configuration stores encrypted password values in the following format:

    {
      "password_key": "fivetran_encrypted:<encrypted_value>"
    }
  

  Avoid using the fivetran_encrypted: prefix in plaintext values. Fivetran attempts to decrypt any value with this prefix, which fails if the value was not encrypted through fivetran configuration.

• Use --disable-encryption to generate configuration.json with unencrypted password values. When encryption is disabled, sensitive field values will be stored as plain text in configuration.json. This is not recommended when working with AI or in shared environments.

• --test always attempts to decrypt encrypted values in configuration.json. The --disable-encryption flag only affects configuration generation; it does not prevent decryption during testing. However, if --test finds unencrypted password values in the configuration, it displays a warning because storing passwords without encryption poses a security risk in production environments.

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.