Platform: Box source connector (#496)

Paul-Cornell · web-flow · commit e31999fba29d · 2025-02-27T11:22:19.000-08:00
diff --git a/mint.json b/mint.json
@@ -192,6 +192,7 @@
               "pages": [
                 "platform/sources/overview",
                 "platform/sources/azure-blob-storage",
+                "platform/sources/box",
                 "platform/sources/confluence",
                 "platform/sources/couchbase",
                 "platform/sources/databricks-volumes",
@@ -277,6 +278,7 @@
             "pages": [
               "platform-api/api/sources/overview",
               "platform-api/api/sources/azure-blob-storage",
+              "platform-api/api/sources/box",
               "platform-api/api/sources/confluence",
               "platform-api/api/sources/couchbase",
               "platform-api/api/sources/databricks-volumes",
diff --git a/platform-api/api/sources/box.mdx b/platform-api/api/sources/box.mdx
@@ -0,0 +1,32 @@
+---
+title: Box
+---
+
+Ingest your files into Unstructured from Box.
+
+The requirements are as follows.
+
+import BoxPrerequisites from '/snippets/general-shared-text/box.mdx';
+
+<BoxPrerequisites />
+
+To create or change an Box source connector, see the following examples.
+
+import BoxSDK from '/snippets/source_connectors/box_sdk.mdx';
+import BoxAPIRESTCreate from '/snippets/source_connectors/box_rest_create.mdx';
+import BoxAPIRESTChange from '/snippets/source_connectors/box_rest_change.mdx';
+
+<CodeGroup>
+    <BoxSDK />
+    <BoxAPIRESTCreate />
+    <BoxAPIRESTChange />
+</CodeGroup>
+
+Replace the preceding placeholders as follows:
+
+import BoxAPIPlaceholders from '/snippets/general-shared-text/box-api-placeholders.mdx';
+
+<BoxAPIPlaceholders />
+
+To change a connector, replace `<connector-id>` with the source connector's unique ID. 
+To get this ID, see [List source connectors](/platform/api/overview#list-source-connectors).
diff --git a/platform-api/api/sources/overview.mdx b/platform-api/api/sources/overview.mdx
@@ -19,6 +19,7 @@ To create or update a source connector, you must also provide settings that are
 For the list of specific settings, see:
 
 - [Azure](/platform/api/sources/azure-blob-storage) (`azure`)
+- [Box](/platform/api/sources/box) (`box`)
 - [Confluence](/platform/api/sources/confluence) (`confluence`)
 - [Couchbase](/platform/api/sources/couchbase) (`couchbase`)
 - [Databricks Volumes](/platform/api/sources/databricks-volumes) (`databricks_volumes`)
diff --git a/platform/connectors.mdx b/platform/connectors.mdx
@@ -12,6 +12,7 @@ The Unstructured Platform supports connecting to the following source and destin
 ## Sources
 
 - [Azure](/platform/sources/azure-blob-storage)
+- [Box](/platform/sources/box)
 - [Confluence](/platform/sources/confluence)
 - [Couchbase](/platform/sources/couchbase)
 - [Databricks Volumes](/platform/sources/databricks-volumes)
diff --git a/platform/sources/box.mdx b/platform/sources/box.mdx
@@ -0,0 +1,26 @@
+---
+title: Box
+---
+
+Ingest your files into Unstructured from Box.
+
+The requirements are as follows. 
+
+import BoxPrerequisites from '/snippets/general-shared-text/box.mdx';
+
+<BoxPrerequisites />
+
+To create the source connector:
+
+1. On the sidebar, click **Connectors**.
+2. Click **Sources**.
+3. Cick **New** or **Create Connector**.
+4. Give the connector some unique **Name**.
+5. In the **Provider** area, click **Box**.
+6. Click **Continue**. 
+7. Follow the on-screen instructions to fill in the fields as described later on this page.
+8. Click **Save and Test**.
+
+import BoxFields from '/snippets/general-shared-text/box-platform.mdx';
+
+<BoxFields />
diff --git a/platform/sources/overview.mdx b/platform/sources/overview.mdx
@@ -19,6 +19,7 @@ To create a source connector:
 7. Fill in the fields according to your connector type. To learn how, click your connector type in the following list:
 
    - [Azure](/platform/sources/azure-blob-storage)
+   - [Box](/platform/sources/box)
    - [Confluence](/platform/sources/confluence)
    - [Couchbase](/platform/sources/couchbase)
    - [Databricks Volumes](/platform/sources/databricks-volumes)
diff --git a/snippets/general-shared-text/box-api-placeholders.mdx b/snippets/general-shared-text/box-api-placeholders.mdx
@@ -0,0 +1,4 @@
+- `<name>` (_required_): A unique name for this connector.
+- `<remote-url>` (_required_): The URL to the target Box folder. This URL must take the format `box://<path/to/folder/in/account>`.
+- For `recursive`, set to `true` to recursively access files from subfolders within the taget Box folder. The default is `false` if not otherwise specified.
+- `<box-app-config>` (_required_): The contents of the private key configuration JSON file for the Box Custom App with access to the target Box folder. This file's contents must be provided as a single string.
diff --git a/snippets/general-shared-text/box-cli-api.mdx b/snippets/general-shared-text/box-cli-api.mdx
@@ -12,4 +12,5 @@ The following environment variables:
 
 - `BOX_APP_CONFIG` - The local path to the downloaded private key configuration JSON file for the Box Custom App, 
    or a single-line string that contains the contents of this file, represented by `--box-app-config` (CLI) or `box_app_config` (Python).
-- `BOX_REMOTE_URL` - The remote URL to the target folder, represented by `--remote-url` (CLI) or `remote_url` (Python).
+- `BOX_REMOTE_URL` - The remote URL to the target folder, represented by `--remote-url` (CLI) or `remote_url` (Python). 
+   This URL must take the format `box://<path/to/folder/in/account>`.
diff --git a/snippets/general-shared-text/box-platform.mdx b/snippets/general-shared-text/box-platform.mdx
@@ -0,0 +1,6 @@
+Fill in the following fields:
+
+- **Name** (_required_): A unique name for this connector.
+- **Data URL** (_required_): The URL to the target Box folder. This URL must take the format `box://<path/to/folder/in/account>`.
+- **Recursive**: Check this box to recursively access files from subfolders within the taget Box folder. This box is unchecked by default.
+- **Config** (_required_): The contents of the private key configuration JSON file for the Box Custom App with access to the target Box folder. This file's contents must be provided as a single string.
diff --git a/snippets/general-shared-text/box.mdx b/snippets/general-shared-text/box.mdx
@@ -1,3 +1,13 @@
+<iframe
+width="560"
+height="315"
+src="https://www.youtube.com/embed/Gkniu1sfz1o"
+title="YouTube video player"
+frameborder="0"
+allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+allowfullscreen
+></iframe>
+
 1. Access to the [Developer Console](https://app.box.com/developers/console) from your [Box enterprise account](https://account.box.com/signup/enterprise-plan) or [Box developer account](https://account.box.com/signup/developer).
 
 2. A Box Custom App in your Box account, set up to use **Server Authentication (with JWT)**. See [Setup with JWT](https://developer.box.com/guides/authentication/jwt/jwt-setup/).
diff --git a/snippets/source_connectors/box_rest_change.mdx b/snippets/source_connectors/box_rest_change.mdx
@@ -0,0 +1,15 @@
+```bash REST (Change)
+curl --request 'PUT' --location \
+"$UNSTRUCTURED_API_URL/sources/<connector-id>" \
+--header 'accept: application/json' \
+--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
+--header 'content-type: application/json' \
+--data \
+'{
+    "config": {
+        "remote_url": "<remote-url>",
+        "recursive": <true|false>,
+        "box_app_config": "<box-app-config>" 
+    }
+}'
+```
diff --git a/snippets/source_connectors/box_rest_create.mdx b/snippets/source_connectors/box_rest_create.mdx
@@ -0,0 +1,17 @@
+```bash REST (Create)
+curl --request 'POST' --location \
+"$UNSTRUCTURED_API_URL/sources" \
+--header 'accept: application/json' \
+--header "unstructured-api-key: $UNSTRUCTURED_API_KEY" \
+--header 'content-type: application/json' \
+--data \
+'{
+    "name": "<name>",
+    "type": "box",
+    "config": {
+        "remote_url": "<remote-url>",
+        "recursive": <true|false>,
+        "box_app_config": "<box-app-config>"
+    }
+}'
+```
diff --git a/snippets/source_connectors/box_sdk.mdx b/snippets/source_connectors/box_sdk.mdx
@@ -0,0 +1,14 @@
+```python Python SDK
+# ...
+from unstructured_client.models.shared import <Create|Update>SourceConnector
+# ...
+source_connector = <Create|Update>SourceConnector(
+    name="<name>", # Create only.
+    type="box", # Create only.
+    config={
+        "remote_url": "<remote-url>",
+        "recursive": "<true|false>",
+        "box_app_config": "<box-app-config>"
+    }
+)
+```
