Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Installation and Configuration
Box Connector
Introduction
Using the Box Connector, files and folders from Box can be indexed with their metadata.
Configuring Box
- To index Box, the Box Crawler requires an app and a user with permissions to all Box content to be indexed.
Creating the app
You can create a new app in the Box Dev Console. To do this, click Create New App under My Apps and select Custom App. For Authentication Method, select Server Authentication (Client Credentials Grant) and give the app a name. Then click “Create App” to create the app.
In the Configuration area of the created app you can then view and retrieve the Client ID and the Client Secret. These are needed for the option "OAuth Credential" in the MMC.
Using JWT Server Authentication
For enhanced security, you can also select “Server Authentication (with JWT)” when creating the custom App.
When using “Server Authentication (with JWT)” additionally to all the other steps, you will need to either generate a Public/Private Keypair or upload a public RSA Key. When generating a Keypair, it is important to save the (encrypted) private key as well as the encryption passphrase, since Box won’t store these and you need them for the Mindbreeze InSpire configuration.
Also note down the Client ID and Client Secret, since they are also required for the authentication.
Scopes and Permissions
In addition, the "App Access Level" and "Application Scopes" options must be set in the Configuration area. The Box Crawler requires App + Enterprise Access and the following “Application Scopes”:
- Read all files and folders stored in Box
- Write all files and folders stored in Box (Note: This is required to download file content. See Box API Documentation. Mindbreeze Connector will never modify, delete or upload files)
- Manage users (Note: This is required to download user permissions. See Box API Documentation. Mindbreeze Connector will never modify, delete or create users)
- Manage groups (Note: This is required to download group permissions. See Box API Documentation. Mindbreeze Connector will never modify, delete or create groups)
In addition, the option "Make API calls using the as-user header" must be activated in the "Advanced Features".
Authorizing the App
After that you can click on "Review and Submit" in the Authorization section of the app so that the app can be approved by the admin. The authorization can be done in the Admin Console under the tab Apps -> Custom Apps Manager.
Configuring Mindbreeze
Open the Mindbreeze Management Center in the browser to start configuration.
Index configuration
In the Indices tab, add a new index using the +Add Index button. Select the desired Index Node and Client Service and specify the data source Box in the Data Source field. Then confirm your entries with the Apply button.
Configuring the data source
Now configure the data source.
Legend:
- Properties marked with *: mandatory field, these must be configured explicitly
- Properties not specially marked: optional fields
- Fields marked with (Advanced Settings) are only displayed if the "Advanced Settings" view is enabled in the configuration. This is only necessary in special use cases.
Connection Settings
Enterprise Id* | The Enterprise ID of your Box instance. You can find it in the Box Admin Console under "Account & Billing". Alternatively, you can go to https://www.box.com/master/settings and log in as Enterprise Admin. | ||||||||
Box URL* | The URL of your box instance, e.g. https://myorganization.app.box.com/ | ||||||||
The OAuth 2 credential created in the Network tab.
| |||||||||
A path pointing to a .pem file on the InSpire machine containing the private key needed for JWT authentication.
| |||||||||
The credential type “Password” created in the “Network” tab used to decrypt the private key.
| |||||||||
Page Size | The maximum number of elements that are fetched per API request. If this is increased, fewer requests may need to be made to the API, but it may result in increased memory usage. The maximum number is 1000. | ||||||||
Log All Requests | If enabled, all requests to the Box API are written to a "request-log.csv" file. | ||||||||
Crawler Settings
User Emails* | E-mail addresses of the users whose content is to be indexed. All content to which the specified users have access is indexed. If you want to have precise control over which content is indexed by the crawler, you can create a separate user who can see all the content to be indexed. More on this in the chapter Creating a crawling user. |
Excluded Files/Folders (regex) | If this option is configured, those files and directories that match the specified pattern (Regular Expression) will be ignored. The regex is applied to the full path, e.g. Parentfolder/Childfolder/MyFile.docx Excludes have higher priority than includes (i.e. if a document is both included and excluded, it will not be indexed). |
Maximum File Size (MB) | The maximum size of files (in MB) whose content is to be indexed. If a file exceeds this size, it will be indexed without the file content and only with the metadata. |
Index Only Files | If enabled, folders are not indexed as documents. |
Fetch Custom Metadata | If enabled, the custom metadata is additionally fetched for all files and folders. If you do not use these, you should disable this option to speed up the crawl run. |
Included Files/Folders (regex) | If this option is configured, only those files and directories are indexed which match the specified pattern (Regular Expression). The regex is applied to the full path, e.g. Parentfolder/Childfolder/MyFile.docx If this option is left empty, everything will be included. Excludes have higher priority than includes (i.e. if a document is both included and excluded, it will not be indexed). |
Configuring the principal resolution service
In the new or existing service, select the Box Principal Resolution Service option in the Service setting. For more information about additional configuration options and how to create a cache and how to do the basic configuration of a cache for a Principal Resolution Service, see Installation & Configuration - Caching Principal Resolution Service.
Connection Settings
These configuration options are described in the chapter Crawler Settings.
Appendix
Creating a crawling user
If you want to have precise control over which content is indexed by the crawler, you can create a separate user who can see all the content to be indexed.
A new user can be created in the Admin Console in the menu item Users & Groups.
To give this user access to all folders that are to be indexed, there are two options:
- You add the user directly under "Select folders this user can access" to the desired folders to which he should have access rights.
For this, the corresponding column "Access Level" must be set to "Viewer". - You add the user to the desired groups under "Select groups this user is in:" that have access rights to specific folders.
For this, the corresponding column "Access Level" must be set to "Member".
This user must then also be activated via a login so that it can be used by the Box crawler.
Troubleshooting
Error: Invalid Grant - Current date/time MUST be before the expiration date/time listed in the 'exp' claim
When authenticating against a box app using “Server Authentication (with JWT)” your InSpire machine has to have the current time configured. When you are seeing this error, your machine is likely behind in time. It is best to configure a NTP for this – see the documentation here.