Documentation
DocumentationDeveloperAcademyCommunitySupportLogin
Start typing to search…

Box Setup for Enterprise Search

System Overview

Box is your organization’s secure Content Cloud for managing files, collaborating on documents, and streamlining workflows. It acts as a central repository where teams store everything from strategic plans to technical specifications. Moveworks connects to Box to index the files within your folders—including PDFs, presentations, and spreadsheets—along with their associated metadata and permissions, ensuring that users can instantly locate the specific documents they need while strictly adhering to the access controls you’ve established.

Authentication

Moveworks supports two primary authentication methods for Box: OAuth 2.0 with the Refresh Token grant and Service Accounts with the Client Credentials grant.

Moveworks App with OAuth 2.0 Refresh Token Grant (Recommended) : The OAuth 2.0 refresh token enables the ingestion of both shared and private data for end users. This method utilizes the official Moveworks partner application, which facilitates full indexing of your data.

  1. Setup: A Box Admin or Co-admin installs the Moveworks application from the Box Marketplace and completes the OAuth 2.0 flow to configure the refresh token.
  2. Authorization: This method uses the Box Admin’s access token to authorize the connection with your Box instance.

Custom App with Server Authentication (Service Account)

  1. Setup: A Box Admin creates a new custom application within the Box instance that is tied to a service account.
  2. Authorization: This method uses an access token generated via the Client ID and Client Secret of the custom application to authorize the connection.

Permission enforcement

Moveworks preserves the collaboration permissions applied at the file or folder level within your Box instance. These collaborations are ingested regardless of which authentication method you choose.

Currently, we do not support showcasing files to a user that are accessible through shared links (if the user is not added as a collaborator and only has access via the shareable link). However, if the user is added as a collaborator, they will be able to access the file

🚧

Recommendation: We strongly recommend that the primary Box Admin generates the refresh token or completes the credential setup for the Moveworks application (OAuth 2.0 Refresh Token Grant).

Note: Do not use a Co-admin account for this setup. Co-admins generally cannot access items owned by other Co-admins or the primary Admin. Therefore, if a Co-admin sets up the integration, Moveworks will be unable to crawl or index all expected information.

API usage

  • Standard API: Moveworks uses Box’s standard API for Box to ingest all data

Content types

Moveworks supports the ingestion of files from your Box shared or private folders.

  • Supported file formats: doc, docx, pdf, ppt, txt, html

Moveworks delivers comprehensive data coverage—including metadata, identity data, permissions data, and activity data—and keeps content in sync in real-time, ensuring that updates and permission changes are immediately reflected in search results.

Access Requirements

To set up Enterprise Search, please ensure you have the necessary Box inputs and have completed the prerequisites before proceeding to Moveworks Setup.

Moveworks Partner Application with OAuth2 refresh token grant

📝

BOX Instance level API quota

Every Box instance has an API quota, and any API calls made to your instance consume this quota. However, Box has made special provisions for partner applications deployed on the Box Marketplace—API calls made through these applications do not consume your API quota and are not chargeable.

Moveworks recommends installing the Moveworks partner application when setting up Box within Enterprise Search, as it allows Moveworks to fully index your Box instance without any pricing implications or risk of surpassing the API quota.

👍

Private data ingestion

In Enterprise Search, Moveworks offers private data ingestion. Each end user can authenticate with the Box instance and allow indexing of their data. All files related to an end user are stored in a secure user vault. Private data ingestion within Box can only be supported by using the Moveworks partner application.

The Moveworks partner application is a Moveworks-deployed app available on the Box Marketplace listing screen. A Box Admin must complete the installation to ensure the application is fully set up, enabling Moveworks to connect with Box.

How to install the application ?

  1. Ensure that you are the Box admin for your instance before proceeding with the steps below. If you are not a Box admin, please contact one and ask them to follow these instructions.

  2. Navigate to the Administration Console and go to the Platform Apps Manager section. You will see two options on the screen: Server Authentication Apps and User Authentication Apps. Click on User Authentication Apps. These apps require end users to authenticate with the instance.

  3. Only partner applications deployed on the Box Marketplace that have no pricing implications appear under User Authentication Apps. Click the “+” icon in the top-right corner to install the Moveworks partner application.

  4. You will see an input box where you need to enter the client ID. Enter the following ID to install the application: Client ID: 4gjixwt10e2hpve9o0v2erfn4ynzruud

  5. After submitting the form, a pop-up will appear. Click “Enable” to complete the onboarding of the application. Once this is done, the Moveworks application will be installed in your instance.


Configuration of the Moveworks Setup BOX connector

....

Custom application with server authentication

In case you don't want to enable the BOX private data ingestion or do not want to install the Moveworks application, a custom application can also be created which utilizes the client credentials based OAuth2 authorization in order to connect with your BOX instance.

Follow the below steps for creating the custom application

1. Create Box App and Grant Scopes

Creating an app

  1. Log in to https://cloud.app.box.com/developers/console.

  2. Select Create New App.

  3. Select Custom App.
    The reason for Selecting Custom App is as follows:

    1. Per Box docs, Limited Access Apps can only use a handful of endpoints, which do not include all the endpoints we require.
    2. Per Box docs, Custom Apps provides the flexibility necessary for Moveworks to provide File Search and enforce your source Box permissions.

  4. Name your application under App Name, i.e. “Moveworks”.

  5. In the Description field, select “Integration" (or another field of preference).

  6. Select Next.

  7. Under Purpose, select “Integration” (or another field of preference).

  8. Under Categories, select “Productivity” (or another field of preference).

Select Auth Method, and Create app

  1. Select “Server Authentication (Client Credentials Grant).

    1. The Server Authentication Auth method provides the best and most secure option:

      1. File Search functions via server-side operations to ingest your files and your source file ACL permissions.

      2. Ensuring server to server interactions without exposing user credentials.

      3. Simplifies credential management, as only a single set of credentials (client ID and secret) are used for authentication.

Grant Moveworks the necessary scopes for your App

  1. Go to the Configuration Tab for your App.

  2. Select App + Enterprise Access.

    1. We need App + Enterprise access because we need to be able to ingest all of your organizations’ User profiles – these User profiles are essential for enforcing ACL permissions in our File Search product, and our validations that users can never access files they don’t have access to via File Search.

  3. Continue below on the configuration page, and select the below Application Scopes:

    1. “Read all files and folders stored in Box”
    2. “Write all files and folders stored in Box”
      1. Write file access, like suggested in the screenshot, is required to download files.
    3. “Manage users”
      1. Manage users is to get list of users for identity mapping from Moveworks to Box.
    4. “Manage groups”
      1. Group ingestion is used to enforce permissions when they are granted access to certain internal groups, and allows us to map access to the users within those groups.

Retrieve the Client ID, Client Secret, and Enterprise ID

After this stage, you should have retrieved the Client ID, Client Secret, and Enterprise ID, and forwarded to your representative at Moveworks.

  1. Scroll to the OAuth 2.0 Credentials Section.

    1. Select your Client ID, and and save it for yourself – you’ll need this later.

    2. Select Fetch Client Secret, and and save it for yourself – you’ll need this later.

  2. Go to the General Settings Tab.

    1. Scroll down to Enterprise ID, and save it for yourself – you’ll need this later.

Authorize your App

  1. Review and Submit your app for Authorization, by navigating to the Authorization Tab.

  2. Select Review and Submit.

  3. Accept the request by navigating here: https://app.box.com/master/custom-apps.

    1. In our image below it is “Reauthorize App”, but you should see an option that says “Authorize app” – select Authorize App.

Share Folders with the Authorized App created for Moveworks

  1. Go to your Folders in Box, and open the Share button of your desired Box Folders

  2. Grab the Service Account ID email for the App, which can be found in the General Settings tab for the app you created

Configure Moveworks Setup Connector for BOX custom application

  1. Navigate to the built-in connectors and click on the create new button. Once done search for BOX. Click on the BOX (Next Gen) option.


  2. Click “NEXT: ADD CREDS” and enter the details you captured while creating the connector. Select OAuth2 with Client Credentials Grant as the authentication type.


Configuring BOX for enterprise search

Initialising setup

  1. Log in to your org's MyMoveworks portal

  2. Navigate to Moveworks Setup > Answers > Ingestion > Enterprise Search

  3. Click on Create New or Get Started

  4. Select Service Now from the dropdown list and click on Get Started

  5. You will be redirected to the ServiceNow ingestion overview page. In the overview page, you will find few info blocks and few configuration blocks.

    1. System Overview: This presents an overview of ServiceNow support from Moveworks
    2. Ingestion Summary: This provides information on the count of records that has been ingested and serving. The values will appear after the first successful ingestion run.
    3. Connector Selection: In this configuration block, you are required to select the required connector to enable Moveworks to connect and fetch data
    4. Content Selection: In this configuration block, you are required to define the content that should be ingested within Moveworks

    Connector selection and validation

    1. Once you click on Select Connector, a connector setup screen will appear as follows

    2. Select the connector (from the dropdown) that you have created in the Connector Creation step.

      📘

      Please note: Only the BOX (Next Gen) connectors will appear in this list.

    3. Once the connector is selected, you need to click on Start Validation to validate the connector credentials and required scope.

      📘

      Connector Validation

      This is a mandatory step in order to save the configuration and move to the next step.

      Moveworks validates the selected connector to check:

      • Auth: Moveworks validates if the connector has right credentials to authenticate
      • Content: Moveworks validates if connector has right scopes to fetch content
      • Permissions: Moveworks validates if connector has right scopes to fetch user permissions
      • Users: Moveworks validates if connector has right scopes to fetch user data
      • Groups : Moveworks validates if connector has right scopes to fetch group data

    4. If the connector is validated successfully, you will see a green info banner as follows

      1. If there are any credentials or scope issues, you will receive an error message as follows. Click on View Details to identify the issue. Refer to this step-by-troubleshoot guide (link to be added) to rectify any validation errors.

    5. Once the connector is validated successfully, you will be able to Save the configuration.

      1. Input the unique configuration name and Save.

      2. Once the configuration is saved, you can view the unique configuration name at the top of the screen. You can also click the pencil 🖊️ icon to edit the configuration name.

      3. Additionally, you will start seeing an entry of your configuration in the Enterprise Search home page. You can click on your configuration to go to edit/ complete the configuration.

Content Selection

Once the connector selection step is complete and the configuration is saved, you will now be required to define the scope of content that will be ingested in Moveworks.

  1. Once you click on Select Content, a content selection screen will appear as follows

  2. In this screen, you are required to define the Knowledge Base from which Moveworks will ingest content and apply filters (optionally) to filter down the content further.

  3. Knowledge Base configuration: This is a mandatory configuration. This configuration defines which Knowledge Base Moveworks will crawl and ingest content from. As an admin, you get three option

    1. All folders (Recommended): Moveworks will ingest content from all knowledge base

      📘

      When to choose this option?

    2. Only selected folders : Moveworks will ingest content only from the selected knowledge base

      📘

      When to choose this option?

    3. **All except selected **: Moveworks will ingest all content excluding content from the selected knowledge base

      📘

      When to choose this option?

  4. Additional Filters: Use these filters to narrow the content ingestion scope further. Only records matching ALL of the the specified criteria will be included.

    Currently following filters are supported:

    1. Modified date: Use this filter to include only those content records whose Modified date is after a specified date.
    2. Created date: Use this filter to include only those content records whose Created date is after a specified date.

Save and Start Ingestion

Once Knowledge Base selection is configured, you have two options:

  1. Save: Clicking this will just save the configuration and not initiate the first ingestion crawl. Use this option, if you would want to complete your configuration in multiple sessions/ sittings.

    1. Once you click on Save, you will be redirected to the BOX overview screen

    2. You will notice a banner that prompts you to Start Ingestion

    3. Once you are satisfied with your configuration, you can click on Start Ingestion

    4. A confirmation popup will come that provides a summary of the configuration

    5. Click on Confirm

    6. After you click on Confirm, ingestion will start shortly.

    7. For the first crawl to complete, this generally takes anywhere from few hours to 48 hours depending upon the size of the data.

  2. Save and Start Ingestion: Click this option if you have completed and validated your content selection configuration and you are ready to initiate the first ingestion crawl.

    1. A confirmation popup will come that provides a summary of the configuration

    2. Click on Confirm

    3. After you click on Confirm, ingestion will start shortly.


    📘

    Important Note for Admins:

    • It generally takes anywhere from few hours to 48 hours for the first crawl to complete depending upon the size of the data.
    • You can review the status of ingestion via Data Ingestion Viewer and view ingested record in the Ingested File and Ingested Knowledge screens.




Updated about 6 hours ago