# AI Chatbot The AI Chatbot provides a conversational assistant embedded in the OtisEd.Nimble portal. Users can ask questions about reports, glossary terms, and reference items in natural language and receive AI-generated responses that link directly to relevant portal content. ## Contents * [Overview](#overview) * [Using the Chat Widget](#using-the-chat-widget) * [What the Chatbot Knows](#what-the-chatbot-knows) * [Access and Visibility](#access-and-visibility) * [Conversation Behavior](#conversation-behavior) * [Admin: Chatbot Settings](#admin-chatbot-settings) * [General Settings](#general-settings) * [AI Storage](#ai-storage) * [AI Search](#ai-search) * [Result Limit](#result-limit) * [Open AI](#open-ai) * [Schedule](#schedule) * [Admin: Testing Connections](#admin-testing-connections) * [Admin: Running the Data Sync Job](#admin-running-the-data-sync-job) * [Troubleshooting](#troubleshooting) *** ## Overview The AI Chatbot surfaces as a floating button in the portal. When opened, it presents a chat panel where users type questions and receive answers that are grounded in the portal's own data — reports, glossary definitions, and reference items. Under the hood, the chatbot uses two Azure services: Azure AI Search to find relevant records, and Azure OpenAI to compose a plain-language answer from those results. Administrators control both the chatbot's identity and its connection to those services through the settings page. *** ## Using the Chat Widget The chatbot appears as a clickable avatar button (the "Ask Otis" image) fixed to the page. To start a conversation: 1. Click the avatar button to open the chat panel. 2. A welcome message from the chatbot greets you. The message text and the chatbot's name are configured by your administrator. 3. Type a question in the input box at the bottom of the panel. The chatbot is designed to answer questions about reports, glossary terms, and reference items available in the portal. 4. Press **Enter** or click **Send** to submit your message. The chatbot displays a "thinking..." indicator while it processes your request. 5. The chatbot replies with an answer. When a relevant report is found, the answer includes a clickable link that takes you directly to that report. 6. Continue the conversation by typing follow-up questions. The chatbot retains the context of your current session. 7. Click the close button (X) in the panel header to collapse the chat. Your conversation is remembered for the duration of your browser session, using a conversation ID stored in your browser's local storage. *** ## What the Chatbot Knows The chatbot can answer questions about three types of content that are indexed from the portal: * **Reports** — Titles, descriptions, navigation paths, and direct links to portal reports. * **Glossary terms** — Term names, definitions, and groupings. * **Reference items** — Titles, definitions, and associated URLs. When you ask a question, the chatbot determines which content type(s) are relevant, searches the Azure AI Search index for matching records, and then uses Azure OpenAI to compose a response. If the search returns no matching records, the chatbot responds with a configurable "no data" message rather than speculating. *** ## Access and Visibility The chatbot is only visible when an administrator has enabled it. Depending on how it is configured, the chatbot may be: * **Open to everyone** — Available to all visitors including unauthenticated users. * **Requires login** — Only signed-in users can interact with the chatbot. * **Restricted by role** — Only users who hold one or more of the configured roles can use the chatbot. Users who do not meet the role requirement will receive an authorization error if they attempt to send a message. If you believe you should have access to the chatbot but it is not appearing, contact your administrator to confirm your account has the appropriate roles assigned. *** ## Conversation Behavior Each chat session maintains its own conversation history while the server is running. The chatbot uses up to the last 8 messages in the conversation as context when formulating a response, so follow-up questions work without re-explaining your subject. Conversation history is stored in server memory and is not persisted to a database. History does not survive application restarts. Each conversation is capped at 100 messages; the oldest messages are dropped when that limit is reached. *** ## Admin: Chatbot Settings Navigate to **Site Administration** and select the **AI Chatbot** tab to configure all chatbot options. Settings are organized into tabs. After making changes, click **Save Settings** at the bottom of the page. ### General Settings | Field | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | The internal name of the chatbot. Used in the welcome message when you include `{name}` as a placeholder. | | Title | The heading shown at the top of the chat panel. | | Welcome Message | The first message users see when they open the chat. Use `{name}` anywhere in the text to insert the chatbot's Name automatically. | | Enabled | Controls whether the chatbot button appears in the portal at all. Uncheck to hide the chatbot from all users. | | Requires Authentication | When checked, only signed-in users can send messages. | | Required Roles | Optional. Select one or more portal roles. If any roles are selected, only users who hold at least one of those roles can use the chatbot. Leave empty to allow all authenticated users. | | No Data Message | The message the chatbot returns when a search finds no relevant records. If left blank, a generic default message is used. | | Prompt | The system prompt sent to Azure OpenAI with every request. This instructs the AI on tone, format, and behavior. If left blank, a default prompt is used. | ### AI Storage The AI Storage tab connects the chatbot to an Azure Blob Storage container. This container holds the exported JSON files that Azure AI Search indexes. | Field | Description | | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | SAS URL | The Shared Access Signature URL for the Azure Blob Storage container. This URL must point to a container and include write permissions. | Click **Test Container Connection** to verify that the SAS URL is valid and reachable before saving. ### AI Search The AI Search tab configures the Azure AI Search service that the chatbot queries. | Field | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint | The URL of your Azure AI Search service (for example, `https://your-search.search.windows.net`). | | Index Name | The name of the search index within that service that holds the chatbot's data. | | Api Key | The admin API key for the search service, used for writing and managing the index. When a key is already saved, the field shows masked characters. Leave unchanged to keep the existing key. | | Query Key | The read-only query key used by the chatbot when searching. When a key is already saved, the field shows masked characters. Leave unchanged to keep the existing key. | If you remove the endpoint or index name from these fields and save, the values fall back to defaults configured in the application's server configuration file. Click **Test Azure Search Index Connection** to verify that the endpoint, index name, and API key are valid before saving. ### Result Limit Controls how many search results are passed to Azure OpenAI when building a response. | Field | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------- | | Upper Limit | The maximum allowed value for the search limit. This is set in server configuration and is read-only. | | Lower Limit | The minimum allowed value. Read-only. | | AI Search Limit | The number of matching records to retrieve per search. The default is 20. Must be between the Lower Limit and Upper Limit. | A higher limit gives the AI more information to work with but increases response time and token usage. ### Open AI Configures the Azure OpenAI service that generates chat responses. | Field | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint | The URL of your Azure OpenAI resource (must be an `openai.azure.com` domain). | | Deployment Model | The name of the model deployment within your Azure OpenAI resource. | | Api Key | The API key for the Azure OpenAI resource. When a key is already saved, the field shows masked characters. Leave unchanged to keep the existing key. | Click **Test Azure OpenAI Connection** to send a test message to the configured deployment and confirm connectivity before saving. ### Schedule The Schedule tab controls a recurring background job that exports portal data to blob storage so Azure AI Search can index it. | Field | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable Job | When checked, the data sync job runs automatically on the configured schedule. | | Cron Expression | A standard cron expression defining when the job runs (for example, `0 0 * * *` for daily at midnight). If the field is left empty, any existing schedule is removed. | The schedule operates in the server's local time zone. *** ## Admin: Testing Connections Each integration service (Azure Storage, Azure AI Search, Azure OpenAI) has a **Test Connection** button on its respective settings tab. These buttons send a live request to the configured service and display a success or error message inline. Test connections are performed using whatever values are currently entered in the form, even before you click Save. If a key field shows masked characters and you have not changed it, the test uses the previously saved key. Common error conditions and their causes: | Error | Likely cause | | ---------------------------------------- | ------------------------------------------------------------------------------------------------ | | Authentication failed - invalid API key | The API key entered is incorrect. | | Deployment not found | The deployment model name does not match a deployment in your Azure OpenAI resource. | | Rate limit exceeded | Too many requests were sent to Azure OpenAI in a short period. Wait and retry. | | Invalid Azure OpenAI endpoint URL format | The endpoint field contains a non-URL value, or a URL that is not an `openai.azure.com` address. | | Index name is required | The AI Search index name field is empty. | | SasUrl setting is invalid | The SAS URL does not contain a container path segment. | *** ## Admin: Running the Data Sync Job The data sync job exports all current reports, glossary terms, and reference items from the portal database to blob storage as individual JSON files. Azure AI Search indexes these files to make them searchable by the chatbot. The job runs automatically if a schedule is configured and enabled. To run it immediately without waiting for the schedule: 1. Open the **Schedule** tab in AI Chatbot Settings. 2. Click **Execute Background Job**. 3. Confirm the prompt that appears. The job is queued and typically completes within five minutes. No notification is shown when it finishes, but the chatbot's search results will reflect any new or updated content after the job completes and the index refreshes. The job can be executed manually regardless of whether the Enable Job checkbox is checked. *** ## Troubleshooting **The chatbot button does not appear.** Confirm with your administrator that the chatbot has been enabled in the General settings tab. **The chatbot says it could not find relevant information.** The search index may not yet contain data, or no records match your query. Ask your administrator to run the data sync job and verify that the AI Search index is populated. **I receive "User is not authorized to access the AI Chatbot."** The chatbot is configured to require a specific role that your account does not have. Contact your administrator to review the Required Roles setting or adjust your account's role assignments. **Saving settings produces an error about AI Search Limit.** The value entered for AI Search Limit is outside the permitted range shown as Upper Limit and Lower Limit on the Result Limit tab. Adjust the value to fall within those bounds. **The Test Container Connection fails with an invalid SAS URL error.** Ensure the SAS URL includes a container name in the path (for example, `.../my-container?sv=...`). A URL pointing only to the storage account root is not sufficient. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://nimble.docs.otised.com/guides/ai-chatbot.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.