Connecting Box

Before connecting Box, you must configure Box. Complete the following steps only once per Workplace Search deployment:

Step 1. Log in to your Box developer console, where you will register your Workplace Search deployment as an OAuth application within the Box ecosystem.

Navigate to the following URL, substituting <BOX_BASE_URL> with the base URL at which your Box service is hosted (scheme + host, no path).

<BOX_BASE_URL>/developers/console

For example:

https://acme.app.box.com/developers/console

Log in to Box with the account that should own the OAuth application. This account must have permission to create an OAuth application through the Box UI. Choose an account to which you won’t lose access, such as a team-owned account.

Step 2. Create a new Box app.

From the developer console, choose Create New App.

From the Create New App screen, choose Custom App:

which opens the Custom App form.

Step 3. Complete the custom app form.

Within Authentication Method, choose User Authentication (OAuth 2.0).

Within App Name, enter a name, such as "Elastic Workplace Search" or "Workplace Search Your Org Name". Box will display this name later, when asking permission to connect to Workplace Search.

Choose Create App to save the app, after which you arrive at the app’s configuration screen.

Step 4. Configure the app.

Within OAuth 2.0 Redirect URI, enter the redirect URL for your Workplace Search installation.

Your redirect URL is affected by which user interface you are using to manage Enterprise Search. Enterprise Search in Kibana and standalone Enterprise Search use different redirect URLs. See user interfaces for details on each UI.

For standalone Enterprise Search, enter the following, substituting <WS_BASE_URL> with the base URL at which Workplace Search is hosted (scheme + host, no path).

<WS_BASE_URL>/ws/org/sources/box/create

Examples:

# Deployment using a custom domain name
https://www.example.com/ws/org/sources/box/create

# Deployment using a default Elastic Cloud domain name
https://c3397e558e404195a982cb68e84fbb42.ent-search.us-east-1.aws.found.io:443/ws/org/sources/box/create

# Unsecured local development environment
http://localhost:3002/ws/org/sources/box/create

For Enterprise Search in Kibana, enter the following, substituting <KIBANA_BASE_URL> with the base URL of your Kibana instance. This should correspond with the value of kibana.external_url in your enterprise-search.yml:

<KIBANA_BASE_URL>/app/enterprise_search/workplace_search/sources/added

Examples:

# Deployment using a custom domain name for Kibana
https://www.example.com/app/enterprise_search/workplace_search/sources/added

# Deployment using a default Elastic Cloud domain name for Kibana
https://c3397e558e404195a982cb68e84fbb42.kb.us-east-1.aws.found.io:443/app/enterprise_search/workplace_search/sources/added

# Unsecured local Kibana environment
http://localhost:5601/app/enterprise_search/workplace_search/sources/added

Within Application Scopes, ensure the following scopes are selected:

Choose Save Changes to save the configuration.

Step 5. Copy the client ID and client secret to Workplace Search.

Within the Box application configuration screen, locate the section OAuth 2.0 Credentials.

You need to copy the Client ID and Client Secret to Workplace Search. Either record those values, or keep this page open while you continue.

Navigate to Workplace Search and log in to the administrative dashboard.

Choose Sources, locate Box, and select Configure.

Within Client id and Client secret, enter the corresponding values from the Box developer console.

Choose Save configuration to complete the process.

With Box configured, you’re ready to connect Box accounts to Workplace Search.

After configuring Box, you can connect Box to Workplace Search. Complete the following steps for each Box account you’d like to connect to your Workplace Search deployment:

Step 1. Navigate to Workplace Search and log in to the administrative dashboard.

Choose Sources.

Within Configured content sources, locate Box.

Choose Connect.

Step 2. Complete the authentication flow with Box.

Use the Box account whose data you want to sync to Workplace Search. To support incremental syncs, this account must be a Box admin.

Upon completion, you are redirected back to Workplace Search.

After connecting, Box data begins syncing to Workplace Search. As it syncs, the content is searchable.

After an initial full sync, incremental syncs will run every 2 hours.

You can synchronize document access permissions from Box to Workplace Search. This will ensure the right people see the right documents.

See Document-level permissions for Box.

If you don’t need to index all the available content, you can specify the indexing rules via the API. This will help shorten indexing times and limit the size of the index. See Customizing indexing. For Box, applicable rule types would be path_template and file_extension.

The following table lists the fields synchronized from the connected source to Workplace Search. The attributes in the table apply to the default search application, as follows: