Added Teams guide to documentation

docs/GUIDE.md

@@ -35,6 +35,7 @@
    - [4.12 Search Trimming](#search-trimming)
    - [4.13 Bringing Your Own Resources](#bring-your-own-resources)   
    - [4.14 Setting Up Git Repos](#setting-up-git-repos)
+   - [4.15 Creating a Teams App Interface](#creating-a-teams-app-interface)
 5. [**Reference**](#reference)
    - [5.1 Azure Resources](#azure-resources)
    - [5.2 Permissions](#permissions)    
@@ -1160,6 +1161,10 @@ For detailed instructions and advanced import scenarios, refer to the [Importing
 
 If you intend to contribute to the ongoing development of the Solution Accelerator by submitting pull requests, please refer to our [Contribution Guidelines](https://github.com/Azure/GPT-RAG/blob/main/CONTRIBUTING.md#contribution-guidelines) for detailed instructions on how to fork repositories and create pull requests.
 
+## Creating a Teams App Interface
+
+[This step-by-step guide](TEAMS_INTEGRATION_MAIN.md) provides instructions for creating a Teams App Interface for the Enterprise GPT-RAG Solution Accelerator using the Teams toolkit. It covers the prerequisites and high-level steps required to build, test, deploy, and publish the Teams App. The guide includes creating a new Teams App, connecting it to the GPT-RAG Orchestrator, provisioning and deploying Azure resources, building the app, and finally publishing it.
+
 ## Reference
 
 ### Azure Resources

docs/TEAMS_INTEGRATION_MAIN.md

@@ -0,0 +1,40 @@
+# Guide for Building a Teams App Interface for the Enterprise GPT-RAG Solution Accelerator
+
+## Introduction
+This is a guide for building a Teams App Interface for the Enterprise GPT-RAG Solution Accelerator using Teams toolkit.
+
+## Key Solution Components
+The following Azure resources will be deployed in addition to those already deployed in the Enterprise RAG Solution Accelerator.
+- Azure Bot Framework service
+- Azure App Service Plan & Azure App Service
+- Managed Identity
+
+## Prerequisites
+Before proceeding with the steps in the subsequent sections, ensure you have completed the following:
+- An Azure subscription to deploy the required resources.
+- A Microsoft 365 account. Read more on developer program that can be used for testing purposes. [here](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/tools-prerequisites#microsoft-365-developer-program).
+- The Enterprise GPT-RAG Solution Accelerator deployed in your Azure subscription.
+- For publishing, access to a Teams admin who can approve the app deployment within your organization. Alternatively, you can test locally on your development machine and/or use [custom upload](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/deploy-and-publish/apps-upload) option if enabled for your organization.
+- Note: When deploying Azure resources for the Teams app, such as the App Service Plan and App Service, you can utilize the resources already provisioned in the GPT-RAG Solution Accelerator.
+- Note: The App Service uses a public endpoint for the Teams App to connect to the service.
+
+Set up the following prerequisites on the machine to be used for development:
+- Download and install [Visual Studio Code](https://code.visualstudio.com/Download).
+- Install [NodeJS](https://nodejs.org/) version 16 or later.
+
+## Step 1: [Create a new Teams App](TEAMS_INTEGRATION_STEP1.md).
+
+## Step 2: [Connect to GPT-RAG Orchestrator and test locally](TEAMS_INTEGRATION_STEP2.md).
+
+## Step 3: [Provision and Deploy the Azure resources for the Teams App](TEAMS_INTEGRATION_STEP3.md).
+
+## Step 4: [Build the Teams App](TEAMS_INTEGRATION_STEP4.md).
+
+## Step 5: [Publish the Teams App](TEAMS_INTEGRATION_STEP5.md).
+
+## External Resources
+- [Microsoft Teams Toolkit Overview](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teams-toolkit-fundamentals).
+- [Visual Studio Code](https://code.visualstudio.com/Download).
+- [Install Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode).
+- [Microsoft 365 developer program](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/tools-prerequisites#microsoft-365-developer-program).
+

docs/TEAMS_INTEGRATION_STEP1.md

@@ -0,0 +1,41 @@
+# Guide for Building a Teams App Interface for Enterprise GPT-RAG Solution Accelerator
+
+*Ensure all prerequisites mentioned [here](TEAMS_INTEGRATION_MAIN.md) are completed before proceeding with the steps below.*
+
+## Step 1: Create a new Teams App.
+
+1. Open **Visual Studio Code**. 
+
+2. Select the **Teams Toolkit** > **Create a New App**.
+
+![Teams Toolkit, Create New App](../media/teams-guide-Step1a.png)
+
+2. Select **Bot** as app capability.
+
+![Bot](../media/teams-guide-Step1b.png)
+
+3. Select **Basic Bot** as app capability.
+
+![Basic Bot](../media/teams-guide-Step1c.png)
+
+4. Choose a programming language. For this guide, we will use **TypeScript**.
+
+![Typescript](../media/teams-guide-Step1d.png)
+
+5. Select **Browse** and select the location for project workspace.
+
+6. Enter a suitable name for your app, such as *GPTRAGTeams*, as the application name. Ensure that you use only alphanumeric characters. Press **Enter**.
+
+![Application Name](../media/teams-guide-Step1e.png)
+
+Proceed to Step 2: [Connect to GPT-RAG Orchestrator and test locally](TEAMS_INTEGRATION_STEP2.md).
+
+## Additional Resources
+- [Prerequisites - Guide for Building a Teams App Interface for the Enterprise GPT-RAG Solution Accelerator](TEAMS_INTEGRATION_MAIN.md#prerequisites).
+- [Step 2: Connect to GPT-RAG Orchestrator and test locally](TEAMS_INTEGRATION_STEP2.md).
+
+## External Resources
+- [Install Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode).
+- [Prepare to build apps using Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/build-environments).
+- [Prerequisites for creating your Teams app](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/tools-prerequisites).
+- [Directory structure for different app types](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/create-new-project#directory-structure-for-different-app-types).

docs/TEAMS_INTEGRATION_STEP2.md

@@ -0,0 +1,59 @@
+# Guide for Building a Teams App Interface for Enterprise GPT-RAG Solution Accelerator
+
+*Ensure all steps mentioned in [Step 1](TEAMS_INTEGRATION_STEP1.md) are completed before proceeding with the steps below.*
+
+## Step 2: Connect to GPT-RAG Orchestrator and test locally
+
+1. Navigate to the `teamsBot.ts` file. Modify the code to pass the message to the Orchestrator and obtain a response. Below is a sample code snippet to guide you:
+
+```typescript
+        //await context.sendActivity(`Echo: ${txt}`);
+
+        // Obtain the orchestrator endpoint securely from Azure KeyVault
+        const orchestratorEndpoint = //Obtained from Azure KeyVault;
+
+        // Retrieve the unique conversation ID from the activity context
+        const conversation_id = context.activity.conversation.id;
+
+        // Construct the request body to send to the orchestrator
+        const requestBody = {
+            "question": txt, // The user's input text, which will be sent as the 'question'
+            "conversation_id": conversation_id 
+        };
+
+        try {
+            // Make a POST request to the orchestrator endpoint
+            const response = await fetch(orchestratorEndpoint, {
+                method: 'POST', // HTTP method to send the request
+                headers: {
+                    'Content-Type': 'application/json' // Specifies that the body of the request is in JSON format
+                },
+                body: JSON.stringify(requestBody) // Convert the request body into a JSON string
+            });
+
+            // Check if the response was successful 
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+
+            // Parse the JSON response from the orchestrator
+            const data = await response.json();
+            // Send the answer from the orchestrator back to the user
+            await context.sendActivity(`${data.answer}`);
+
+        } catch (error) {
+            //Error posting question to Azure Function, handle gracefully.
+        } 
+```
+2. Select **Run** and then **Start Debugging**. Test the bot by asking questions relevant to the files uploaded to the GPT-RAG Solution Accelerator.
+
+![Debug Teams Chat Locally](../media/teams-guide-Step2b.png)
+
+Proceed to Step 3: [Provision and Deploy the Azure resources for the Teams App](TEAMS_INTEGRATION_STEP3.md).
+
+## Additional Resources
+- [Step 1: Create a new Teams App](TEAMS_INTEGRATION_STEP1.md).
+- [Step 3: Provision and Deploy the Azure resources for the Teams App](TEAMS_INTEGRATION_STEP3.md).
+
+## External Resources
+- [Teams App Test Tool](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/debug-your-teams-app-test-tool?tabs=vscode%2Cclijs).

docs/TEAMS_INTEGRATION_STEP3.md

@@ -0,0 +1,73 @@
+# Guide for Building a Teams App Interface for Enterprise GPT-RAG Solution Accelerator
+
+*Ensure all steps mentioned in [Step 2](TEAMS_INTEGRATION_STEP2.md) are completed before proceeding with the steps below.*
+
+- Note: When deploying Azure resources for the Teams app, such as the App Service Plan and App Service, you can utilize the resources already provisioned in the GPT-RAG Solution Accelerator.
+
+## Step 3: Provision and Deploy the Azure resources for the Teams App
+1. Select the **Teams Toolkit** icon in the sidebar. Select **Sign in to Microsoft 365**. 
+
+![Microsoft 365 Signin](../media/teams-guide-Step3a.png)
+
+2. Your default web browser opens to let you sign in to the account. Sign in with Microsoft 365 account. Close the browser when prompted and return to Visual Studio Code.
+
+![VS Code Signin](../media/teams-guide-Step3b.png)
+
+3. Select the **Teams Toolkit** icon in the sidebar. Select **Sign in to Azure**. 
+
+![Azure Signin](../media/teams-guide-Step3c.png)
+
+4. Your default web browser opens to let you sign in to the account. Sign in to your Azure account. Close the browser when prompted and return to Visual Studio Code.
+
+5. Select Provision from the LIFECYCLE section in the left pane.
+
+![Lifecycle Provision](../media/teams-guide-Step3d.png)
+
+6. Select the Azure subscription. 
+
+![Azure Subscription Selection](../media/teams-guide-Step3e.png)
+
+7. Select an existing resource group or create a new resource group. Press **Enter**.
+
+![Resource group selection](../media/teams-guide-Step3f.png)
+
+![Resource group creation](../media/teams-guide-Step3g.png)
+
+8. Select the Azure location.
+
+9. Review the message and select **Provision**.
+
+![Provision button](../media/teams-guide-Step3h.png)
+
+10. Wait for the provisioning process to complete. 
+
+![Provisioning status](../media/teams-guide-Step3i.png)
+
+![Provision complete](../media/teams-guide-Step3j.png)
+
+11. You can review the deployed Azure resources on the Azure portal.
+
+![Azure resources on portal](../media/teams-guide-Step3k.png)
+
+12. Select Deploy from the LIFECYCLE section in the left pane.
+
+![Teams Deploy](../media/teams-guide-Step3l.png)
+
+13. Select Deploy.
+
+![Deploy button](../media/teams-guide-Step3m.png)
+
+13. Wait for the deployment to complete.
+
+![Deployment status](../media/teams-guide-Step3n.png)
+
+Proceed to Step 4: [Build the Teams App](TEAMS_INTEGRATION_STEP4.md).
+
+
+## Additional Resources
+- [Step 2: Connect to GPT-RAG Orchestrator and test locally](TEAMS_INTEGRATION_STEP2.md).
+- [Step 4: Build the Teams App](TEAMS_INTEGRATION_STEP4.md).
+
+## External Resources
+- [Provision cloud resources](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/provision).
+- [Deploy Microsoft Teams app to the cloud](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/deploy).

docs/TEAMS_INTEGRATION_STEP4.md

@@ -0,0 +1,35 @@
+# Guide for Building a Teams App Interface for Enterprise GPT-RAG Solution Accelerator
+
+*Ensure all steps mentioned in [Step 3](TEAMS_INTEGRATION_STEP3.md) are completed before proceeding with the steps below.*
+
+## Step 4: Build the Teams App
+
+1. Select the **Teams Toolkit** icon in the sidebar. Select **Utility** and then, **Zip Teams App Package**.
+
+![Zip Teams App Package](../media/teams-guide-Step4a.png)
+
+2. Select the Teams Manifest JSON file.
+
+![Manifest file selection](../media/teams-guide-Step4b.png)
+
+3. Choose the environment. The Teams Toolkit supports running and testing your app in different deployment targets such as development, staging, production, or locally. It utilizes environment files to handle configurations and automate resource provisioning for various environments. Learn more about environments [here](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-multi-env).
+
+![Teams Toolkit environment selection](../media/teams-guide-Step4c.png)
+
+4. Wait for the build to complete. Once finished, navigate to the folder. You can click on the **local address** link to go directly to the folder.
+
+![Local Address link](../media/teams-guide-Step4d.png)
+
+5. Review the files generated in the folder. These files will be used for deployment in the subsequent section.
+
+![Teams App Files](../media/teams-guide-Step4e.png)
+
+Proceed to Step 5: [Publish the Teams App](TEAMS_INTEGRATION_STEP5.md).
+
+## Additional Resources
+- [Step 3: Provision and Deploy the Azure resources for the Teams App](TEAMS_INTEGRATION_STEP3.md).
+- [Step 5: Publish the Teams App](TEAMS_INTEGRATION_STEP5.md).
+
+## External Resources
+- [Teams app package](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/apps-package).
+- [Environments in Microsoft Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teamsfx-multi-env).

docs/TEAMS_INTEGRATION_STEP5.md

@@ -0,0 +1,43 @@
+# Guide for Building a Teams App Interface for Enterprise GPT-RAG Solution Accelerator
+
+*Ensure all steps mentioned in Step 4: [Build the Teams App](TEAMS_INTEGRATION_STEP4.md) are completed before proceeding with the steps below.*
+
+## Step 5: Publish the Teams App
+
+You can follow the below steps to publish the Teams app at an individual level for testing purposes using the custom upload option:
+
+1. In the Teams client or Teams web version, select **Apps** > **Manage your apps** > **Upload an app**. 
+
+![Upload Teams App](../media/teams-guide-Step5a.png)
+
+2. The Upload an app window appears. Select Upload a custom app.
+
+![Upload a custom app](../media/teams-guide-Step5b.png)
+
+3. Select the zip file generated in the previous section.
+
+![Select Zip File](../media/teams-guide-Step5c.png)
+
+4. Select the **Add** button.
+
+![Add button](../media/teams-guide-Step5d.png)
+
+5. Wait for the app to be added successfully. 
+
+![App Added Success](../media/teams-guide-Step5f.png)
+
+6. Test the app by asking a question. 
+
+![Test prompt](../media/teams-guide-Step5g.png)
+
+![Chat Response](../media/teams-guide-Step5h.png)
+
+To publish the Teams App to the developer portal, follow the steps outlined [here](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/publish-your-teams-apps-using-developer-portal).
+
+
+## Additional Resources
+- [Step 4: Build the Teams App](TEAMS_INTEGRATION_STEP4.md).
+
+## External Resources
+- [Publish Teams apps using Teams Toolkit](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/publish#upload-app-package).
+- [Integrate with Developer Portal](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/publish-your-teams-apps-using-developer-portal).