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

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

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

When using the Moveworks Partner application, we expect the refresh token to be configured in the Moveworks connector.

This can be generated by completing the following steps in Postman (API testing tool). You can search for postman directly in browser and download the tool, postman can also be used directly within the browser. You will need to create a account for it.

1. Click a “New” button and create a new HTTP request
   
2. Go to the Authorization tab and select the authentication type as OAuth 2.0. The grant type must be authorization code. Set the following values in the fields accordingly

   Auth URL = https://account.box.com/api/oauth2/authorize
   Access Token URL = https://api.box.com/oauth2/token
   Client ID = 4gjixwt10e2hpve9o0v2erfn4ynzruud
   Client Secret = ******************

3. Once done you will need click on the “Get New Access Token” button. This will redirect you to your browser to complete the OAuth2 flow and redirect back to postman to show the generated access token and refresh token URL. Copy the refresh token and keep it in a secured manner

This refresh token needs to be now entered into the Moveworks BOX connector as credential. This allows Moveworks to generate the Access token and ingest your documents.

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.
   5. “Manage enterprise properties”
      1. Manage enterprise properties enables us to crawl recent enterprise logs activity to ingest newly created/modified data

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 > Search > Configure Search > Max Capacity
3. Click on Create New or Get Started
4. Select Box (Next Gen) from the dropdown list and click on Get Started
5. You will be redirected to the Box 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 Box 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 Indexed Content > Files and Indexed Content > Internal Knowledge screens.