File Search Box Configuration

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 Serve 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 copy the Share Link of your desired Box Folders, formatted as such:

(Optional) Send credentials to your Customer Success partners

If you do not yet have access to Moveworks Setup to Self-Serve your File Search ingestions, please forward the following information to your Customer Success partners:

  1. Your saved credentials: Enterprise ID, Client ID, and Client Secret
  2. The URLs of the folders for which you have shared access and wish to ingest

Your Customer Success partners can configure the rest of your setup for you afterwards.

2. Create Connector in Moveworks Setup (Coming Soon)

Coming soon, you will be able to self-serve your File Ingestions via Moveworks Setup. Until then, your Customer Success team will configure your File Ingestions, using the credentials you provided in previous steps.Alternatively, if you have access to Moveworks Setup, you can also Self-Serve

If you have not created a Box connector with the Enterprise ID, Client ID, and Client Secret that you have saved for the Application we just created, you will now create a Connector for ingesting Files from your Box folders:

  1. Log into your Moveworks Self-Serve Admin Portal.
  2. Go to the System Connectors Tab.
  3. Select Create New.
  4. Select Box.
  5. Input a Connection Name, Enterprise ID, Client ID, and Client Secret.
  6. Hit Save.

3. (Self-Serve Path) Configure File Ingestion Steps in Moveworks Setup

You can now configure your File Ingestion using the Connector you’ve created!

  1. Navigate to the Enterprise Search → Answers → File Ingestion.
  2. Select the Box Connector and provide a Name your File ingestion config.
  3. Continue to the Ingestion Details page and Specify each Folder, using the Folder IDs.
    1. Please double check that each Folder has been shared access with the Custom App that you have built for Moveworks.
    2. Please double check that you have entered each Folder ID correctly.
      1. For example, if the Share link for your Box folder is: https://<>.app.box.com/folder/123, input 123 into the Start Folder IDs field.
    3. You can assign a Domain to each Folder, i.e IT, HR, Finance, etc.– this Domain is used for tagging in Analytics, enabling you to filter Search usage for each of your domains.
    4. Save the File Ingestions.

4. Launch File Search to your employees (if not already)

  1. Refer back to the main File Search Self-Serve guide: File Search Self-Serve Configuration.