Settings

Connector-wide settings are required for configuring the behaviour of a connector across all its capabilities. These settings often include unique identifiers for tenants, server configurations, or other API-specific parameters required for the connector to function correctly.

Purpose of Connector-Wide Settings

1. Tenant Identification: Many APIs require a unique identifier for the customer's account or organization (e.g., site_id, customer_code). Sometimes this value is returned within validate_credentials, in cases when the API does not return a valid identificator.
2. Server Configuration: For APIs that can be hosted on-premises or in different environments, server details may be required (e.g., server_name, instance_url).
3. API-Specific Parameters: Some APIs may require additional configuration parameters for authentication or functionality.

Implementing Connector-Wide Settings

Connector-wide settings are typically implemented using a Pydantic model in the settings.py file of each connector. Here's an example from the abc connector:

# file at abc/settings.py
from pydantic import BaseModel

class abcSettings(BaseModel):
    site_id: str = Field(
        title="abc Site ID",
        description=(
            "You should be able to see the Site ID on the Settings page -> Name -> Site ID. "
            "Or in the URL at 'site/siteID/' following the number sign ( # )."
        ),
    )
    server_name: str | None = Field(
        title="abc Server Name",
        default="10ax.online.abc.com",
        description=(
            "abc server name. Defaults to abc server. "
            "This represents the instance URL of the abc server. "
            "Or by default it is set to abc server base URL."
        ),
    )
    auth_setting: abcAuthSetting | None = Field(
        title="abc Authentication Setting",
        default=abcAuthSetting.SERVER_DEFAULT,
        description=(
            "abc authentication settings. Defaults to Server Default. "
            "This setting is used for creating accounts under specific site. "
            "You can find more information [here](https://help.abc.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#add_user_to_site)"
        ),
    )

Key Components of Connector-Wide Settings

1. Pydantic BaseModel: Use Pydantic's BaseModel as the base class, to ensure proper type checking and validation.
2. Required Fields: Define fields that are always required for the connector to function (e.g., site_id).
3. Optional Fields: Include fields that have default values or are not always required (e.g., server_name, auth_setting).
4. Field Metadata: Use pydantic.Field to provide additional information:
   • title: A user-friendly name for the field.
   • description: Detailed explanation of the field's purpose and how to obtain its value.
   • default: Default value for optional fields.

Integrating Settings with the Connector

To use these settings across all capabilities, include them in the Integration configuration:

# file at abc/integration.py
from connector.generated import OAuthCredential
from connector.oai.integration import Integration
from abc.settings import abcSettings

integration = Integration(
    app_id="abc",
    settings_model=abcSettings,
    auth=OAuthCredential,
    # ... other configuration ...
)

Best Practices for Connector-Wide Settings

1. Sensible Defaults: Where possible, provide default values that work for most common scenarios.
2. Validation: Use Pydantic validation features to ensure that provided settings meet the required format and constraints.
3. Flexibility: Design settings to accommodate different deployment scenarios (e.g., cloud vs. on-premises).
4. Security: Be cautious about default values for sensitive information. Use AnnotatedField where applicable.

Accessing Settings in Capabilities

To use these settings within capability functions, you can access them using the get_settings helper:

from connector.oai.capability import get_settings

async def some_capability(args: SomeCapabilityRequest) -> SomeCapabilityResponse:
    settings = get_settings(args, abcSettings)
    # Now you can use settings.site_id, settings.server_name, etc.

By implementing comprehensive connector-wide settings, you ensure that your Lumos Integration connector is flexible, well-documented, and easy to configure for different environments and use cases.