> For the complete documentation index, see [llms.txt](https://docs.ovaledge.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ovaledge.com/release7.2/connectors/connector-repositories/file-connectors/box.md).

# Box

This article outlines the integration with the Box connector, enabling streamlined metadata management through features such as crawling, data preview, data quality, and manual lineage building. The connector extracts folder, file, and supported file-type metadata and maps them to corresponding catalog assets.

The connector connects to Box using SDK-based connectivity and retrieves metadata from Box file system objects and attributes. Authentication is established using OAuth 2.0 client credentials flow with Client ID and Client Secret managed through a credential manager, enabling access to Box APIs for secure retrieval of folders, files, and related metadata objects.

<figure><img src="https://1813356899-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhTnkoJQml0pok9awFDhx%2Fuploads%2FdmPMwvW1GGUKe9JASMAF%2Fimage.png?alt=media&amp;token=07892e57-90be-4d83-b437-51da2665858f" alt=""><figcaption></figcaption></figure>

## Overview

### **Connector** Details

| Connector Category                                                      | File Connectors      |
| ----------------------------------------------------------------------- | -------------------- |
| OvalEdge Release Supported                                              | Release6.x and later |
| <p>Connectivity</p><p>\[How the connection is established with Box]</p> | SDK                  |
| Verified Box Version                                                    | 4.x                  |

{% hint style="info" %}
The Box connector has been validated with the mentioned "Verified Box Versions" and is expected to be compatible with other supported Box versions. If there are any issues with validation or metadata crawling, please submit a support ticket for investigation and feedback.
{% endhint %}

### Connector Features

| Feature                                      | Availability |
| -------------------------------------------- | :----------: |
| Crawling                                     |       ✅      |
| Delta Crawling                               |       ❌      |
| Profiling\*                                  |       ✅      |
| Sample Profiling                             |       ✅      |
| Query Sheet                                  |      NA      |
| Data Preview                                 |       ✅      |
| Auto Lineage                                 |      NA      |
| Manual Lineage                               |       ✅      |
| Secure Authentication via Credential Manager |       ✅      |
| Data Quality                                 |       ✅      |
| DAM (Data Access Management)                 |       ❌      |
| Bridge                                       |       ✅      |

{% hint style="info" %}
NA' indicates that the respective feature is 'Not Applicable.'
{% endhint %}

{% hint style="info" %}
\*Full profiling is supported through DuckDB. To enable this capability, configure the system setting (**enable.duckdb**) to **True**. When enabled, the File Data tab displays only the first 100 rows from the source file.
{% endhint %}

### Metadata Mapping

The following objects are crawled from Box and mapped to the corresponding UI assets.

<table><thead><tr><th>Box Object</th><th width="134">Box Attribute</th><th width="170.3333740234375">OvalEdge Attribute</th><th width="172.5482177734375">OvalEdge Category</th><th width="148">OvalEdge Type</th></tr></thead><tbody><tr><td>Folder</td><td>Folder</td><td>Folder</td><td>Folder</td><td>Folder</td></tr><tr><td>File</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>↳ XLSX (Sheets)</td><td>File</td><td>File (subfile)</td><td>File (subfile)</td><td>File (subfile)</td></tr><tr><td>↳ XLS (Sheets)</td><td>File</td><td>File (subfile)</td><td>File (subfile)</td><td>File (subfile)</td></tr><tr><td>CSV</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>TXT</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>PARQUET</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>ORC</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>JSON</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>YAML</td><td>File</td><td>File</td><td>File</td><td>File</td></tr><tr><td>PIP</td><td>File</td><td>File</td><td>File</td><td>File</td></tr></tbody></table>

{% hint style="info" %}
The file types to be cataloged are controlled through a system setting. Navigate to the Common Files Configuration page to manage supported file types. The setting key is `config.file.types.to.be.cataloged`, with a default value of csv, conf, env, sh, properties, txt, yaml, xlsx, json, ddl, sql, hql, and parquet.
{% endhint %}

## Set up a Connection

### Prerequisites

The following are the prerequisites to establish a connection.

Ensure that the CSV files follow the required formatting standards for proper data processing and visibility. Refer to [CSV Format Requirements](https://docs.ovaledge.com/connectors/additional-requirements/csv-format-requirements-for-file-connectors)**.**

For detailed steps to create a Box custom application, configure access permissions, authorize the application, and generate the required **User ID, Client ID, and Client Secret**, refer to [**Box Authentication Configuration**](https://docs.ovaledge.com/connectors/connector-repositories/file-connectors/box/box-authentication-configuration).

{% hint style="info" %}
OvalEdge supports OAuth 2.0 client credentials–based authentication.
{% endhint %}

#### **Service Account User Permissions**

{% hint style="warning" %}
It is recommended to use a dedicated service account to establish the connection to the data source, configured with the following minimum set of permissions.
{% endhint %}

{% hint style="info" %}
👨‍💻Who can provide these permissions? These permissions are typically granted by the Box administrator, as users may not have the required access to assign them independently.
{% endhint %}

| Operations           | Objects         | Access Permission |
| -------------------- | --------------- | ----------------- |
| Connector Validation | -               | Read on APP       |
| Crawling             | Files & Folders | Read on APP       |
| View File Data       | Files & Folders | Write on APP      |
| Profiling            | Files & Folders | Write on APP      |

### Connection Configuration Steps

{% hint style="warning" %}
Users are required to have the Connector Creator role in order to configure a new connection.
{% endhint %}

1. Log into **OvalEdge**, go to **Administration > Connectors**, click **+ (New Connector)**, search for **Box**, and complete the required parameters.

{% hint style="info" %}
Fields marked with an asterisk (\*) are mandatory for establishing a connection.
{% endhint %}

<table><thead><tr><th width="220.25">Field Name</th><th>Description</th></tr></thead><tbody><tr><td>Connector Type</td><td>By default, "Box" is displayed as the selected connector type.</td></tr><tr><td>Credential Manager*</td><td><p>Select the desired credentials manager from the drop-down list. Relevant parameters will be displayed based on the selected option.</p><p>Supported Credential Managers:</p><ul><li>OE Credential Manager</li><li>AWS Secrets Manager</li><li>HashiCorp</li><li>Azure Key Vault</li></ul><p>For more details, click <a href="https://docs.ovaledge.com/connectors/additional-requirements/credential-manager-configuration">here</a>.</p></td></tr><tr><td>License Add Ons</td><td>Select the checkbox for <strong>Data Quality Add-On</strong> to identify data quality issues using data quality rules and anomaly detection.<br>For more details, click <a href="https://docs.ovaledge.com/connectors/introduction-to-connectors/setup-and-connectivity/license-types-and-add-ons">here</a>.</td></tr><tr><td>Connector Environment</td><td>Select the environment (Example: PROD, STG) configured for the connector.<br>For more details, click <a href="https://docs.ovaledge.com/connectors/introduction-to-connectors/setup-and-connectivity/prerequisites#connector-environment">here</a>.</td></tr><tr><td>Connector Name*</td><td><p>Enter a unique name for the Box connection              </p><p>(Example: "Boxdb").</p></td></tr><tr><td>Connector Description</td><td>Enter a brief description of the connector.</td></tr><tr><td>Client ID*</td><td>Enter the unique Client ID provided by the service or application for authentication.</td></tr><tr><td>Client Secret*</td><td>Enter the Client Secret associated with the Client ID to securely authenticate the connection.</td></tr><tr><td>User ID*</td><td>Enter the registered User ID used to access the external system or service.<br><strong>Note</strong>: The User ID must be the Box numeric user ID. Ensure to provide the correct numeric ID associated with the Box account.</td></tr></tbody></table>

**Default Governance Roles**

<table data-header-hidden><thead><tr><th width="220.25"></th><th></th></tr></thead><tbody><tr><td>Default Governance Roles*</td><td>Select the appropriate users or teams for each governance role from the drop-down list. All users configured in the security settings are available for selection.</td></tr></tbody></table>

**Admin Roles**

<table data-header-hidden><thead><tr><th width="219"></th><th></th></tr></thead><tbody><tr><td>Admin Roles*</td><td><p>Select one or more users from the dropdown list for Integration Admin and Security &#x26; Governance Admin. All users configured</p><p>in the security settings are available for selection.</p></td></tr></tbody></table>

**No of Archive Objects**

<table data-header-hidden><thead><tr><th width="220.25"></th><th></th></tr></thead><tbody><tr><td>No Of Archive Objects*</td><td><p>This shows the number of recent metadata changes to a dataset at the source. By default, it is off. To enable it, toggle the Archive button and specify the number of objects to archive.</p><p>Example: Setting it to 4 retrieves the last four changes, displayed in the 'Version' column of the 'Metadata Changes' module.</p></td></tr></tbody></table>

**Bridge**

<table data-header-hidden><thead><tr><th width="220.25"></th><th></th></tr></thead><tbody><tr><td>Select Bridge*</td><td><p>If applicable, select the bridge from the drop-down list.</p><p>The drop-down list displays all active bridges that have been configured. These bridges facilitate communication between data sources and the system without requiring changes to firewall rules.</p></td></tr></tbody></table>

2. After entering all connection details, the following actions can be performed:
   1. Click **Validate** to verify the connection.
   2. Click **Save** to store the connection for future use.
   3. Click **Save & Configure** to apply additional settings before saving.
3. The saved connection will appear on the Connectors home page.

## Manage Connector Operations

### Crawl

{% hint style="warning" %}
To perform crawl & profile operations, users must be assigned the Integration Admin role.
{% endhint %}

1. Navigate to the **Connectors** page and click **Crawl/Profile.**
2. This action initiates the metadata collection process from the data source and loads the retrieved metadata into the **File Manager > File Explorer.**
3. In the File Manager, click the connector name, select the specific **folder(s) or file(s)**, then click **Catalog / Catalog and Profile** from the **Nine Dots** menu. For more details, click [here](https://docs.ovaledge.com/file-manager/file-explorer).
4. The selected files or folders will be added to the **Data Catalog > Files/File Columns** tab.

### Other Operations

The **Connectors** page provides a centralized view of all configured connectors, along with their health status.

**Managing connectors includes:**

* **Connectors Health**: Displays the current status of each connector using a **green** icon for active connections and a **red** icon for inactive connections, helping to monitor the connectivity with data sources.
* **Viewing**: Click the **Eye icon** next to the connector name to view connector details, including databases, tables, columns, and codes.

**Nine Dots Menu Options:**

To view, edit, validate, configure, or delete connectors, click on the **Nine Dots** menu.

* **Edit Connector**: Update and revalidate the data source.
* **Validate Connector**: Check the connection's integrity.
* **Settings**: Modify connector settings.
  * **Crawler**: Configure data extraction.
  * **Access Instructions:** Add notes on how to access the data.
  * **Business Glossary Settings**: Manage term associations at the connector level.
* **Delete Connector**: Remove a connector with confirmation.

For more details on connector settings, click [here](https://docs.ovaledge.com/connectors/introduction-to-connectors/setup-and-connectivity/connector-settings).

## Limitations

<table><thead><tr><th width="92.666748046875">S.No.</th><th>Limitation</th></tr></thead><tbody><tr><td>1</td><td>For File-based connectors, the folder count in the File Manager and Data Catalog Files module may not match if folders or files are added or deleted in the source system after crawling. Run the connection crawl again to refresh and display the latest changes.</td></tr></tbody></table>

## Troubleshooting

If incorrect parameters are entered, error messages may appear. Ensure all inputs are accurate to resolve these issues. If issues persist, contact the assigned support team.

{% tabs %}
{% tab title="Connectivity" %}

<table data-search="true"><thead><tr><th width="60.2265625">S. No</th><th width="180.34765625">Error Message</th><th>Error Description &#x26; Resolution</th></tr></thead><tbody><tr><td>1</td><td>Error while validating connection: connection API returns 400 error</td><td><p>This error typically indicates that the client ID or client secret provided is invalid or does not match the application created in the developer console.</p><p><strong>Resolution</strong>:</p><ul><li>Confirm that the client ID and client secret entered are valid and copied correctly from the application.</li><li>Confirm the user ID entered matches the intended account.</li><li>Retry validation once the credentials are corrected.</li></ul></td></tr><tr><td>2</td><td>Connection validates but profiling or data preview fails</td><td><p>The application used for authentication has only been granted read permission, whereas profiling and data preview require write permission on the application.</p><p><strong>Resolution</strong>:</p><ul><li>Confirm whether the application in use has read-only or read and write permissions configured.</li><li>Update the application permissions to include write access if profiling or data preview is required.</li><li>Revalidate the connection once the required permission has been granted.</li></ul></td></tr></tbody></table>
{% endtab %}

{% tab title="Crawling" %}

<table data-search="true"><thead><tr><th width="62.0625">S. No</th><th width="179.53515625">Error Message</th><th>Error Description &#x26; Resolution</th></tr></thead><tbody><tr><td>1</td><td>Only first-level files and folders appear after crawling</td><td><p>The standard crawl and profile job only captures the first level of files and folders by default, without automatically traversing deeper into the folder structure.</p><p><strong>Resolution</strong>:</p><p>• Use the file manager to open the relevant folder and view its contents directly.</p><p>• Use the catalog options in the file manager, such as catalog all subfolders or catalog all files, and specify the required folder level to reach deeper content.</p><p>• Recrawl or catalog the specific inner folder if content beyond the first level needs to be included.</p></td></tr><tr><td>2</td><td>Files removed from the source still appear in the catalog</td><td><p>The connector does not automatically detect or remove files that have been deleted from the source system, so the catalog remains out of sync until a new crawl is run.</p><p><strong>Resolution</strong>:</p><p>• Recrawl the connector to synchronize the catalog with the current state of the source.</p><p>• Confirm the removed file no longer appears after the recrawl completes.</p><p>• Repeat this recrawl step periodically if source content is expected to change frequently.</p></td></tr><tr><td>3</td><td>Certain file extensions do not appear in the catalog after crawling</td><td><p>Only file extensions included in the configured list of cataloguable types in the system settings are picked up during crawling.</p><p><strong>Resolution</strong>:</p><p>• Open the connector system settings and review the configured list of file types to be catalogued.</p><p>• Add the required file extension to the list if it is missing.</p><p>• Recrawl the connector once the extension has been added.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="Profiling" %}

<table data-search="true"><thead><tr><th width="60.42578125">S. No</th><th width="169.45703125">Error Message</th><th width="483.05859375">Error Description &#x26; Resolution</th></tr></thead><tbody><tr><td>1</td><td>File is catalogued but cannot be profiled</td><td><p>Profiling depends on the file having a structured, column-based format, so certain file types such as images, videos, or unstructured documents cannot be profiled regardless of configuration.</p><p><strong>Resolution</strong>:</p><p>• Confirm the file type is one of the specific types currently supported for profiling, rather than only cataloguing.</p><p>• Recognize that unstructured file types, such as images or videos, are not expected to support profiling.</p><p>• Refer to the connector documentation for the current list of profiling-supported extensions.</p></td></tr><tr><td>2</td><td>CSV file does not display data correctly during profiling</td><td><p>CSV files with inconsistent structure, such as embedded newlines or improperly placed quotes, are not supported and can prevent correct data extraction during profiling.</p><p><strong>Resolution</strong>:</p><p>• Confirm the CSV file follows the documented formatting guidelines, without embedded newlines or misplaced quotes.</p><p>• Correct the file structure to match the required CSV format before recataloguing.</p><p>• Reprofile the file once the structure has been corrected.</p></td></tr><tr><td>3</td><td>Sub sheets within an Excel file do not appear as separate cataloged items</td><td><p>Only the main Excel file is catalogued as a single item, while individual sub-sheets within it are not catalogued separately.</p><p><strong>Resolution</strong>:</p><p>• Confirm this is expected behaviour, since sub-sheets are treated as part of the main file rather than as individual catalog entries.</p><p>• Profile the main Excel file to access the content of its individual sheets.</p><p>• Note that all sheets within the file remain accessible through profiling even though they are not listed as separate catalog items.</p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## FAQs

{% tabs %}
{% tab title="Authentication" %}

<table data-search="true"><thead><tr><th width="58.8828125">S. No</th><th width="202.91015625">Question</th><th>Answer</th></tr></thead><tbody><tr><td>1</td><td>What access is needed before setting up the Box connector?</td><td><p>The following access is required:</p><ul><li>Access to create applications in the Box account</li><li>Access to the Box developer console</li><li>Box admin access</li><li>Access to configure the connector</li></ul><p>Create an application in the developer console to generate the client ID, client secret, and user ID required for the connection.</p></td></tr><tr><td>2</td><td>What is the difference between read and write permission on the Box application?</td><td><ul><li>Read permission: Required to crawl and catalog files and folders and discover their structure.</li><li>Write permission: Required to view data and profile files because these operations read the actual file content.</li></ul><p>With only read permission, files can be catalogued but their content cannot be previewed or profiled.</p></td></tr><tr><td>3</td><td>Which credential managers are supported for storing Box connector credentials?</td><td><p>The Box connector supports the standard credential managers:</p><ul><li>OE Database</li><li>HashiCorp</li><li>AWS secret manager</li><li>Azure key vault</li></ul></td></tr></tbody></table>
{% endtab %}

{% tab title="Crawling" %}

<table data-search="true"><thead><tr><th width="58.8828125">S. No</th><th width="202.91015625">Question</th><th>Answer</th></tr></thead><tbody><tr><td>1</td><td>Does crawling automatically reach every folder level?</td><td><p>No. The standard crawl and profile job reaches only the first level of files and folders.</p><p>To catalog deeper folder levels, use the file manager and specify the required folder level. This allows subfolders and files up to the selected level to be included.</p></td></tr><tr><td>2</td><td>Does this connector support delta crawling?</td><td><p>No. Delta crawling is not supported for the Box connector.</p><p>Each crawl processes the currently selected files and folders instead of automatically identifying only changed content.</p></td></tr><tr><td>3</td><td>What happens if a file is deleted from Box after it has been catalogued?</td><td><p>The catalog does not automatically detect or remove deleted files.</p><p>The deleted file continues to appear in the catalog until the source is crawled again. A new crawl synchronizes the catalog with the current source and removes the deleted file.</p></td></tr><tr><td>4</td><td>Can specific file types be added to or removed from what gets catalogued?</td><td><p>Yes. The list of file extensions eligible for cataloguing can be configured through system settings.</p><ul><li>Add an extension to include that file type in future crawls.</li><li>Only file extensions included in the configured list are catalogued.</li></ul></td></tr><tr><td>5</td><td>Can an entire folder be downloaded through the connector?</td><td><p>No. Downloading an entire folder is not supported.</p><p>The number and size of objects in a folder are not known in advance. Individual files can be downloaded where the connector supports the operation, but folder-level downloads are not available.</p></td></tr></tbody></table>
{% endtab %}

{% tab title="Profiling" %}

<table data-search="true"><thead><tr><th width="58.78515625">S. No</th><th width="180.41015625">Question</th><th width="485.0625">Answer</th></tr></thead><tbody><tr><td>1</td><td>Why is profiling limited to a sample of rows by default?</td><td><p>By default, profiling uses a sample size of 10,000 rows.</p><p>This helps avoid performance issues when processing large files. Full profiling can be enabled through the dedicated setting to process the complete file instead of the default sample.</p></td></tr><tr><td>2</td><td>Can the number of rows shown in the data preview be adjusted?</td><td><p>Yes. The number of rows displayed in the file data preview can be configured.</p><p>For example, you can select 100, 1,000, or 5,000 rows, depending on the required preview size.</p></td></tr><tr><td>3</td><td>Why are only certain file types supported for profiling?</td><td><p>Cataloguing only requires the connector to identify the file and capture its basic details, so more file types can be catalogued.</p><p>Profiling requires the connector to read and interpret the file content in a structured, column-based format. Therefore, only supported file types can be profiled.</p><p>Unstructured file types, such as images and videos, cannot be profiled.</p></td></tr><tr><td>4</td><td>Why do columns not appear immediately after a file is catalogued?</td><td><p>Column information is available only after the file is profiled.</p><ul><li>Cataloguing captures the file and its basic details.</li><li>Profiling reads the file content and identifies its structure, including individual columns.</li></ul></td></tr></tbody></table>
{% endtab %}

{% tab title="Lineage" %}

<table data-search="true"><thead><tr><th width="59.625">S. No</th><th width="188.765625">Question</th><th>Answer</th></tr></thead><tbody><tr><td>1</td><td>Is automatic lineage supported for the Box connector?</td><td><p>No. Automatic lineage is not supported for the Box connector.</p><p>Manual lineage is supported, allowing a file to be manually linked to a lineage flow, including files referenced by name in another ETL tool or platform such as Power BI.</p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

Copyright © 2026, OvalEdge LLC, Peachtree Corners, GA, USA.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ovaledge.com/release7.2/connectors/connector-repositories/file-connectors/box.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.