Chapter 7. Connect to Gmail

To trigger execution of an integration when a particular Gmail account receives an email, add a Gmail connection to an integration as its start connection. In an integration, to send an email from a particular Gmail account, add a Gmail connection as the integration’s finish connection, or as a middle connection.

The general steps for connecting to Gmail in an integration are:

  1. Register Fuse Online as a Google client application.
  2. Create a Gmail connection. When you do this you choose the Gmail account that the connection is authorized to access.
  3. If your integration sends an email from a Gmail account, decide how to populate an email to send.
  4. Add a Gmail connection to an integration.
  5. For a Gmail connection that sends an email, optionally map integration data to the email fields.

Information and instructions are in the following topics:

7.1. Register Fuse Online as a Gmail client application

In an integration, to be able to connect to Gmail, you must register your Fuse Online environment as a Google client application. During registration, you enable the Gmail API and create credentials that Fuse Online uses to access Google APIs that you have enabled.

With registration in place, you can create any number of Gmail connections and any number of integrations that connect to Gmail. While each Gmail connection uses the same registration, each connection can access the mail for a different Google account.

Note

If you already created a Google Calendar connection, then you already created the credentials that your Fuse Online environment needs to access enabled Google APIs. You do not need to follow the procedure documented here. To be able to create a Gmail connection, you just need to enable the Gmail API.

Prerequisite

You must be able to sign in to the Google account that you want to use to register Fuse Online as a Gmail client application.

Procedure

  1. In Fuse Online, do the following:

    1. In the left navigation panel, click Settings.
    2. On the Settings page, near the top, to the right of the callback URL, click Copy Callback URL to copy the callback URL for your Fuse Online environment to the clipboard. You will need this URL later in this procedure.
  2. In another browser tab, go to https://console.developers.google.com and do the following:

    1. Confirm that you are signed in to the Google account that you want to use to register Fuse Online as a Google client application. Or, choose a different Google account and sign in to that account.
    2. Ensure that you want to use the current Google project to grant authorization to Fuse Online. Or, choose or create another project. If this Google account does not already have a project, you must create one. For information about Google projects and how you might want to organize your use of projects, click the Google help icon in the upper right.
    3. Enable the Gmail API as follows:

      1. You should see the APIs and Services dashboard. If you do not, then in the upper left corner, click the Navigation menu icon and select APIs and Services > Dashboard.
      2. Click the Gmail API card.
      3. In the Gmail API page, click ENABLE.
    4. Give your client application a name as follows:

      1. In the page that appears, in the left navigation panel, click Credentials and then on the right, click Credentials in APIs & Services.
      2. Click the OAuth consent screen tab.
      3. In the page that appears, in the Application Name field, enter a name for the Fuse Online client application. For example, enter Fuse Online client application.
      4. Skip the other fields.
      5. Click Save.
    5. Obtain client application credentials as follows:

      1. To the right of Create Credentials, click the down arrow to display a menu and select OAuth client ID.
      2. In the page that appears, select Web application to display more content.
      3. In the Name field, enter a name for the OAuth client ID for your Fuse Online environment. This is different from the name that you entered for the client application itself. For example, enter OAuth client ID for Fuse Online.
      4. Skip Authorized JavaScript origins.
      5. In the Authorized redirect URIs field, paste the callback URL that you copied from your Fuse Online environment at the beginning of this procedure.
      6. Click Create to display the client ID and client secret for your Fuse Online environment.
    6. To the right of the client ID field, click the Copy icon to copy the client ID to your clipboard.
  3. Return to the Fuse Online Settings page, expand the Gmail entry, and in the Gmail Client ID field, paste the consumer client ID that you just copied.
  4. Return to the Google developers site and to the right of the client secret field, click the Copy icon to copy the client secret to your clipboard.
  5. Return to Fuse Online and do the following:

    1. In the Settings page, in the Gmail Client Secret field, paste the Gmail client secret that you just copied.
    2. Click Save. You should get a Registration Successful! notification.
    3. Click Ok to collapse the fields.

Results

You can now create a Gmail connection.

Important

The Google client ID and Google client secret contain token refresh information that ensures that your Gmail connections, and integrations that have Gmail connections continuously work correctly. Consequently, you should not obtain new credentials. If you do, then you would need to recreate each Gmail connection, replace the old Gmail connections with new Gmail connections, and re-publish each integration that uses a Gmail connection.

7.2. Enable access to the Gmail API

To be able to connect to Gmail in an integration, you must register your Fuse Online environment as a Google client application. During registration, you enable the Gmail API and create credentials that Fuse Online uses to access Google APIs that you have enabled.

If you already created a connection to Google Calendar, then Fuse Online has the credentials for access to enabled Google APIs. To be able to create a Gmail connection, you just need to enable the Gmail API and then in the Fuse Online Settings page, copy the Google Calendar client ID and client secret to the Gmail settings for client ID and client secret.

If you already registered your Fuse Online environment as a Google client application and during registration you enabled the Gmail API, then you do not need to follow the procedure provided here. You are ready to create a Gmail connection.

Prerequisite

In the Settings page in your Fuse Online environment, the Google Calendar entry displays Edit and Remove, which indicate that Fuse Online has the credentials to access enabled Google APIs. If Register appears in the Google Calendar entry and the Gmail entry, then you must register your Fuse Online environment as a Google client application.

Procedure

  1. In a browser, go to https://console.developers.google.com.
  2. Confirm that you are signed in to the Google account that you used to register your Fuse Online environment as a Google client. If you are not, sign in to that account.
  3. Ensure that the current Google project is the one you used for registration. If it is not, change to that project.
  4. You should see the APIs and Services dashboard. If you do not, then in the upper left, click Navigation menu icon and select APIs and Services > Dashboard.
  5. Click the Gmail API card.
  6. In the Gmail API page, click ENABLE.
  7. In the Fuse Online Settings page:

    1. Expand the Google Calendar entry
    2. Expand the Gmail entry.
    3. Copy the Google Calendar client ID to the input field for the Gmail client ID.
    4. Copy the Google Calendar client secret to the input field for the Gmail client secret.
    5. Click Save,and then click Ok.

Result

You can now create a Gmail connection.

7.3. Create a Gmail connection

When you create a Gmail connection, you authorize the connection to access one particular Gmail account. After you create a Gmail connection, you can add it to multiple integrations.

Prerequisite

You registered your Fuse Online environment as a Gmail client application.

Procedure

  1. In Fuse Online, in the left panel, click Connections to display any available connections.
  2. In the upper right, click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
  3. Click the Gmail connector.
  4. In the Configure Connection page, click Connect Gmail, which takes you to a Sign in with Gmail page.

    If Connect Gmail does not appear, then your Fuse Online environment is not registered as a Gmail client application. See Register with Gmail. When you try to create a Gmail connection and your Fuse Online environment is not registered as a Gmail client application, then Fuse Online displays multiple fields that prompt for authorization information. While you can create a Gmail connection by entering values in these fields, you should register with Gmail first, and then create a Gmail connection after registration is in place.

  5. In the page that is prompting you to sign in to Gmail, enter the email address of the Google account that you want this connection to access from Fuse Online and click Next.
  6. In response to openshiftapps.com wants to access your Google Account, click Allow to return to Fuse Online.
  7. In the Fuse Online Connection Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter Gmail Connect 1.
  8. In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter Sample Gmail connection that uses jkim Gmail account credentials.
  9. In the upper right, click Create to see that the connection you created is now available. If you entered the example name, you would see that Gmail Connect 1 appears as a connection that you can choose to add to an integration.

7.4. Alternatives for populating email to send

A Gmail connection that finishes an integration or that is in the middle of an integration sends an email from the Gmail account that the connection is authorized to access. There are several ways to populate the content of the email that the connection sends. Before you add a Gmail connection that sends an email, consider how you want to populate that email.

The alternatives for populating an email to send are as follows:

  • Add a data mapper step just before the Gmail connection that sends an email. In this data mapper step, map data fields that are output from previous integration steps to Gmail connection Send Email action fields. The Send Email action fields are:

    • Email to
    • Email subject
    • Email text
    • Email cc
    • Email bcc

    If you add a data mapper step then you can map one, some, or all Send Email action fields.

  • When you add a Gmail connection to an integration, configure the action by specifying values in the Send Email action fields. You can specify values in one, some, or all fields.
  • Use both a data mapper step and Send Email action configuration to populate the fields. In other words, you can configure the Send Email action by specifying one or more fields and also add a data mapper step that populates other fields.

    A value that you specify directly in a Send Email action field has precedence over a value that is mapped to the Send Email action field. In other words, suppose you populate a Send Email field by specifying a value when you add the connection and configure the action and also by mapping a value to the same field. The value that you specify in the action configuration always overrides the value that was mapped. For example, suppose you specify people@redhat.com in the Email to action field and you also map an email field from a previous step to the Gmail Email to field. The integration always uses people@redhat.com and only people@redhat.com as the email address.

When you add a Gmail connection that sends an email, no action configuration parameters are required. This is because you might choose to populate an email entirely by mapping integration data to the Send Email action fields. However, the presence of an email address in the Email to field, either by configuration specification or by mapping, is required. Without an email address to send the message to, Fuse Online generates a runtime error and the integration stops executing.

7.5. Trigger an integration when polling returns a Gmail message

To trigger execution of an integration based on email received by a particular Gmail account, add a Gmail connection as the start connection of an integration. When the integration is running, the Gmail connection checks this account for emails at intervals that you control. When the connection finds an unread email, it passes the email to the next step in the integration and, by default, marks the email as read.

Prerequisite

You created a Gmail connection that is authorized to access the Gmail account that you want to obtain emails from.

Procedure

  1. In the Fuse Online panel on the left, click Integrations.
  2. Click Create Integration.
  3. On the Choose a Start Connection page, click the Gmail connection that you want to use to start the integration.
  4. On the Choose an Action page, click the Receive Email action.
  5. To configure the Receive Email action:

    1. In the Delay field, accept the default of 30 seconds or specify how often you want the integration to check for new email.
    2. In the Labels field, leave it blank to obtain any unread email. To obtain only certain emails, specify a comma separated list of labels that are used in the Gmail account that the connection is accessing. By default, the integration obtains the unread emails that have those labels.
    3. Select Mark as read to ensure that the connection does not return the same email twice. If Mark as read is not selected, the connection returns emails that are in the account’s in box, whether or not they were previously read. Or, if you specify one or more labels, then the integration return emails that have those labels whether or not they were already read.
    4. In the Max Results field, accept the default of 5 or indicate the maximum number of emails that the connection can return for each poll. If the connection finds more than this number of unread emails, then it returns the most recent Max Results emails.

      When a Gmail connection returns more than one email, the integration processes the emails as a batch. In other words, Fuse Online executes the integration once for the batch.

    5. Click Done to add this Gmail connection as the start connection in the integration. The connection appears as the first step in the integration flow.

7.6. Send an email from a Gmail account

In an integration, you can send an email from a Gmail account either in the middle of the integration or to finish the integration. To do this, add a Gmail connection to the middle of an integration or as the integration’s finish connection.

Prerequisites

Procedure

  1. Start creating the integration.
  2. Add and configure the start connection.
  3. On the Choose a Finish Connection page, do one of the following:

    • To finish an integration by sending an email from a Gmail account, click the Gmail connection that is authorized to access the Gmail account that you want to send the email from.
    • To send an email in the middle of an integration:

      1. Click the connection that you want to use to finish the integration.
      2. Configure that connection.
      3. When the finish connection is part of the integration, in the left panel, hover over the plus sign where you want to add a Gmail connection and click Add a connection.
      4. Click the Gmail connection that you want to use to send an email in the middle of an integration.
  4. On the Choose an Action page, click Send Email.
  5. On the Configure Send Email page, do one of the following:

    • Leave all fields blank if you plan to add a data mapper step just before this connection and you plan to map integration data to the Send Email fields.
    • Enter information in one or more fields:

      1. In the Email To field, enter one email address or a comma separated list of email addresses to send the email to.
      2. In the Email Subject field, enter text that states the subject of the email.
      3. In the Email Text field, enter the message that you want to send.
      4. In the Email cc field, enter a comma separated list of email addresses to which you want to send copies of the email.
      5. In the Email bcc field, enter a comma separated list of email addresses to which you want to send blind copies of the email.
    • Leave some fields blank and enter information in some fields.

      If you plan to add a data mapper step just before this Gmail connection, and you want to map integration data to some email fields, leave those fields blank in the action configuration. Enter values in other action fields as needed.

      A value that you specify in a Send Email action configuration field has precedence over a value that is mapped from a previous step.

  6. Click Done to add the connection to the integration.

Result and next steps

The connection appears in the integration flow in the location where you added it. If you plan to add a data mapper step before this connection, first add any other connections that you plan to add to this integration. Then add the data mapper step.