> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings

#### Learn how to configure the settings required to connect an integration

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:

```python theme={null}
# 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:

```python theme={null}
# 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:

```python theme={null}
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.