Google Workspace data source

This topic provides details on how to capture Google Chats, Drive, Groups, and emails with Collect. Relativity collects Google Drive data using the Vault API.

Considerations

Note the following considerations about this data source:

  • Unable to collect Google Calendar data from Google Vault due to a Google limitation.

  • No support for modern attachments, or linked files.

  • Google does not have a date range limitation. We recommend limiting the date range of the collection. Extended date ranges can increase collection time and potentially create issues.

Google Workspace account setup

Connecting your Google Workspace to Collect takes some setup in Google and Relativity. Begin with the credential setup in Google.

Creating a Google Cloud project

Create a Google Cloud project to create, enable, and use all Google Cloud services. You will use this account to manage APIs.

To create a Google Cloud project,

  1. Open the Cloud Resource Manager page, click Create Project.

  2. Enter information into the fields:

    • Project name—enter a memorable name for your project.

    • Organization—enter the name of your organization.

    • Location—enter the parent organization or folder.

  3. Click Create.

Enable required APIs for the Project

Continuing in this process, you now need to enable the required Google Cloud Console APIs and associate them to a new project.

To start enabling APIs,

  1. In the Google Cloud Console, select the newly created project.

  2. In the left-navigation menu, select API & Services > Library.


    This will open up the Library page that includes all available APIs.

  3. Enter Google Vault API in the search bar and search.

  4. Click the Google Vault API option.

  5. Click Enable.

  6. In the top left corner, click the Back arrow icon.
    This will take you back to the search results page with the search bar.

  7. Enter Admin SDK API in the search bar and search.

  8. Click the Admin SDK API option.

  9. Click Enable.

  10. In the top left corner, click the Back arrow icon.
    This will take you back to the search results page with the search bar.

  11. Enter Cloud Storage API in the search bar and search.

  12. Click the Cloud Storage API option.

  13. Click Enable.

      Notes: This API may be enabled by default.

Setup OAuth2 consent screen

Follow the steps to create a OAuth2 consent screen.

  1. Open Google Cloud Console and select newly created project.

  2. Click on the Navigation menu.

  3. Select APIs & Services>OAuth consent screen.

  4. Select Internal type.

  5. Click Create.

  6. Enter descriptive App name. For example, Relativity Collect.

  7. Enter a User support email from within your organization.

  8. Enter relativity.one as Authorized Domain.

  9. Enter an email form within your organization in the Developer Contact Information field.

  10. Click Save and Continue.

On the next step, you will want to add scopes.

  1. Click Add or remove scopes.

  2. Enter filter and select required scopes one at a time, or enter them in a text box.
    The scopes are:

    • https://www.googleapis.com/auth/ediscovery

    • https://www.googleapis.com/auth/devstorage.read_only

    • https://www.googleapis.com/auth/admin.directory.user.readonly

    • https://www.googleapis.com/auth/admin.directory.group.readonly

  3. Click Update.

  4. Click Save and Continue.

Create credentials

  1. Click in the top left corner.

  2. Hover over APIs & Services > Credentials.

  3. Click Create Credentials.

  4. Click OAuth Client ID credentials.

  5. Enter the following information in the fields:

    • Application type—select Web application

    • Name—enter a name for the credentials

    • Authorized redirect URIs—enter the URI based on the RelativityOne Data Center Geo you intend to run collections from.

      • Asia (East)—https://services.esas.relativity.one/collect-oauth-authorization/index.html

      • Asia (Southeast)—https://services.seas.relativity.one/collect-oauth-authorization/index.html

      • Australia—https://services.auea.relativity.one/collect-oauth-authorization/index.html

      • Brazil (South)—https://services.brso.relativity.one/collect-oauth-authorization/index.html

      • Canada (Central)—https://services.cact.relativity.one/collect-oauth-authorization/index.html

      • Europe (North)—https://services.noeu.relativity.one/collect-oauth-authorization/index.html

      • Europe (West)—https://services.wseu.relativity.one/collect-oauth-authorization/index.html

      • Germany (West Central)—https://services.dect.relativity.one/collect-oauth-authorization/index.html

      • India (Central)—https://services.inct.relativity.one/collect-oauth-authorization/index.html

      • Japan—https://services.jpes.relativity.one/collect-oauth-authorization/index.html

      • Korea (Central)—https://services.krct.relativity.one/collect-oauth-authorization/index.html

      • Switzerland—https://services.chno.relativity.one/collect-oauth-authorization/index.html

      • United Arab Emirates—https://services.aeno.relativity.one/collect-oauth-authorization/index.html

      • United Kingdom (South)—https://services.ukso.relativity.one/collect-oauth-authorization/index.html

      • United States (Central)—https://services.ctus.relativity.one/collect-oauth-authorization/index.html

      • United States (East)—the United States (East) geo has six URIs associated to the pod that you're RelativityOne tenant is assigned to. Contact Relativity Support to confirm which URI to use.

        • RelativityOne pod esus025000—https://services.esus.relativity.one/collect-oauth-authorization/index.html

        • RelativityOne pod esus025064—https://services-02.esus.relativity.one/collect-oauth-authorization/index.html

        • RelativityOne pod esus025128—https://services-03.esus.relativity.one/collect-oauth-authorization/index.html

        • RelativityOne pod esus025192—https://services-04.esus.relativity.one/collect-oauth-authorization/index.html

        • RelativityOne pod esus008064—https://services-05.esus.relativity.one/collect-oauth-authorization/index.html

        • RelativityOne pod esus022064—https://services-06.esus.relativity.one/collect-oauth-authorization/index.html

  6. Click Create.

After clicking Create, you will have your Client ID and Client Secret. Add them to the New Collection Source Instance.

Setting reauthentication policy

As an optional step, you will want to configure Google's reauthentication policy. To do that,

  1. Open Google Cloud Console and select newly created project.

  2. Click on the Navigation menu.

  3. Select Security > Access and data control > Google Cloud session control.

  4. On the Google Cloud session control, select a reauthentication policy.

    • Never require reauthentication

    • Require reauthentication

      Note: If you select Require authentication, you must also select Exempt Trust apps.

  5. Click Save.

Google's reauthentication policy on the Google Cloud session control page.

For more information on setting reauthentication policy and the options, see Google's documentation.

Google Workspace user account setup

Collections require user account on which behalf Relativity exports data. This can be a dedicated or an existing user account.

Create admin role for Vault API

  1. Open the Google Admin page.

  2. Click Account>Admin roles to open the up the page.

  3. Click Create New Role.

  4. Enter the role name. We recommend Relativity Collect.

  5. Click Continue to select privileges.

  6. Select the following privileges:

    • Services - Google Vault > Manage Matters

    • Services - Google Vault > Manage Searches

    • Services - Google Vault > Manage Exports

  7. Click Continue.

  8. Click Create Role.

Create admin role for the user accounts listing

  1. Open the Google Admin page.

  2. Click Account>Admin roles to open the up the page.

  3. Click Create New Role.

  4. Enter the role name. We recommend Users Reader for Collect.

  5. Click Continue.

  6. Select the Admin API privileges - Users > Read privilege.

  7. Click Continue.

  8. Click Create Role.

Create admin role for the groups listing

  1. Open the Google Admin page.

  2. Click Account>Admin roles to open the up the page.

  3. Click Create New Role.

  4. Enter the role name. We recommend Groups Reader for Collect.

  5. Click Continue.

  6. Select the Admin API privileges - Groups > Read privilege.

  7. Click Continue.

  8. Click Create Role.

Enable required privileges

  1. Open the Google Admin page.

  2. Navigate to Directory > Users to open the list of users.
  3. Select or create the user you want to use.

  4. Select and expand Admin roles and privileges pane.

  5. Assign the following roles to the user in All organizational units scope

    • Relativity Collect
    • Users Reader for Collect
    • Groups Reader for Collect

Restricting collections to the selected user accounts

You can restrict collections to the selected group of users by leveraging admin role scoping to organizational units. To limit collections, you will need to create an organizational unit and add the users to the unit. Once created, Collect will only collect data from the users within the organizational unit.

This configuration step is for Google Workspace data sources only and is optional.

Create an organizational unit

An organization unit restricts RelativityOne’s collections only to the selected custodians. Create an organization unit and add selected custodians to the unit so only their information is collected.

To create an organizational unit, open Google Admin Console and follow the steps below:

  1. Open Google Admin page.

  2. Navigate to Directory > Organizational Units.

  3. On the Manage organizational units page, click the + icon.

  4. In the Create new organizational unit pop-up menu, enter the Name of organizational unit.

  5. (Optional) Enter description of the organizational unit.

  6. Select the Parent Organization Unit (POU). If this field isn’t populated, add a POU. To create a POU, follow the steps in Google’s documentation.

  7. Click Create.

Once the organizational unit is created, the next step is to add targeted users you want to collect from to the unit.

To add users to the organizational unit, follow the steps below:

  1. Click the navigation menu.
  2. Navigate to Directory > Users.
  3. Select the users who should have collections restricted
  4. Click Change organizational unit.
  5. In the Change organizational unit pop-up menu, select appropriate organizational unit.
  6. Click Continue.
  7. Click Confirm.

You can upload a .csv file to bulk update users. For more information, see Google’s documentation.

Scope user privileges to the organizational unit

  1. Open Google Admin page.

  2. Navigate to Directory > Users.

  3. Select or create a user account.

  4. Select and expand the Admin roles a privileges pane.

  5. Click the pencil icon.

  6. Edit the scope of the role to the appropriate organization unit.

  7. Click Save.

Groups Reader privilege can only be scoped to All organizational units. This privilege is only required to enable collections from Google Workspace Groups and it can be omitted. Doing so will disable Groups collections on behalf of this user account.

Creating the data source

There are specific steps to connect Google Workspace to Relativity when creating the data source. To set up the Google Workspace data source, you will need to enable API access with Google Workspace and then complete the data source settings in Relativity.

After confirming that your Discover APIs are enabled, complete the set up process in Relativity.

    Notes: Copy the Refresh Token value you generate in Step 10 and store it in a secure location. It can be used to setup other Google Workspace data sources without the need to create new OAuth2 credentials.

    Google Workspace allows only a single refresh token to be generated for a set of OAuth2 credentials.

To add the Google Workspace data source, follow the steps below:

Google Workspace data source information page.

  1. Within the Collect application, navigate to the Collection Admin tab.

  2. Click the New Collection Source Instance button.
  3. Enter in a unique name for the data source.
  4. Select a Google Workspace data source.

  5. In the Settings pane, enter Client Id and Client Secret copied from Google’s OAuth2 credentials page. For more information, see Create credentials.

  6. Click Generate Code.

  7. Select or sign into Google’s account on which behalf collections will be performed.

  8. Click Copy Temporary Code to copy to your clipboard.

    Once copied, you can close that window and return back to RelativityOne.

  9. In Collect, paste the code in the Temporary Code field.

  10. Click Generate Refresh Token.

    The access token will be generated and populated in the Refresh Token field below.

      Notes: Copy Refresh Token value and store it in a secure location. It can be used to setup other Google Workspace data sources without the need to create new OAuth2 credentials.
      Google Workspace allows only a single refresh token to be generated for a set of OAuth2 credentials.

  11. Click Save.

Configuring the data source

Configure the data sources chosen in the Collection Details step. If you select multiple data sources in the first step, you will configure all sources in the step. Switch between each source by clicking the name of the data source in the left navigation menu. Clicking Next and Previous also moves you through the data sources. Select individual data sources by clicking on the checkbox and then using the right arrows to select them. After selecting the data sources to configure, fill out the criteria. Each data source has different criteria to enter.

Add criteria to collect specific data. To configure the data sources, complete the following fields:

  • Select and unselected tabs—choose the data sources to collect from by moving unselected data sources to the selected list.
  • Field—choose the field to filter on within the data source.
      Notes: This field is only required when a calendar source is selected.
  • Operator—choose an operator such as equals, contains, greater than, or less than.
  • Value—enter a value to find in the selected field.

After selecting field options, you must click Add Criteria. Things to know about criteria:

  • Each criteria is then separated by an AND operator.
  • Leave the data source criteria empty to collect all data from the sources.

Filter a data source's data that you want to collect by adding criteria. This section covers the different criteria for each data source. It also includes what can be searched within each data source. The criteria options change based on the selected data source.

The following table lists the filter criteria support for Google Workspace Chat collections. Google Workspace Chat data is collected in RSMF. For more information, see The Relativity Short Message Format .

Google Groups

Setting criteria for Google Groups is not required. For more information on Advanced examples, see Google Workspace documentation.

The following table lists the filter criteria support for Google Workspace Groups collections. Setting criteria for Google Workspace Groups is not required. For more information on Advanced examples, see Google Workspace documentation.

Criteria Operators Description Example
Advanced Equals When you use the Advanced property in a query, specific Google Workspace search criteria become available in Collect. For more information, see Google Workspace documentation. For more information on Advanced examples, see Google Workspace documentation.
Email BCC Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email BCC field. If you search “@example.com,” your results include all blind carbon copied messages received by people with the @example.com in their email address.
Email CC Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email CC field. If you search “@example.com,” your results include all carbon copied messages received by people with the @example.com in their email address.
Email From Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email From field. If you search “@example.com,” your results include all messages sent by people with the @example.com in their email address.
Email Received Date Equals, Does Not Equal, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Email Received Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Less Than 1/1/2021,” your results include all emails received before January 1, 2021.
Email Sent Date Equals, Does Not Equal, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Email Sent Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Greater Than 1/1/2001,” your results include all emails sent after January 1, 2001.
Email To Contains When you use the Email To property in a query, the search returns all messages that contain the text in the Email To field. If you search “@example.com,” your results include all messages sent to people with the @example.com in their email address.
Has Attachments Equals, Does Not Equal When you use the Has Attachments property, the search returns emails with or without attachments based on the Value setting. If you mark toggle the Value setting On, your results include all messages that include an attachment.
Is Draft Equals Indicates whether or not messages are written and not sent. Use the values true or false. If you mark toggle the Value setting On, your results include all emails that are in the drafted state.
Keyword Search Search In When you use the Keyword Search property in a query, the search returns all messages that contain the text you are searching for. If you search “Dear John,” your results include all messages that contain the text in email body. Note that this is not the same as searching for “Dear” OR “John”. In order to do that you need to enter keywords in separate lines.
Label Equals When you use the Label property, the search returns all messages that contains the search word or phrase in the emails' label. If you search "Important," your results include all emails that are marked with the "Important" label.
Subject Contains When you use the Subject property, the search returns all messages that contains the search word or phrase in the email's title.  If you use the Subject property in a query, the search returns all messages which the subject line contains the text you’re searching for. In other words, the query doesn’t return only those messages that have an exact match. For example, if you search for subject “Quarterly Financials,” your results include messages with the subject “Quarterly Financials 2018.”

Included in the Google Workspace Groups Criteria is one toggle:

  • Collect all emails with attachments regardless of criteria—enable the toggle to collect emails and attachments. Disable to collect only emails that match the criteria.

Gmail

Setting criteria for Google Drive is not required. For more information on Advanced examples, see Google Workspace documentation.

The following table lists the filter criteria support for Google Workspace Gmail collections. Setting criteria for Google Workspace Gmail is not required. For more information on Advanced examples, see Google Workspace documentation.

Criteria Operators Description Example
Advanced Equals When you use the Advanced property in a query, specific Google Workspace search criteria become available in Collect. For more information, see Google Workspace documentation. For more information on Advanced examples, see Google Workspace documentation.
Email BCC Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email BCC field. If you search “@example.com,” your results include all blind carbon copied messages received by people with the @example.com in their email address.
Email CC Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email CC field. If you search “@example.com,” your results include all carbon copied messages received by people with the @example.com in their email address.
Email From Contains When you use the Email From property in a query, the search returns all messages that contain the text in the Email From field. If you search “@example.com,” your results include all messages sent by people with the @example.com in their email address.
Email Received Date Equals, Does Not Equal, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Email Received Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Less Than 1/1/2021,” your results include all emails received before January 1, 2021.
Email Sent Date Equals, Does Not Equal, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Email Sent Date property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Greater Than 1/1/2001,” your results include all emails sent after January 1, 2001.
Email To Contains When you use the Email To property in a query, the search returns all messages that contain the text in the Email To field. If you search “@example.com,” your results include all messages sent to people with the @example.com in their email address.
Has Attachments Equals, Does Not Equal When you use the Has Attachments property, the search returns emails with or without attachments based on the Value setting. If you mark toggle the Value setting On, your results include all messages that include an attachment.
Is Draft Equals Indicates whether or not messages are written and not sent. Use the values true or false. If you mark toggle the Value setting On, your results include all emails that are in the drafted state.
Keyword Search Search In When you use the Keyword Search property in a query, the search returns all messages that contain the text you’re searching for. If you search “Dear John,” your results include all messages that contain the text in email body. Note that this is not the same as searching for “Dear” OR “John”. In order to do that you need to enter keywords in separate lines.
Label Equals When you use the Label property, the search returns all messages that contains the search word or phrase in the emails' label. If you search "Important," your results include all emails that are marked with the "Important" label.
Subject Contains When you use the Subject property, the search returns all messages that contains the search word or phrase in the email's title.  If you use the Subject property in a query, the search returns all messages which the subject line contains the text you’re searching for. In other words, the query doesn’t return only those messages that have an exact match. For example, if you search for subject “Quarterly Financials,” your results include messages with the subject “Quarterly Financials 2018.”

Included in the Google Workspace Gmail Criteria is one toggle:

  • Collect all emails with attachments regardless of criteria—enable the toggle to collect emails and attachments. Disable to collect only emails that match the criteria.

Google Drive

Setting criteria for Google Drive is not required. For more information on Advanced examples, see Google Workspace documentation.

The following table lists the filter criteria support for Google Workspace Drive collections. Setting criteria for Google Workspace Drive is not required. For more information on Advanced examples, see Google Workspace documentation.

Criteria Operators Description Example
Advanced Equals When you use the Advanced property in a query, specific Google Workspace search criteria become available in Collect. For more information, see Google Workspace documentation. For more information on Advanced examples, see Google Workspace documentation.
File Type Equals When you use the File Type property in a query, the search returns all files that equals what is entered. If you select "Google Sheets" as your value, your results include Google Sheet files.
Filename Contains When you use the Filename property in a query, the search returns all files that contain the value entered. If you search "Important_Document,” your results include all files with "Important_Document” in the filename.

Keyword Search

 Search In When you use the Keyword Search property in a query, the search returns all files that contain the text you’re searching for. If you search “Dear John,” your results include all messages that contain the text in the file. Note that this is not the same as searching for “Dear” OR “John”. In order to do that you need to enter keywords in separate lines.
Modification Date Equals, Does Not Equal, Greater Than, Greater Than or Equals, Less Than, Less Than or Equals When you use the Modification Date property in a query, the search returns all files that equal/doesn’t equal, greater/less than the selected date. If you search “Less Than 1/1/2021,” your results include all files received before January 1, 2021.
Owner Contains When you use the Owner property in a query, the search returns all messages that contain the text in the Owner field. If you search “Iscovery,” your results include all files sent by people with the "Iscovery" in their name, such as "Ed Iscovery."
Shared By Contains When you use the

Shared By property in a query, the search returns all files that contain the text in the Shared By field.		 If you search “ExampleUser1,” your results include all filed shared by people with the UserExample1 in their name.

Shared With

 Contains When you use the Shared With property in a query, the search returns all files that contain the text in the Shared With field. If you search “UserExample1,” your results include all files shared with people with the UserExample1 in their name.
Version Date Equals When you use the Version Date property in a query, the search returns the version of files on the selected date. If you search 1/1/2021, your results include only the version of the files on 1/1/2021. The results won't include earlier or later versions of the file.

Included in the Google Workspace Drive Criteria is one toggle:

  • Collect files from shared drives—enable the toggle to retrieve data from shared drives, along with personal drives, that match the criteria. Disable to collect only data from personal drives that match the criteria.

Google Chat

Setting criteria for Google Workspace Chat is not required. For more information on Advanced examples, see Google Workspace documentation.

Criteria Operators Description Example
Advanced Equals When you use the Advanced property in a query, specific Google Workspace search criteria become available in Collect. For more information, see Google Workspace documentation. For more information on Advanced examples, see Google Workspace documentation.
Content Type Equals When you used the Content Type property in a query, the search returns messages with specific file types. If you search with the value set to Google Docs, your results include all Google Docs sent as messages.
Keyword Search Equals When you use the Keyword Search property in a query, the search returns all messages that contain the text you’re searching for. If you search “Dear John,” your results include all messages that contain the text in email body. Note that this is not the same as searching for “Dear” OR “John”. In order to do that you need to enter keywords in separate lines.

Message Source

 Equals When you use the Message Source property in a query, the search returns all direct messages or all messages in rooms. If you search with the value set to "Messages in Rooms," your results include only messages sent in a group chat and no direct messages will be included.
Sent/Updated Date Greater Than or Equals, Less Than, Less Than or Equals When you use the Sent/Updated property in a query, the search returns all messages that equal/doesn’t equal, greater/less than the date entered. If you search “Greater Than 1/1/2001,” your results include all messages sent after January 1, 2001.
Slice Interval in Hours Equals When you use The Slice Interval in Hours property, the search returns all messages in a specific time range or defaults the slice interval to 24 hours. If you search with a slice interval set to one hour and a conversation spans five hours, you will end up with five RSMFs after processing. For more information, see RSMF Slicing.
User At Contains When you use the User At property in a query, the search returns all messages that contain the text in the User At field. If you search “UserExample1” your results include all messages sent to people with the UserExample1 in their email address.

User From

 Contains When you use the User From property in a query, the search returns all messages that contain the text in the User From field. If you search “ExampleUser1,” your results include all messages sent by people with the UserExample1 in their email address.

Included in the Google Workspace Chat Criteria are two toggles:

  • Include results from Rooms—enable this toggle to include all messages in rooms, along with direct messages, that match your query. Disable to collect only direct messages that match your query.

  • Disable RSMF conversion—enable this toggle to keep data in its original format by preventing Relativity from converting the files into Relativity's short message format (RSMF) files.

Troubleshooting

This table includes troubleshooting for Google's data sources.

Error Cause Resolution
The token is invalid. You must remove access and generate a new refresh token. For more information, see Troubleshooting. Your token is invalid. This could be due to changing the account owner. While signed in with your account, navigate to https://myaccount.google.com/u/0/permissions. In the page, click Remove Access. Then generate a new refresh token. For more information on generating a refresh token, see Creating the data source