Box Status
Print

Enabling the Box Copilot Connector

The Box Copilot Connector allows Box and Microsoft customers to index Box data so it appears in Microsoft 365 experiences. By enabling this integration, Microsoft 365 users can discover Box content from Microsoft Search, Microsoft 365 app, or Microsoft Copilot.

These steps will guide a Microsoft admin through enabling the Box Copilot Connector integration for their tenant.

Broadly, these are the main steps you need to follow when you deploy the Box Copilot Connector for integration in your enterprise:

  1. Authorize the App
  2. Monitor Box as an External Data Source
  3. Add the Box Search Vertical
  4. [Optional] Customize the Vertical
  5. [Optional] Disabling the Integration

Please make sure you have filled out the enablement form. We would need the information in the form to complete the setup for you. In the meantime, you can proceed with Step 1 which is the pre-requiste for us to configure the connection for you.

Step 1: Authorize the App

This step authorizes the app, and allows it to perform API calls necessary to sync Box content to Microsoft Graph.

  1. As an admin of the Microsoft tenant, open a new tab and navigate to: https://login.microsoftonline.com/{TENANT_ID}/v2.0/adminconsent?client_id=1aab5478-9db7-40c6-90fa-6adfad72e0a9&state=12345&scope=https://graph.microsoft.com/.default&redirect_uri=https://account.box.com, replacing {TENANT_ID} with the Microsoft tenant ID which you'll be enabling the Copilot Connector for. You can find your Microsoft tenant ID in your admin Azure portal: https://aad.portal.azure.com/
  2. On the consent screen, click Accept.
  3. After clicking Accept, you will be taken to Box. You can close the tab - no actions need to be taken in Box.
  4. Verify that the app has been added to the tenant and authorized. Go to https://aad.portal.azure.com -> Applications -> Enterprise applications -> and look for the Box Graph Connector app in the enterprise applications list.
  5. Click on the app, and go to Permissions. All of the permissions should be granted. If one or more permissions have not been granted, you can grant them by clicking the “Grant admin consent for {tenant}” button. 

             

  1. Notify us that the tenant is ready to begin ingesting data by responding to the email from partnerintegrations@box.com. We will perform work on the Box side to create the data connection between Box and Microsoft Graph, and onboard the Box enterprise to the service.

Step 2: Monitor Box as an External Data Source

Once Box setup is complete, you can follow these steps to monitor the connection

  1. We will inform you via email once the Box setup is complete.
  2. You can log into https://admin.microsoft.com as a tenant admin to monitor the connection.
  3. On the left sidebar, click Copilot -> Connectors. Click the Your Connections tab at the top.
  4. You should see a Box datasource, with a connection ID of “boxmsgraph”. The connection will initially be in a draft state until the service has finished setting up the connection. This may take several hours or weeks, depending on the load of the service.
  5. Once the connection has been fully configured, the connection state should change to Ready.
  6. You can also view the number of items indexed and the last sync time by clicking on the connection, in the Detail section (Please note that the Statistics tab is not supported for third-party connectors).
  7. Please make sure you enable Copilot Visibility to allow content indexed via the Box Copilot Connector to appear in Copilot Chat and search results.

Step 3: Add the Box Search Vertical

Now that the Box data source has been configured, the next step is to configure a vertical for the data source. The vertical is what users will use to search for Box files in the UI.

  1. As a tenant admin, log into https://admin.microsoft.com, go to Settings -> Search & intelligence -> Customizations.
  2. Under the Verticals tab, click Add.
  3. Pick the name that you want to appear for the Box tab in the UI. Something like “Box” or “Box Files”, although feel free to name it however you’d like.
  4. For the content source, choose the Box data source configured in the previous step.
  5. The query and filters steps can be skipped.
  6. Finally, click Add Vertical to save the new vertical.
  7. The vertical will soon be visible to users (it may take anywhere from a few minutes to several hours to appear for all users). You can see the vertical by going to https://m365.cloud.microsoft/search/, and typing a query into the search bar at the top of the screen. There should be a tab with the vertical name configured in the previous step. Results may not appear under the vertical until the initial sync has completed, which can take anywhere from a few hours to several days.
  8. To view Box files that have been indexed, you can navigate to the Box vertical and search for *. This will return all indexed Box content for that specific user.

Note: Box results should appear in the All vertical by default. If this is not the case, you can follow the steps detailed here.

Step 4: [Optional] Customize the Vertical

Optionally, you can choose to customize the way that search results are displayed in the Box vertical. If you don’t customize the search result layout, a default layout will be used.

  1. As a tenant admin, log into https://admin.microsoft.com, go to Settings -> Search & intelligence -> Customizations.
  2. Click the Result types tab, and add a new result type. Name the result type something like “Box file” and set its content source to the Box data connection configured previously.
  3. The Rules step can be skipped unless you want a more advanced configuration for your result type.
  4. The Layout step lets you configure how results should be displayed when searching. The layout designer gives you a visual interface to configure the result, and can be used to generate the customization JSON.
    1. When using the layout designer, properties are mapped to elements in the layout. The Box Copilot Connector exposes the following properties:
      1. id – The Box file ID
      2. name – The file’s name, including extension
      3. fileName – The file name without extension
      4. extension – The file’s extension
      5. createdByName – The name of the user who created the file
      6. createdAt – The date and time which the file was created
      7. ownedByName – The name of the user who owns the file
      8. modifiedByName – The name of the user who last modified the file
      9. modifiedAt – The date and time which the file was last modified
      10. url – A URL to view the file in Box
      11. size – The file’s size in bytes
      12. icon – A generic icon for the file based on the file’s extension
      13. thumbnail – A thumbnail-sized image of the file. If content ingestion is disabled or there is no thumbnail for the file, then the thumbnail will be the same as the icon
      14. ResultSnippet – A special Microsoft-supplied field which shows relevant portions of the file’s text with matching search terms highlighted. If content ingestion is disabled or the file is a type which does not support text indexing, then there will be no result snippet. Note that ResultSnippet capitalizes the first letter, unlike the other property names.
  5. If you don’t want to create a custom layout using the designer, you can use this layout developed by Box: https://cloud.box.com/s/p8g567z3tsh45pzh4bz8kywk2vhm88d2.

Step 5: [Optional] Disabling the Integration

Disabling the Box Copilot Connector will prevent users from searching for Box content from Microsoft products, and delete any Box data indexed by the integration. 

  1. Contact us to update the service so that it stops syncing enterprise data to Microsoft Graph.
  2. As a tenant admin, log into https://admin.microsoft.com and go to Settings -> Search & intelligence -> Data sources.
  3. Select the “boxmsgraph” connection, and click the trash icon near the connection’s name. This will delete the connection. It may take several minutes for all indexed data to be deleted.

Related articles