Gmail API

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

Considerations

Consider the following when using the Google Mail API for hold communications:

  • Your refresh token must be updated when it reaches certain limitations. For more information, see Google's documentation.
    Limitation examples:
    • The user has revoked your app's access.
    • The refresh token has not been used for six months.
    • The user changed passwords and the refresh token contains Gmail scopes.
    • The user account has exceeded a maximum number of granted (live) refresh tokens.
    • If an admin set any of the services requested in your app's scopes to Restricted. The error is admin_policy_enforced.
    • The session length set by the admin could have been exceeded.
  • The Gmail API is not compatible with incoming email.
  • You must use a Client ID and Client Secret that is specific to these email settings. For example, you cannot use the Client ID and Client Secret entered for preservation in-place.

Requirements

Before setting up a Google Mail to communicate, you must complete the following steps in order:

  1. Create a Google Cloud project.
  2. Enable required APIs for the project.
  3. Set up OAuth2 consent screen.
  4. Create credentials.
  5. Add email settings.

After completing these required steps, you can use a Gmail account in RelativityOne.

Create 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, then click Create Project.
  2. Enter information into the fields:
    • Project name—enter a descriptive name for your project.
    • Organization—enter the name of your organization.
    • Location—enter the parent organization or folder.
  3. Click Create.

The New Project window in Google Cloud.

Enable required APIs for the project

Next in the process, you must 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.

    The APIs and Services menu open with the Library tab selected.

    This will open up the Library page that includes all available APIs.
  3. Enter Gmail API in the search bar and search.
  4. Click the Gmail API option, then click Enable.

Set up OAuth2 consent screen

Follow the steps below to create an 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 and click Create.
    OAuth consent screen on the APIs and Services window.
  5. Enter descriptive App name. For example, Relativity Preservation.
  6. Enter a User support email from within your organization.
  7. Enter relativity.one as Authorized Domain.
  8. Enter an email from within your organization in the Developer Contact Information field.
  9. Click Save and Continue.

In the next step, you will add scopes.

Note: You cannot use the same scopes used in Preservation in-place.

  1. Click Add or remove scopes.
  2. Enter filter and select https://www.mail.google.com/ or enter it in a text box.
  3. Click Update.
  4. Click Save and Continue.

Create credentials

You must create credentials, enter an authorized redirect URL, and save your client ID and secret.

Note: You must use a Client ID and Client Secret that is specific to these email settings.

  1. Click the navigation menu 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 URL based on the RelativityOne Data Center Geo you intend to run collections from.
      • For example, https://{instanceURL}.com/Relativity.REST/api/kCura.LegalHold.Services.ILegalHoldModule/Google%20Authorization%20Manager/workspace/{WorkspaceID}/GoogleMail/HandleAuthenticationRedirect.
      • When the {InstanceURL} is a Relativity instance URL and {WorkspaceID} is the Relativity workspace artifact ID where you are setting up the email settings..
  6. Click Create.

After clicking Create, you will have your Client ID and Client Secret. You will need to use them when adding your email settings.

The OAuth client created windown with Your Client ID and Your Client Secret fields.

Add email settings

After completing the required steps in Google, you can then set up the account in RelativityOne.

To set up Gmail for Legal Hold:

  1. Navigate to the Legal Hold Settings page.
  2. Click Edit.
  3. Locate the Outgoing Email section.
  4. Enter information in the fields. For more information, see Outgoing email fields.
    The Outgoing Email settings for Gmail.
  5. Update another section or click Save.

Outgoing email fields

Enter the information you gathered in Google into the following fields:

Note: You must use a Client ID and Client Secret that is specific to these email settings.

  • Client ID—enter the Client Id copied from Google’s OAuth2 credentials page.
  • Client Secret—enter Client Secret copied from Google’s OAuth2 credentials page. For more information, see Create credentials.
  • From Email Address—enter the email address you authenticated with Google. Relativity will only use the email inbox that you authenticated with.
  • Reply to Email Address—enter the email address you authenticated with Google. Relativity will only use the email inbox that you authenticated with.

If authentication is successful, you will see the following message:

Google's success message.