🗃️Connect Sharepoint

This guide provides a step-by-step walkthrough for setting up SharePoint folders as knowledge bases using Azure Active Directory applications.

Register Azure Active Directory (AAD) Application in Azure Portal

For detailed guidance, refer to our Connect Azure AD guide.

1. Register Sites Admin App

1.1 Create a New Sites Admin App

• Go to the Overview page and obtain the Client ID (Application (client) ID) and Tenant ID (Directory (tenant) ID). Save this information in a text file.

1.2 Grant Graph API Permission

Go to Sites Admin App Registration, you give Graph API permission with Application.Read.APP and Sites.FullControl.All.

Remember to grant admin consent for these permissions.

1.3 Create Client Secret Key

Navigate to the Certificate & Secrets page to create secrets.

• Copy the secret key value to the text file containing the Client ID and Tenant ID. Your text file should include:

Client Id: 4dbceba4-*******-960918801231
Client Secret: JPz******************
Directory (tenant) ID: cef6ac5c-7bc6-*****-fdf05232c2f4

Final Step:

Provide the Client ID, Client Secret Key, Tenant ID of the Target Application, and a list of selected sites to connect to the Knowledge Bots platform.

2. Register Target Application for Connecting SharePoint

• Follow the steps above, but only create Certificates & Secrets with Sites.Selected permission.

• Copy the secret key value to the text file containing the Client ID and Tenant ID. Your text file should include:

Client Id: 1ad09322-6c74-*****-8d736a2d9e92
Client Secret: Npn******************
Directory (tenant) ID: cef6ac5c-7bc6-*****-fdf05232c2f4

3. Use Graph API Endpoint to Assign Permissions to Specific SharePoint Online Site

Refer to Graph API Documentation.

• Use the Client ID, Client Secret, and Tenant ID of the Site Admin App to assign the Target Application permissions to a specific SharePoint Online site.

Steps to Use Graph API:

Step 1: Get Token from Microsoft Graph API

• Use Postman to call the API.

Step 2: Get Site ID for the Target Application

• Example: To connect with the "Site Data Local Test" site, obtain the site ID: trustsoftjsc.sharepoint.com,de3c6e23-0395-4050-8157-46a1b5b1482e,3ec5a27e-56a1-4d99-b9d1-87a27b6335e3.

Step 3: Assign Permissions to the Target Application

• Make a POST request to the following endpoint:

POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions
Content-Type: application/json

{
  "roles": ["read"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "clientId",  // Target Application’s Client ID
        "displayName": "Site Data Local Test"  // Target Application’s Display Name
      }
    }
  ]
}

Step 4: Recheck Site Permissions

• Verify the permissions assigned to the site.

Final Step:

Provide the Client ID, Client Secret Key, Tenant ID of the Target Application, and a list of selected sites to connect to the Knowledge Bots platform.

4. Web Part: Deployment & Configuration Guide

Use this guide to deploy, configure, and troubleshoot your Blockbrain Chat SPFx Web Part in SharePoint Online.

1. Deploy the Package to SharePoint

1. Access the App Catalog

2. Navigate to your SharePoint Online App Catalog site. Usually the URL is something like:

https://<your-tenant>.sharepoint.com/sites/AppCatalog

1. Upload the Package

   1. Go to Apps for SharePoint (in the left navigation).

   2. Click Upload and select the .sppkg file from the sharepoint/solution folder of your project.

   3. When prompted, check Make this solution available to all sites in the organization if you want it globally available.
   4. Click Deploy.

      
2. Verify Deployment

   • If you selected Make this solution available to all sites, the web part should automatically be available on all site collections.

   • Otherwise, you may need to explicitly add the app to the site where you want to use it.

---

2. Add the Web Part to a SharePoint Page

1. Navigate to Your SharePoint Site

2. Go to the site where you want to add the chatbot.

3. Edit the Page

4. Click on the gear icon and select Edit Page or Edit.

5. Add the Web Part

   • Click on the + icon to add a new web part.

   • Search for BlockbrainChat (or the name you provided during setup).

   • Add it to the page.

---

3. Web Part Configuration

The new web part has three primary configuration sections in its Property Pane: Authentication, Content, and Appearance.

1. Open the Web Part Property Pane

   • While the page is in Edit mode, select the Blockbrain Chat web part.

   • Click the pencil icon to open the web part’s property pane.

2. Authentication

   • Login Mode (loginMode)

     • Private Login: Uses an issuer URL (auth endpoint).

     • Public Login: Uses clientId and secretKey for public authentication.

   • Issuer (Private Login only) (issuer)

     • Provide the issuer endpoint URL if you have set loginMode to "private".

   • Client ID / Secret Key (Public Login only) (clientId, secretKey)

     • Provide the OAuth2 credentials to authenticate with Blockbrain if you have set loginMode to "public".

3. Content

   • Bot Unique Identifier (uid)

     • Enter the bot UID if you want to specify a particular bot.

     • This can also be overridden by URL parameters (e.g., ?uid=your-bot-id).

4. Appearance

   • Width & Height (width, height)

     • Accepts any valid CSS size value: e.g., 100%, 600px, 50vh, etc.

     • Use % or viewport units for responsive design, or px for a fixed size.

   • Icon URL (iconUrl)

     • Provide a direct URL to the icon you want displayed in the chat.

   • Icon Size (iconSize)

     • Set the size of the icon (e.g., 50px, 96px).

   • Custom Messages JSON (messages)

     • Allows you to override or customize system messages. Must be valid JSON.

   • Background Color (backgroundColor)

     • Pick a color from the color picker or input a hex code (e.g., #FFFFFF).

5. Web Part Title

   • By default, the web part will show a title area. You can edit it directly on the page:

     1. Click on the web part title text.

     2. Enter your custom title (e.g., “Customer Support Chat”).

     3. Press Enter or click outside to save.

6. Saving and Publishing

   • After you finish configuring the properties, click Apply (if needed), then Publish the page.

---

4. Additional Configuration Options

1. URL Parameters

   • You can override the bot UID by appending ?uid=YOUR_BOT_UID to the page URL.

   • Similarly, you can specify a userUid with ?userUid=SOME_VALUE to track or identify the user differently.

2. For Detailed Prop Documentation

   • Refer to the official Blockbrain Docs for additional, up-to-date property references and usage examples.

---

5. Troubleshooting & Common Issues

1. Script Loading Issues

   • Correct External Script URL: Ensure you haven’t altered the blocky-chat.bundle.js URL.

   • Network / Proxy Restrictions: If your company network blocks external scripts, ensure https://assets.theblockbrain.io/ is allowed.

2. Authentication Errors

   • Double-check loginMode, issuer, clientId, and secretKey in the property pane.

   • If using private login, ensure the issuer endpoint is correct.

   • If using public login, ensure both client ID and secret key are valid.

3. Bot Not Found

   • Verify the uid you provided (either in the web part property or URL) is a valid bot UID from your Blockbrain environment.

4. Web Part Not Appearing or ‘Not Found’

   • Ensure you uploaded the .sppkg file to the App Catalog.

   • Check Make this solution available to all sites if you want it to appear in site collections.

   • If not, add the solution to your specific site’s Site Contents.

5. Other Users Cannot View the Web Part

   • Confirm that the web part (and the underlying script) is shared or accessible by all intended users.

   • If the script is externally hosted, verify that the script domain is not restricted by tenant policies.