# How to Configure Instance Parameters?

Instance settings let you change global system parameters: add or update settings by key, choose an email provider, and control which platform features are available on this instance.

## When You'll Need This

- You need to change system parameters (e.g., timezone, project name, file limits).
- You need to enable or disable specific features in instance settings (AI assistant, Process Library, integrations).
- You need to configure an email provider (Mailgun, Gmail, Outlook).

## What's Important to Know

- **Instance** — a separate ConnectiveOne system instance for a specific client.
- **Instance settings** — key-value pairs that affect the entire system.
- **Access** — only root administrators can view and change instance settings.
- **Feature availability** — individual platform capabilities can be turned on or off; a root administrator sets this in instance settings.

## Before You Start

- [x] You are logged in as a root administrator.
- [x] You see the "Instance Settings" item in the Settings side menu.

## Step-by-Step Instructions

### 1. Open Instance Settings

1. Go to the **Settings** module via the menu or at `/settings-page`.
2. In the side menu, find **"Instance Settings"**.
3. Click it.

### 2. View Current Settings

1. The left side of the page shows a list of all settings (key and value).
2. Scroll the list to find the parameters you need.

**Common settings:**
- `instance_timezone` — timezone (e.g., `Europe/Kiev`, `America/New_York`)
- `clarity_enabled` — enable Microsoft Clarity (1/0)
- `lifecycle` — number of days before automatic file deletion in storage
- `client_portal_url` — base URL of the ConnectiveOne Client Portal (helpdesk web app); adds that origin to Engine CORS so the portal can call the instance API from another domain
- `portal_registration_enabled` — enable (`true`) or disable (`false`) Client Portal self-registration (`/register`)
- `portal_registration_role_id` — role id assigned to newly registered portal users; the role must have **Client Portal** permission enabled (see [Configure roles](/en/settings/how-to/configure-roles.md)). Usually the system `client_portal` role
- **Client Portal (staff)** — trusted URLs and context window for employees of your organization: `client_portal_staff_jira_url`, `client_portal_staff_operator_line_url`, `client_portal_staff_recent_ticket_days`, `client_portal_staff_highlighted_client_field_keys` (see [Configure staff access](/en/clientportal/how-to/configure-staff-access.md))
- Toggles for individual platform features (Process Library, Instance Agent, etc.) — managed in the instance settings block

Full description of all keys is in the technical documentation for developers.

To change values in the instance form in the UI:

1. Update the parameters you need:
   - **"Instance name"** — your ConnectiveOne instance name.
   - **"Domain"** — system domain (if available).
   - **"Contact information"** — email, phone, etc.
   - **"Timezone"** — timezone for the system.
   - **"Chatroom export to PDF"** — maximum wait time (in seconds) when generating PDF for dialogs. Used when operators export chat history to PDF.
   - **Feature toggles** — for new platform capabilities. For example, **"Operator Panel → Chatroom Export to PDF"** enabled so operators can export dialogs to PDF; if disabled, the menu item is hidden.
   - Other parameters (depending on implementation).
2. Verify the entered data.

### 3. Create or Update a Setting

1. On the right, find the **"Create/Update key"** card.
2. In the **"Key"** field, enter the parameter name (e.g., `project_name`, `instance_timezone`).
3. In the **"Value"** field, enter the desired value.
4. Optionally enable **"Exclude"** to hide the setting from non-root users.
5. Click **"Create/Update"**.

### 4. Delete a Setting

1. Find the **"Delete key"** card.
2. Enter the key of the setting to delete.
3. Click **"Delete"**.

### 5. Configure Email Provider

1. Scroll to the **"Email Provider"** section.
2. Select a provider: Not configured, Mailgun, Gmail, or Outlook.
3. Click **"Save"**.
4. If you select Mailgun, an extra section appears with API Key, Signing Key, Region, and Forwarding Domain. Fill them in and save.

### 6. Turn platform features on or off

1. Scroll to the block where you turn individual platform features on or off (categories depend on your configuration).
2. Expand the category you need (e.g., **Instance Agent**, **Process Library**, **Operator Panel**).
3. Toggle switches or select values for the features you want.
4. Changes are saved automatically when you toggle.

**Example — enabling the AI assistant:**
- Expand the **Instance Agent** category.
- Enable **Instance Agent Integration**.
- Optionally enable **Agent Debug Mode** to see the agent’s reasoning and tool calls in the chat.
- To block data changes through the assistant for all users, enable **Agent Read-Only Mode** (view and UI guidance only).

For role permissions, see [Configure AI Assistant access](/en/constructor/how-to/configure-ai-assistant-access.md).

**Example — Notification Center:** expand **Notifications**, turn on **Notification Center** — full step-by-step is in the [root how-to](/en/notifications/how-to/enable-notification-center.md).

**Example — instance knowledge base (Constructor):** expand **Instance Docs**, enable **Instance Docs** — how to work with documents: [Constructor how-to](/en/constructor/how-to/use-instance-knowledge-base.md).

**Example — native files in Facebook Messenger:** expand **Integrations**, enable **Facebook native file attachments** — PDFs and documents from Operator Line arrive as Messenger attachments (off by default). Step-by-step: [How to enable native files in Facebook Messenger](/en/operatorline/how-to/enable-facebook-native-file-attachments.md).

## What Happens Next

- Settings apply to the entire system.
- These settings affect which features appear in the menu and interface.
- Some changes may require a page reload.

## How to Verify Everything Worked

- Check that the new or updated setting appears in the list on the left.
- For feature toggles, verify that the corresponding capability appears or disappears in the interface.

## Related Materials

- [Configure roles](/en/settings/how-to/configure-roles.md)
- [How to enable the Notification Center on the instance (root)](/en/notifications/how-to/enable-notification-center.md)
- [How to enable native files in Facebook Messenger](/en/operatorline/how-to/enable-facebook-native-file-attachments.md)
- [Configure client fields](/en/settings/how-to/configure-client-fields.md) — Client Portal registration form fields

## Important Notes

- ⚠️ **Critical changes:** Some settings affect system access — use with care. Do not change `project_name` without consulting the technical team — it affects instance identity.
- 🔄 **Reload:** Some changes may require a page or system reload.
- 💡 **Exclude:** If Exclude is enabled, the setting is hidden from non-root users.