diff --git a/docs/libraries/web-sdk/guides/sharepoint.mdx b/docs/libraries/web-sdk/guides/sharepoint.mdx new file mode 100644 index 00000000..e4497e67 --- /dev/null +++ b/docs/libraries/web-sdk/guides/sharepoint.mdx @@ -0,0 +1,311 @@ +--- +title: 'SharePoint' +description: 'Guide for embedding Glean Search or Chat into SharePoint sites using SharePoint Framework (SPFx)' +icon: 'share-nodes' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Embedding Glean Search & Chat into SharePoint Sites + +## Overview + +This guide provides step-by-step instructions for integrating Glean Search and Chat functionality into SharePoint sites using the SharePoint Framework (SPFx). + + + + Embed Glean's search functionality directly into SharePoint pages + + + Add Glean's conversational AI interface to SharePoint sites + + + +## Prerequisites + +Before beginning the integration, ensure your SharePoint environment meets the following requirements: + +### SharePoint Version Compatibility + + + + +SPFx is fully supported in SharePoint Online (Microsoft 365). This is the recommended platform for Glean integration. + + + + +SPFx requires: +- **SharePoint Server 2016**: Feature Pack 2 or later +- **SharePoint Server 2019**: Fully supported +- **SharePoint Subscription Edition**: Fully supported + + + + +### Required Permissions + +You'll need the following permissions to deploy SPFx solutions: +- SharePoint Administrator role, or +- Site Collection Administrator rights for the target sites + +### App Catalog Verification + + + + Navigate to your App Catalog: `https://.sharepoint.com/sites/appcatalog/_layouts/15/tenantAppCatalog.aspx/manageApps` + + If you encounter a 404 error, the App Catalog needs to be created. + + + + 1. Go to **SharePoint Admin Center**: `https://admin.microsoft.com` + 2. Navigate to **More features** > **Apps** > **App Catalog** + 3. Follow the setup instructions to create a new App Catalog site + + + + Ensure your SharePoint sites use the modern experience. SPFx web parts are not compatible with classic SharePoint pages. + + + +## Development Environment Setup + + + + Install Node.js version 18.x (required for SPFx compatibility): + + ```bash + # Check current version + node -v + + # Install Node.js 18.x if needed + # Visit https://nodejs.org/en/download/package-manager for installation instructions + ``` + + + + Install the required global packages: + + ```bash + # Install Yeoman, SPFx Yeoman Generator, and Gulp CLI + npm install gulp-cli yo @microsoft/generator-sharepoint -g + ``` + + + + Install Visual Studio Code or your preferred code editor for SPFx development. + + + +## Creating the SPFx Web Part + +### Generate New SPFx Project + + + + ```bash + mkdir GleanSearchWebPart + cd GleanSearchWebPart + ``` + + + + Run the Yeoman generator: + + ```bash + yo @microsoft/sharepoint + ``` + + Configure the project with these settings: + - **Solution Name**: `GleanSearchWebPart` + - **Target for deployment**: SharePoint Online only + - **Web Part Name**: `GleanSearch` + - **Framework**: React + + + + Replace the generated code with the Glean-specific implementation: + + - **Search Web Part**: Download from [cs-tools/sharepoint-webpart-search](https://github.com/askscio/cs-tools/tree/main/sharepoint-webpart-search) + - **Chat Web Part**: Download from [cs-tools/sharepoint-webpart-chat](https://github.com/askscio/cs-tools/tree/main/sharepoint-webpart-chat) + + + +### Customize for Your Environment + + + + The web part uses `document.querySelector('input[placeholder*="Search"]')` to locate SharePoint's search input. + + If your SharePoint site uses different search box styling or placeholder text, modify this selector in the web part code. + + + + Update the Glean configuration in the web part properties: + - Backend URL + - Authentication settings + - Application ID (for Chat web parts) + + + + Test the web part in a non-production SharePoint environment before deploying to live sites. + + + +## Build and Package + + + + ```bash + gulp build + ``` + + + + ```bash + gulp bundle --ship + ``` + + + + ```bash + gulp package-solution --ship + ``` + + This creates a `.sppkg` file in the `sharepoint/solution` folder. + + + +## Deploy to SharePoint + + + + 1. Navigate to your SharePoint App Catalog + 2. Upload the generated `.sppkg` file + 3. Click **Deploy** when prompted + + + + Choose one of these deployment options: + + + + + Select **Enable this app and add it to all sites** to make the web part available across your tenant. + + + + + Select **Only enable this app** to manually add the web part to specific sites. + + + + + + + Wait for the confirmation message indicating successful deployment. + + + +## Add Web Part to SharePoint Pages + + + + Go to the SharePoint site where you want to add Glean functionality. + + + + Click the **Edit** button to modify the page. + + + + 1. Click the **+** icon to add a new web part + 2. Search for your Glean web part by name + 3. Select and add it to the page + + :::note + The web part can be added to any page section. It will activate when users interact with the SharePoint search box, regardless of where the web part is positioned. + ::: + + + + Configure any web part properties specific to your Glean deployment. + + + + Save and **Republish** the page to make the Glean functionality live. + + + +## Testing the Integration + + + + Test that Glean Search activates when users interact with the SharePoint search box. + + + + Ensure that API calls to Glean services are functioning correctly. + + + + Confirm that the search interface and results display properly within the SharePoint environment. + + + +## Chat Integration + +To implement Glean Chat instead of or in addition to Search, follow the same process using the Chat web part code. The main differences are: + +- Use the chat-specific web part code from the cs-tools repository +- Configure the Application ID for your specific AI application +- Customize the chat trigger element selector as needed + +## Troubleshooting + +### Common Issues + +**App Catalog Not Found (404 Error)** +If you encounter a 404 error when accessing the App Catalog, it may not be created yet. Follow the App Catalog setup steps in the Prerequisites section. + +**Web Part Not Appearing** +- Verify the web part is properly deployed to the App Catalog +- Confirm the page is using the modern SharePoint experience +- Check that you have sufficient permissions to add web parts + +**Search Box Not Detected** +If the Glean functionality doesn't activate: +- Inspect your SharePoint page to identify the correct search box selector +- Update the `querySelector` in the web part code to match your page structure +- Test the selector in the browser console before rebuilding + +### Getting Help + +For additional support with SharePoint integration: +- Review the [SharePoint Framework documentation](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) +- Check the [SPFx Yeoman Generator guide](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/yeoman-generator-for-spfx-intro) +- Consult SharePoint admin resources for App Catalog management + +## Technical Reference + +### Code Structure + +The Glean web parts extend Microsoft's `BaseClientSideWebPart` class, which provides: +- Lifecycle methods (`onInit`, `render`, `onDispose`) +- Property management for user-defined settings +- Context access for SharePoint resources + +### Key Components + +- **Web Part Implementation**: Extends `BaseClientSideWebPart` with Glean-specific functionality +- **Element Detection**: Uses `document.querySelector` to locate SharePoint search elements +- **Dynamic Loading**: Loads Glean SDK from `https://app.glean.com/embedded-search-latest.min.js` +- **Search Integration**: Attaches Glean's EmbeddedSearch object to SharePoint's search interface + +### Useful Resources + +- [SharePoint Framework Overview](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) +- [SharePoint App Catalog Management](https://learn.microsoft.com/en-us/sharepoint/use-app-catalog) +- [SPFx Development Environment Setup](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/yeoman-generator-for-spfx-intro) diff --git a/sidebars.ts b/sidebars.ts index a0c3e504..32bde42f 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -283,6 +283,11 @@ const sidebars: SidebarsConfig = { id: 'libraries/web-sdk/guides/react', label: 'React', }, + { + type: 'doc', + id: 'libraries/web-sdk/guides/sharepoint', + label: 'SharePoint', + }, { type: 'doc', id: 'libraries/web-sdk/guides/zendesk',