Set up the Openflow Connector for Box¶

Import the connector definition into Openflow¶

1. Download the connector definition file.

2. Import the connector definition into Openflow:

   1. Open the Snowflake Openflow canvas.

   2. Add a process group. To do this, drag the Process Group icon from the tool palette at the top of the page onto the canvas. Once you drop the icon, a Create Process Group pop-up appears.

   3. On the Create Process Group pop-up, select the connector definition file to import.

Configure the connector¶

1. Right-click on the imported process group and select Parameters.

2. Enter the required parameter values as described in Flow parameters: Ingest files only.

Run the flow¶

1. Right-click on the plane and select Enable all Controller Services.

2. Right-click on the imported process group and select Start. The connector starts the data ingestion.

After starting the connector, it retrieves all files from the specified folder, and then consumes admin_logs_streaming events within the last 14 days. This is done to capture data that may otherwise have been missed during the initialization process. During that time, not found errors may occur, which are caused by files that appear in the events but are no longer present.

Import the connector definition into Openflow¶

1. Download the connector definition files:

   1. Download this connector definition file to set up and run the connector. This flow fetches data from Box, runs parsing and chunking processes, updates the Cortex Search service.

   2. Download this connector definition file to manage the connector. This file can be used to toggle Cortex Search service indexing and to clean up the connector state.

2. Import the connector definition into Openflow:

   1. Open the Snowflake Openflow canvas.

   2. Add a process group. To do this, drag and drop the Process Group icon from the tool palette at the top of the page onto the canvas. Once you release your pointer, a Create Process Group pop-up appears.

   3. On the Create Process Group pop-up, select the connector definition file to import.

Configure the connector¶

1. Right-click on the imported process group and select Parameters.

2. Populate the required parameter values as described in Flow parameters: Ingest files and perform processing with Cortex.

Run the flow¶

1. Right-click on the plane and select Enable all Controller Services.

2. Right-click on the imported process group and select Start. The connector starts the data ingestion.

After starting the connector, it retrieves all files from the specified folder, and then consumes admin_logs_streaming events within the last 14 days. This is done to capture any data that may have been missed during the initialization process. During that time, not found errors may occur, caused by the files that appear in the events but are no longer present.

Query the Cortex Search service¶

You can use the Cortex Search service to build chat and search applications to chat with or query your documents in Box.

After you install and configure the connector and it begins ingesting content from Box, you can query the Cortex Search service. For more information about using Cortex Search, see Query a Cortex Search service.

Filter responses

To restrict responses from the Cortex Search service to documents that a specific user has access to in Box, you can specify a filter containing the user ID or email address of the user when you query Cortex Search. For example, filter.@contains.user_ids or filter.@contains.user_emails. The name of the Cortex Search service created by the connector is search_service in the schema Cortex.

Run the following SQL code in a SQL worksheet to query the Cortex Search service with files ingested from your Box site.

Replace the following:

• application_instance_name: Name of your database and connector application instance.

• user_emailID: Email ID of the user who you want to filter the responses for.

• your_question: The question that you want to get responses for.

• number_of_results: Maximum number of results to return in the response. The maximum value is 1,000 and the default value is 10.

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    '<application_instance_name>.cortex.search_service',
      '{
        "query": "<your_question>",
         "columns": ["chunk", "web_url"],
         "filter": {"@contains": {"user_emails": "<user_emailID>"} },
         "limit": <number_of_results>
       }'
   )
)['results'] AS results

Here is a complete list of values that you can enter for columns:

Example: Query an AI assistant for human resources (HR) information

You can use Cortex Search to query an AI assistant for employees to chat with the latest versions of HR information, such as onboarding, code of conduct, team processes, and organization policies. Using response filters, you can also allow HR team members to query employee contracts while adhering to access controls configured in Box.

SELECT PARSE_JSON(
     SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
          '<application_instance_name>.cortex.search_service',
          '{
             "query": "What is my vacation carryover policy?",
             "columns": ["chunk", "web_url"],
             "filter": {"@contains": {"user_emails": "<user_emailID>"} },
             "limit": 1
          }'
     )
 )['results'] AS results

import snowflake.snowpark as snowpark
from snowflake.snowpark import Session
from snowflake.core import Root

def main(session: snowpark.Session):

   root = Root(session)

   # fetch service
   my_service = (root
     .databases["<application_instance_name>"]
     .schemas["cortex"]
     .cortex_search_services["search_service"]
   )

   # query service
   resp = my_service.search(
     query="What is my vacation carryover policy?",
     columns = ["chunk", "web_url"],
     filter = {"@contains": {"user_emails": "<user_emailID>"} },
     limit=1
   )
   return (resp.to_json())

curl --location "https://<account_url>/api/v2/databases/<application_instance_name>/schemas/cortex/cortex-search-services/search_service" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer <CORTEX_SEARCH_JWT>" \
     --data '{
         "query": "What is my vacation carryover policy?",
         "columns": ["chunk", "web_url"],
         "limit": 1
     }'

{
  "results" : [ {
  "web_url" : "https://<domain>.box.com/sites/<site_name>/<path_to_file>",
  "chunk" : "Answer to the question asked."
  } ]
}

Create a Snowflake table for storing the Box metadata¶

1. Ensure that Box AI is enabled for the extraction of metadata to occur. For more information, see Configuring Box AI.

2. Create a Snowflake table where the metadata will be sent

   For the connector to know what kind of metadata to extract, you must create a Snowflake table in your database and schema with the column names of the fields you would like to extract. Add descriptions to each column to improve the performance of the model used to extract the metadata from the files.

3. In the table created in the previous step, ensure that there is a column to store the Box file ID and that it is of type VARCHAR.

   The name of this column is required to be entered as the Box File Identifier Column parameter in later steps. The list of supported columns types for the metadata table is VARCHAR, STRING, TEXT, FLOAT, DOUBLE, and DATE.

Here is an example of the table that you can create for this connector:

CREATE OR REPLACE TABLE OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA (
  BOX_FILE_ID               VARCHAR    COMMENT 'Box file identifier column',
  LOAN_ID                   STRING     COMMENT 'Unique loan agreement identifier (e.g. L-2025-0001)',
  BORROWER_NAME             STRING     COMMENT 'Name of the borrower entity or individual',
  LENDER_NAME               STRING     COMMENT 'Name of the lending institution',
  LOAN_AMOUNT               DOUBLE     COMMENT 'Principal amount of the loan (in USD)',
  INTEREST_RATE             FLOAT      COMMENT 'Annual interest rate (%)',
  EFFECTIVE_DATE            DATE       COMMENT 'Date on which the loan becomes effective',
  MATURITY_DATE             DATE       COMMENT 'Scheduled loan maturity date',
  LOAN_TERM_MONTHS          FLOAT      COMMENT 'Original term length in months',
  COLLATERAL_DESCRIPTION    TEXT       COMMENT 'Description of collateral securing the loan',
  CREDIT_SCORE              FLOAT      COMMENT 'Borrower credit score',
  JURISDICTION              STRING     COMMENT 'Governing law jurisdiction (e.g. NY, CA)'
);

Import the connector definition into Openflow¶

1. Download the connector definition file to set up and run the connector.

   This flow extracts metadata from each Box file, processes them, and uploads the metadata to a Snowflake table. When additional files are uploaded or existing files are changed, the metadata is extracted again and the table is updated. The connector handles file deletions too and their metadata is removed from the table.

2. Import the connector definition into Openflow:

   1. Open the Snowflake Openflow canvas.

   2. Add a process group. To do this, drag and drop the Process Group icon from the tool palette at the top of the page onto the canvas. Once you release your pointer, a Create Process Group pop-up appears.

   3. Select the connector definition file to import.

Configure the connector¶

1. Right-click on the imported process group and select Parameters.

2. Populate the required parameter values as described in Flow parameters: Extract Box metadata using Box AI and ingest it into a Snowflake table.

Run the flow¶

1. Right-click on the plane and select Enable all Controller Services.

2. Right-click on the imported process group and select Start. The connector starts the data ingestion.

After starting the connector, it retrieves all files from the specified folder, and then consumes admin_logs_streaming events from the last 14 days. This is done to capture any data that may have been missed during the initialization process. During that time, not found errors may occur, caused by the files that appear in the events but are no longer present.

Create a Snowflake stream for storing the Box metadata¶

1. Create a Snowflake stream for the metadata table you want to use. The stream is used to monitor any changes that occur to the table with which you want to synchronize your Box files. To learn how to create a table for storing Box metadata, see Create a Snowflake table for storing the Box metadata. If the connector is stopped beyond the data retention time and the stream becomes stale, then you must recreate a stream and replace the previous one. To learn more about managing streams, see Managing Streams.

   Here is an example of a stream that you can create for this connector:

   CREATE OR REPLACE STREAM OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA_STREAM
   ON TABLE OPENFLOW.BOX_METADATA_SCHEMA.LOAN_AGREEMENT_METADATA
   

   Copy

2. In the metadata table, ensure that there is a column to store the Box file ID and that it is of type VARCHAR.

   The name of this column is required to be entered as the Box File Identifier Column parameter in later steps. The list of supported columns types for the metadata table is VARCHAR, STRING, TEXT, FLOAT, DOUBLE, and DATE.

Import the connector definition into Openflow¶

1. Download the connector definition file for setting up and running the connector.

   This flow takes an initial snapshot of your Snowflake table for which the stream is set up and then any subsequent changes to your table are automatically ingested. The changes are processed and the metadata is added to the associated Box file in a metadata template dedicated to this connector.

2. Import the connector definition into Openflow:

   1. Open the Snowflake Openflow canvas.

   2. Add a process group. To do this, drag and drop the Process Group icon from the tool palette at the top of the page onto the canvas. Once you release your pointer, a Create Process Group pop-up appears.

   3. Select the connector definition file to import.

Configure the connector¶

1. Right-click on the imported process group and select Parameters.

2. Populate the required parameter values as described in Flow parameters: Synchronize Box file metadata instances with a Snowflake table.

Run the flow¶

1. Right-click on the plane and select Enable all Controller Services.

2. Right-click on the imported process group and select Start. The connector starts the data ingestion.

After running the flow, you can query the Cortex Search service. For information on how to query the Cortex Search service, see Query the Cortex Search service.