> For the complete documentation index, see [llms.txt](https://docs.aisera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisera.com/aisera-platform/adding-data-to-your-tenant/integrations-and-data-sources/connectors/box-connector.md).

# Box Connector

## Overview

This topic describes how to configure and use the Box connector for the Aisera platform as a data source.

The Box connector uses the **File Data** data source during setup.  This method increases your flexibility by allowing you to Easily ingest data from multiple non-contiguous folders and sub-folders. This configuration supports the following key features.

#### Multiple Folder Ingestion

In the Data Source configuration, you can enter multiple **Box Folder IDs** separated by commas in the **Folder Id** parameter. This allows you to include content from several specific folders within a single data source.

#### Recursive Folder Crawling

When **Enable Recursion** is selected, the connector will automatically crawl and ingest supported files from all sub-folders nested within the specified **Folder IDs**. This eliminates the need to manually add every sub-folder ID individually when you want to include nested content.

## Prepare

### Authorization

The Box connector for the Aisera Platform supports **OAuth 2.0** for authentication. You will need to create a **Custom Application** on the Box Platform to authorize the Aisera Platform to ingest data. Go to [Setup with OAuth 2.0](https://developer.box.com/guides/authentication/oauth2/oauth2-setup/) for instructions on how to do this.

You will need to set the Redirect URI during the setup of the custom application. The redirect URI is: `https://<your_tenant>.login.aisera.<top_level_domain>/?id=aisera.oauth.oauthCommand`&#x20;

You will need to enable the following options in the **Application Scopes**:

* Write All files and Folders Stored in Box
* Manage Enterprise Properties

For the integration step, take note of the following credentials:

* Access Token URL
* Authorization URL
* Client Id
* Client Secret

{% hint style="info" %}
Access Token URL and Authorization Token URL are usually the same for all Box Cloud instances, and are generally in the format of:

`https://<account>.box.com/api/oauth2/token`

`https://<account>.box.com/api/oauth2/authorize`
{% endhint %}

#### Manual Approval

You may need to manually approve the application if the application if the application is inactive by default. Go to [Platform App Approval ](http://developer.box.com/guides/authroization/platform-app-approval/)to learn about how to enable an application.

## Integration Setup

1. In the Aisera Admin UI navigate to **Settings > Integrations**

2. Click on **+ New Integration**

3. In the menu, select **Box** and click **Next**<br>

   <div align="left"><figure><img src="/files/e9DcfmOF9UkvG1WMzCfm" alt=""><figcaption></figcaption></figure></div>

4. Enter the configuration details, then click  **Next**

   <table><thead><tr><th width="157.20001220703125">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>The name used to identify the integration</td></tr><tr><td>Description</td><td>A description of the integration and it's purpose</td></tr></tbody></table>

5. Under the **Auth Type** dropdown select **OAuth**<br>

   <div align="left"><figure><img src="/files/a88dThW5zjWKGirGvV5o" alt=""><figcaption></figcaption></figure></div>

6. Enter the collected credentials

7. Click **OK**

When you click **Ok** you will be directed to the Box Platform to authorize the Aisera Platform to use OAuth. When authorization is complete the integration will be saved.

## Data Source Setup

To set up the **File Data** data source for the Box connector:

1. In the Aisera Admin UI navigate to **Settings > Data Sources**
2. Click **+ New Data Source** in the upper right corner
3. Select **File Data** and click **Next**\ <br>

   <div align="left"><figure><img src="/files/cLyijvLlOyqw34FFhryv" alt=""><figcaption></figcaption></figure></div>
4. Select **Cloud Files**. You can now see the integrations that are available for your tenant<br>

   <div align="left"><figure><img src="https://aisera.gitbook.io/~gitbook/image?url=https%3A%2F%2F2983236984-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FiZkLJr3EjXkd2tHYiQJP%252Fuploads%252FRytW67jEyLAn6p8rNKZA%252F8.png%3Falt%3Dmedia&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=8971ddcd&#x26;sv=2" alt="" width="563"><figcaption><p>Box Data Source Configuration</p></figcaption></figure></div>
5. Choose the **Box integration** that you created in Step 2
6. After you enter the integration, you will see the updated **Folder Id** parameter. Enter a comma-separated list of Folder Ids corresponding to the folders you want to ingest data from
7. Click **Next** until the window closes to complete the creation of the **Data Source.**

## Optional Configurations

All remaining configurations are optional. See the section below for more information.

### Enable Recursion

When enabled, the Aisera Platform will check for and ingest content from all subfolders contained in the folders listed in the **Folder Id** field.

### **Extract metadata (metatags) from .boxnote files during ingestion**

This enables the RAG layer to filter and serve knowledge articles based on attributes such as **region**, **audience**, **access level**, **content type**, and other custom metadata fields configured in the **Box Data Source**.

**Key Capabilities of Metadata Extraction:** **Metadata Extraction:** A new "Fetch Metadata" checkbox is available in the Box integration configuration. When enabled, the connector calls Box's metadata API endpoints to retrieve all metadata templates and their field values attached to .boxnote files.

**Downstream Propagation:** Extracted metadata is included in the ingestion payload under a customMetaData object, preserving the full template structure (e.g., template name, field keys, and values).

**ACL-Based Filtering via Custom Scripts:** Administrators can apply custom transformation scripts in the field mapping configuration to map specific metadata fields (e.g., region) to tagKeys and tagValues. This enables attribute-based access control and filtered retrieval at query time.

**Multi-Value Support:** Array-type metadata fields (e.g., a file tagged to multiple regions like \["AMER", "EMEA"]) are correctly parsed and mapped as individual tag entries.

#### **To Enable Metadata Fetching:**

1. Navigate to **Settings > Connectors** in the Aisera Admin UI.
2. Open the **Box Connector Data Source**.
3. Select the **pencil icon** to open the **Edit Data Source** window.
4. Choose the **Configuration** tab.

<div align="left"><img src="https://docs.aisera.com/~gitbook/image?url=https%3A%2F%2F2983236984-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FiZkLJr3EjXkd2tHYiQJP%252Fuploads%252Fnx0XiUVtj37MKALZCx05%252Fedit_ds.gif%3Falt%3Dmedia%26token%3Deac6a612-d133-41dc-894a-39a79c294247&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=4a1080b2&#x26;sv=2" alt="" width="563"></div>

5. Enable the **Fetch Metadata** checkbox.

<div align="left"><img src="https://docs.aisera.com/~gitbook/image?url=https%3A%2F%2F2983236984-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FiZkLJr3EjXkd2tHYiQJP%252Fuploads%252FMsADcH5vK5V8CuTWe6qI%252Fknow_doc_tags.gif%3Falt%3Dmedia%26token%3D68d6a4ff-0fc7-4494-8397-df51bd1915a0&#x26;width=768&#x26;dpr=3&#x26;quality=100&#x26;sign=f58f6544&#x26;sv=2" alt="" width="563"></div>

6. Configure field mappings to map your desired metadata fields to **tagKeys/tagValues** using a custom transformation script.
7. Enable auto-commit on the datasource and attach it to the target bot.
8. Validate that metadata appears correctly in the **System of Record (SOR)** and that retrieval respects the configured attributes.

## Post Setup Actions

Your Aisera team can use test knowledge articles to ingest and then determine the specific fields that are mapped, if your data source administrators want to restrict the access of the Aisera Service User account to only those fields.