Google Gmail Connector

Squirro provides a 1-click connector for Gmail. This connector allows the Project Creators to connect to a Google account and index the Gmail data into Squirro.

Set up connector

Usage assumes that the OAuth setup for the 1-click connectors has already been done on the server. This is by default available on all of our cloud servers at https://start.squirro.com. For any other Squirro installation, please ask your Squirro server admin to follow the steps in the OAuth Configuration section below.

• Head over to the Enterprise tab on the Data screen as shown in the screenshot below.

• Click on the Gmail icon. Squirro will show a prompt asking you to authenticate your Google account. Click on the Authenticate button there.

• Once you click on the Authenticate button, you will be re-directed to the Sign-in screen hosted by Google.

Squirro will never ask you for your Google password. This is requested by Google itself.

• Once you sign-in you will be prompted to approve Gmail scopes. This screen is presented to you by Google asking you to provide consent for your Gmail data to Squirro.

• Click Allow on one more screen to approve scopes.

• After approving scopes you will be brought back to Squirro’s source configuration screen. This screen shows which Google account Squirro has connected to.

• Now, you can click Save & Exit for Squirro to automatically configure the mapping of item fields and labels, as well as any other required source configuration.

Messages and attachments from spam and trash folders are not fetched by default. To change that behaviour expand the Advanced Options section and check the option to fetch data from spam and trash.

• Alternatively you can define those settings manually by clicking Next and going through the whole source setup process. This allows you the full flexibility of how the Gmail data should be mapped to Squirro items.

• After clicking on Save & Exit, you will see your source running. Sit back, relax & enjoy while we index your Gmail data into Squirro.

OAuth Configuration

App Config

You will need to register an OAuth2 app on the Google portal to allow Squirro to connect to the Google accounts of end users. Please follow the steps below to do so.

Note that the exact process on the Google platform may change. If you notice big discrepancies between the current Google website and the documentation page here, please reach out to Squirro’s support at support@squirro.com for help.

• Go to Google Developer Console here: https://console.developers.google.com/, and click on the arrow on the top of the page to display projects settings.

• On the next screen, click the New project button.

• Choose the appropriate name of your project and click the Create button.

• After creating the project go to the link https://console.developers.google.com/marketplace/product/google/gmail.googleapis.com and enable Gmail API service.

• The next step is creating an OAuth consent screen. To do that first go back to your project’s settings and in the OAuth consent screen tab choose External user type (if you want to make the app available only to users within your organization choose Internal user type). Confirm your choice by clicking Create button.

• On the next screen, choose the following options:

  • App name: Name of your app

  • User support email: Email for users to contact with questions about their consent

  • Authorized domains: When a domain is used on the consent screen or in an OAuth client’s configuration, it must be pre-registered here

  • Email addresses: Email addresses for Google to notify about any changes to your project

  • Other fields are necessary only when you are going to apply your app for production.

• On the Scopes screen add https://www.googleapis.com/auth/gmail.readonly scope and click Update button.

• On the next screen you can choose test users which will be able to connect to the app. To disable testing mode you need to apply for production status of the Gmail app. More information about how to do that you will find in the Apply for Production section below.

• The last screen is a Summary screen, so you can see your final app settings and make necessary corrections.

• Go to the Credentials tab, click Create Credentials button and choose OAuth client ID option.

• On the next screen, choose the following options as shown in the screenshot below and then click on Create button:

  • Application type: “Web application”

  • Name: Name of the client (could be whatever you want)

  • URIs: This is the URL Google will redirect the user to after successful authorization. This needs to be set to https://<your-server-url>/dataloader/gmail_plugin/pl/google/authorized on your server.

    For example: https://squirro.example-company.com/dataloader/gmail_plugin/pl/google/authorized.

Apply for Production

As was mentioned above, the app is in the testing mode by default. It means that it has some restrictions on using it. While the app is in the testing mode only test users are able to access the app. Also, the app is limited in terms of users (up to 100). Moreover, the app will show a warning that Google hasn’t verified this app during the user authorization process when the users connect their Squirro instance to their Google account. To avoid that, you have to apply for publishing the Gmail app.

To start that verification process follow the steps described here: https://support.google.com/cloud/answer/9110914?hl=en.

Squirro Configuration

After having created the OAuth2 app on the Google portal, you need to configure the Client ID and the Client Secret on your Squirro instance.

• Go to the Credentials tab of the app and click the details of your client. Get the Gmail Client ID and the Client Secret from here.

This configuration will soon be possible from the user interface.

• Edit /etc/squirro/common.ini on your Squirro cluster and add the following lines:

[dataloader]
gmail_client_id = YOUR_ID
gmail_client_secret = YOUR_SECRET

• If the [dataloader] header is already present in this file, add the two lines to the existing section. The section header can not appear more than once in the configuration file.

• Restart the frontend & datasource service to apply the settings:

sudo systemctl restart sqfrontendd
sudo systemctl restart sqdatasourced