Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 7. Connecting to Gmail

To trigger 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 client application that can access the Gmail API.
  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

To be able to connect to Gmail in an integration, you register your Fuse Online environment as a client application that can access Gmail. Registration authorizes Fuse Online to access Gmail. 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 use different user credentials to access a different Gmail account.

To authorize your Fuse Online environment to access Gmail:

  1. In Fuse Online, 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 toward the end of this procedure.

  3. In another browser tab, go to https://console.developers.google.com and do the following:

    1. Confirm that you are signed in to the Gmail account that you want to use to register Fuse Online as a Gmail client application. Or, choose a different Gmail 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. 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.
    4. Click the Gmail API card.
    5. In the Gmail API page, click Enable.

    6. In the page that appears, in the left navigation panel, click Credentials and then click the OAuth consent screen tab. In this tab, do the following:

      1. In the Product name shown to users field, enter a name for the client application. For example, enter Fuse Online client application.
      2. Skip the other fields.
      3. Click Save.
    7. To the right of Create Credentials, click the down arrow to display a menu and select OAuth client ID.

    8. Select Web application and in the page that appears, do the following:

      1. 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.
      2. Skip Authorized JavaScript origins.
      3. In the Authorized redirect URIs field, paste the callback URL that you copied from your Fuse Online environment at the beginning of this procedure.
      4. Click Create to display the client ID and client secret for your Fuse Online environment.
    9. To the right of the client ID field, click the Copy icon to copy the client ID to your clipboard.
  4. Return to the Fuse Online Settings page, expand the Gmail entry, and in the Gmail Client ID field, paste the Gmail client ID that you just copied.
  5. 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.
  6. Return to the Fuse Online Settings page and in the Gmail Client Secret field, paste the Gmail client secret that you just copied.
  7. Click Save. You should get a Registration Successful! notification.
  8. Click Ok to collapse the fields. With registration in place, you can create a Gmail connection.

7.2. Create a Gmail connection

A connection to Gmail requires registration of Fuse Online as an application that can access Gmail. If you did not already register Fuse Online, see Section 7.1, “Register Fuse Online as a Gmail client application”.

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.

To create a Gmail connection:

  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 installation is not registered as a Gmail client application. See Section 7.1, “Register Fuse Online as a Gmail client application”. When your installation is not registered with Gmail, then when you try to create a Gmail connection, 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.3. 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.4. Add a Gmail connection to an integration

You must create a Gmail connection before you can add it to an integration. If you did not already create a Gmail connection, see Section 7.2, “Create a Gmail connection”.

The procedure for adding a Gmail connection to an integration varies according to whether you want to use the Gmail connection to:

  • Trigger an integration based on email that is received by the account that the connection has authorization to access. Periodically, the connection obtains the email and sends it to the next step in the integration. To do this, add a Gmail connection as an integration’s start connection.
  • Send an email from the account that the connection is authorized to access. To do this, add a Gmail connection in the middle of an integration or as the integration’s finish connection.

See the following topics:

7.4.1. Obtain emails that are received by a Gmail account

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 you created the Gmail connection you authorized it to access the particular Gmail account that you want to obtain emails from.

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.

To trigger an integration based on email received by a particular Gmail account:

  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.4.2. 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.

Before you add a Gmail connection that sends an email, decide how you want to populate the fields in the email. See Section 7.3, “Alternatives for populating email to send”.

To add a Gmail connection that sends an email from the authorized Gmail account:

  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. For more information about this, see Section 7.3, “Alternatives for populating email to send”.

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

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.