From 3be35d769cf749fec7d15c677887bd79d7e0b8d2 Mon Sep 17 00:00:00 2001 From: Waldek Mastykarz Date: Fri, 5 Jul 2024 08:51:28 +0200 Subject: [PATCH] chore: Adds CodeTour to the RAG JS and TS templates (#11953) * Adds CodeTour to the RAG JS template * Adds CodeTour for the TS sample Updates readme with a link to the Graph connector sample * Adds CodeTour as a recommended extension --- .../load-data-from-graph-connector.tour | 82 +++++++++++++++++++ .../.vscode/extensions.json | 3 +- .../README.md.tpl | 3 + .../load-data-from-graph-connector.tour | 82 +++++++++++++++++++ .../.vscode/extensions.json | 3 +- .../README.md.tpl | 3 + 6 files changed, 174 insertions(+), 2 deletions(-) create mode 100644 templates/js/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour create mode 100644 templates/ts/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour diff --git a/templates/js/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour b/templates/js/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour new file mode 100644 index 0000000000..e15ad74dbd --- /dev/null +++ b/templates/js/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour @@ -0,0 +1,82 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Load data from Graph connector", + "steps": [ + { + "file": "aad.manifest.json", + "description": "### Update Entra app manifest\n\nChange the permission to be able to read external items. This is necessary to grant your app access to external items imported to Microsoft 365 by the Microsoft Graph connector. Change the permission to:\n\n```text\nExternalItem.Read.All\n```", + "line": 24, + "selection": { + "start": { + "line": 24, + "character": 28 + }, + "end": { + "line": 24, + "character": 42 + } + }, + "title": "Update Entra app manifest" + }, + { + "file": "src/app/app.js", + "description": "### Update default scopes\n\nUpdate the scopes that the Microsoft Graph client should request when connecting to Microsoft Graph. This is necessary for your app to be able to read external items imported by the Graph connector. Change the permission to:\n\n```text\nExternalItem.Read.All\n```", + "line": 41, + "selection": { + "start": { + "line": 41, + "character": 19 + }, + "end": { + "line": 41, + "character": 33 + } + }, + "title": "Update Entra app permissions" + }, + { + "file": "src/app/graphDataSource.js", + "description": "### Update entity type\n\nUpdate entity type to search for external items. This instructs Microsoft Search to only search for items of type `externalItem` which represents external items ingested by Graph connectors. Change the code to:\n\n```text\nexternalItem\n```", + "line": 42, + "selection": { + "start": { + "line": 42, + "character": 32 + }, + "end": { + "line": 42, + "character": 41 + } + }, + "title": "Update entity type" + }, + { + "file": "src/app/graphDataSource.js", + "description": "### Define content source\n\nDefine the name of your external connection. This scopes the search result to only include results from the specified external connection. Add the snippet and replace `myconnection` with your connection name:\n\n```json\n contentSources: [\n '/external/connections/myconnection'\n ],\n\n```", + "line": 43, + "title": "Define content source" + }, + { + "file": "src/app/graphDataSource.js", + "description": "### Update download code\n\nUpdate the code to download external item's contents:\n\n```javascript\n const rawContent = await this\n .downloadExternalContent(result.resource.properties.substrateContentDomainId);\n```\n", + "line": 70, + "selection": { + "start": { + "line": 68, + "character": 1 + }, + "end": { + "line": 70, + "character": 15 + } + }, + "title": "Update code to download external item's contents" + }, + { + "file": "src/app/graphDataSource.js", + "description": "### Define download content method\n\nDefine new method to retrieve external item's contents. Update `myconnection` with your connection's name:\n\n```javascript\n\n async downloadExternalContent(externalItemFullId) {\n const externalItemId = externalItemFullId.split(',')[1];\n const externalItem = await this.graphClient\n .api(`/external/connections/myconnection/items/${externalItemId}`)\n .get();\n return externalItem.content.value;\n }\n\n```\n", + "line": 93, + "title": "Define method to download external item's contents" + } + ] +} \ No newline at end of file diff --git a/templates/js/custom-copilot-rag-microsoft365/.vscode/extensions.json b/templates/js/custom-copilot-rag-microsoft365/.vscode/extensions.json index 1b70a39308..086855dc92 100644 --- a/templates/js/custom-copilot-rag-microsoft365/.vscode/extensions.json +++ b/templates/js/custom-copilot-rag-microsoft365/.vscode/extensions.json @@ -1,5 +1,6 @@ { "recommendations": [ - "TeamsDevApp.ms-teams-vscode-extension" + "TeamsDevApp.ms-teams-vscode-extension", + "vsls-contrib.codetour" ] } \ No newline at end of file diff --git a/templates/js/custom-copilot-rag-microsoft365/README.md.tpl b/templates/js/custom-copilot-rag-microsoft365/README.md.tpl index f50bb8c3fe..88b511a5cc 100644 --- a/templates/js/custom-copilot-rag-microsoft365/README.md.tpl +++ b/templates/js/custom-copilot-rag-microsoft365/README.md.tpl @@ -22,6 +22,9 @@ This app template also demonstrates usage of techniques like: > - Prepare your own [Azure OpenAI](https://aka.ms/oai/access) resource. {{/useAzureOpenAI}} +> [!TIP] +> You can adjust this template to use data from a Microsoft Graph connector. Follow the steps in the [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) included in the project to apply the necessary changes. To use data from a Microsoft Graph connector, you need a Graph connector deployed to your tenant. For testing, we recommend using the [Ingest custom API data using TypeScript, Node.js and Teams Toolkit for Visual Studio Code](https://adoption.microsoft.com/sample-solution-gallery/sample/pnp-graph-connector-nodejs-typescript-food-catalog) sample. + > For local debugging using Teams Toolkit CLI, you need to do some extra steps described in [Set up your Teams Toolkit CLI for local debugging](https://aka.ms/teamsfx-cli-debugging). 1. First, select the Teams Toolkit icon on the left in the VS Code toolbar. diff --git a/templates/ts/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour b/templates/ts/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour new file mode 100644 index 0000000000..6a9333c04e --- /dev/null +++ b/templates/ts/custom-copilot-rag-microsoft365/.tours/load-data-from-graph-connector.tour @@ -0,0 +1,82 @@ +{ + "$schema": "https://aka.ms/codetour-schema", + "title": "Load data from Graph connector", + "steps": [ + { + "file": "aad.manifest.json", + "description": "### Update Entra app manifest\n\nChange the permission to be able to read external items. This is necessary to grant your app access to external items imported to Microsoft 365 by the Microsoft Graph connector. Change the permission to:\n\n```text\nExternalItem.Read.All\n```", + "line": 24, + "selection": { + "start": { + "line": 24, + "character": 28 + }, + "end": { + "line": 24, + "character": 42 + } + }, + "title": "Update Entra app manifest" + }, + { + "file": "src/app/app.ts", + "description": "### Update default scopes\n\nUpdate the scopes that the Microsoft Graph client should request when connecting to Microsoft Graph. This is necessary for your app to be able to read external items imported by the Graph connector. Change the permission to:\n\n```text\nExternalItem.Read.All\n```", + "line": 41, + "selection": { + "start": { + "line": 41, + "character": 19 + }, + "end": { + "line": 41, + "character": 33 + } + }, + "title": "Update Entra app permissions" + }, + { + "file": "src/app/graphDataSource.ts", + "description": "### Update entity type\n\nUpdate entity type to search for external items. This instructs Microsoft Search to only search for items of type `externalItem` which represents external items ingested by Graph connectors. Change the code to:\n\n```text\nexternalItem\n```", + "line": 61, + "selection": { + "start": { + "line": 61, + "character": 32 + }, + "end": { + "line": 61, + "character": 41 + } + }, + "title": "Update entity type" + }, + { + "file": "src/app/graphDataSource.ts", + "description": "### Define content source\n\nDefine the name of your external connection. This scopes the search result to only include results from the specified external connection. Add the snippet and replace `myconnection` with your connection name:\n\n```json\n contentSources: [\n '/external/connections/myconnection'\n ],\n\n```", + "line": 62, + "title": "Define content source" + }, + { + "file": "src/app/graphDataSource.ts", + "description": "### Update download code\n\nUpdate the code to download external item's contents:\n\n```javascript\n const rawContent = await this\n .downloadExternalContent(result.resource.properties.substrateContentDomainId);\n```\n", + "line": 89, + "selection": { + "start": { + "line": 87, + "character": 1 + }, + "end": { + "line": 89, + "character": 15 + } + }, + "title": "Update code to download external item's contents" + }, + { + "file": "src/app/graphDataSource.ts", + "description": "### Define download content method\n\nDefine new method to retrieve external item's contents. Update `myconnection` with your connection's name:\n\n```javascript\n\n private async downloadExternalContent(externalItemFullId: string) {\n const externalItemId = externalItemFullId.split(',')[1];\n const externalItem = await this.graphClient\n .api(`/external/connections/myconnection/items/${externalItemId}`)\n .get();\n return externalItem.content.value;\n }\n\n```\n", + "line": 105, + "title": "Define method to download external item's contents" + } + ] +} \ No newline at end of file diff --git a/templates/ts/custom-copilot-rag-microsoft365/.vscode/extensions.json b/templates/ts/custom-copilot-rag-microsoft365/.vscode/extensions.json index 1b70a39308..086855dc92 100644 --- a/templates/ts/custom-copilot-rag-microsoft365/.vscode/extensions.json +++ b/templates/ts/custom-copilot-rag-microsoft365/.vscode/extensions.json @@ -1,5 +1,6 @@ { "recommendations": [ - "TeamsDevApp.ms-teams-vscode-extension" + "TeamsDevApp.ms-teams-vscode-extension", + "vsls-contrib.codetour" ] } \ No newline at end of file diff --git a/templates/ts/custom-copilot-rag-microsoft365/README.md.tpl b/templates/ts/custom-copilot-rag-microsoft365/README.md.tpl index 98b7f95f08..67b98630db 100644 --- a/templates/ts/custom-copilot-rag-microsoft365/README.md.tpl +++ b/templates/ts/custom-copilot-rag-microsoft365/README.md.tpl @@ -22,6 +22,9 @@ This app template also demonstrates usage of techniques like: > - Prepare your own [Azure OpenAI](https://aka.ms/oai/access) resource. {{/useAzureOpenAI}} +> [!TIP] +> You can adjust this template to use data from a Microsoft Graph connector. Follow the steps in the [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) included in the project to apply the necessary changes. To use data from a Microsoft Graph connector, you need a Graph connector deployed to your tenant. For testing, we recommend using the [Ingest custom API data using TypeScript, Node.js and Teams Toolkit for Visual Studio Code](https://adoption.microsoft.com/sample-solution-gallery/sample/pnp-graph-connector-nodejs-typescript-food-catalog) sample. + > For local debugging using Teams Toolkit CLI, you need to do some extra steps described in [Set up your Teams Toolkit CLI for local debugging](https://aka.ms/teamsfx-cli-debugging). 1. First, select the Teams Toolkit icon on the left in the VS Code toolbar.