Skip to main content

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).

Glean Search

Embed Glean's search functionality directly into SharePoint pages

Glean Chat

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​

The Glean sample web parts use SPFx 1.19 and require SharePoint Online (Microsoft 365). SharePoint Server on-premises releases support only older SPFx versions; see Microsoft's SPFx compatibility reference.

Required Permissions​

Uploading to the tenant App Catalog requires the SharePoint Administrator role or higher. Adding a deployed web part to a page requires permission to edit that page.

App Catalog Verification​

1

Check App Catalog Availability

Navigate to your App Catalog: https://<tenant-name>.sharepoint.com/sites/appcatalog/_layouts/15/tenantAppCatalog.aspx/manageApps

If you encounter a 404 error, the App Catalog needs to be created.

2

Create App Catalog (if needed)

  1. Open the SharePoint admin center: https://<tenant-name>-admin.sharepoint.com
  2. Select More features, then under Apps select Open
  3. Follow the prompts to create the App Catalog site

See Manage apps using the Apps site.

3

Verify Modern Pages

Use modern SharePoint pages. The Glean samples attach to the modern SharePoint search box.

Development Environment Setup​

1

Install Node.js

The Glean sample web parts use SPFx 1.19, which requires Node.js 18 (18.17.1 or later). Node.js 18 is past end of life, so use it only for building these samples. For other SPFx versions, check Microsoft's SPFx compatibility reference.

# Check current version
node -v

# Install Node.js 18.x if needed
# Visit https://nodejs.org/en/download/package-manager for installation instructions
2

Install Development Tools

The samples use the gulp-based SPFx toolchain. Install the gulp CLI globally:

npm install gulp-cli -g
3

Set Up Code Editor

Install Visual Studio Code or your preferred code editor for SPFx development.

Creating the SPFx Web Part​

Get the Sample Project​

Start from a Glean sample instead of generating a new project. The current SPFx generator creates Heft-based projects, which do not use the gulp commands below.

1

Clone the Samples

git clone https://github.com/gleanwork/web-sdk-embed-examples.git
cd web-sdk-embed-examples/sharepoint-webpart-search

For Chat, use sharepoint-webpart-chat instead.

2

Install Dependencies

npm install

Customize for Your Environment​

1

Update Search Element Selector

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.

2

Configure Glean Settings

Set these web part properties after you add the web part to a page:

  • Backend URL (backendURL)
  • Application ID (applicationId, Chat web part only)
3

Test in Development

Test the web part in a non-production SharePoint environment before deploying to live sites.

Build and Package​

1

Build the Project

gulp build
2

Create Production Bundle

gulp bundle --ship
3

Package the Solution

gulp package-solution --ship

This creates a .sppkg file in the sharepoint/solution folder.

Deploy to SharePoint​

1

Upload to App Catalog

  1. Navigate to your SharePoint App Catalog
  2. Upload the generated .sppkg file
  3. Click Deploy when prompted
2

Enable App

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.

3

Confirm Deployment

Wait for the confirmation message indicating successful deployment.

Add Web Part to SharePoint Pages​

1

Navigate to Target Page

Go to the SharePoint site where you want to add Glean functionality.

2

Edit the Page

Click the Edit button to modify the page.

3

Add the Web Part

  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.

4

Configure Properties

Configure any web part properties specific to your Glean deployment.

5

Save and Publish

Save and Republish the page to make the Glean functionality live.

Testing the Integration​

1

Verify Search Functionality

Test that Glean Search activates when users interact with the SharePoint search box.

2

Check API Connectivity

Ensure that API calls to Glean services are functioning correctly.

3

Validate User Experience

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 web-sdk-embed-examples/sharepoint-webpart-chat
  • Configure the Application ID for your specific AI application
  • The chat web part renders Glean Chat in its own container on the page, so it does not need a search box selector

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

Glean script blocked due to Content Security Policy

Find your Glean Web app URL in the admin console. In the SharePoint admin center, go to Advanced > Script sources and add it as a trusted script source.

See Microsoft's trusted script sources guide.

Getting Help​

For additional support with SharePoint integration:

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 the Glean Web SDK script with SPComponentLoader.loadScript. The samples load it from app.glean.com; replace this with your Glean app domain if it differs.
  • Search Integration: Calls the SDK's attach method on SharePoint's search input

Useful Resources​