Getting Started with Apigee Integration and Cloud Pub/Sub trigger

Stay organized with collections Save and categorize content based on your preferences.

You're viewing Apigee X documentation.
View Apigee Edge documentation.

Learn how to create a sample integration using Apigee Integration and the Cloud Pub/Sub trigger. The following steps describe how to configure the trigger, tasks, variables, and data mappings required to run a complete integration.

In this quickstart, you will create a Pub/Sub topic, create an integration with a Cloud Pub/Sub trigger to listen to the Pub/Sub topic, use data mapping to transform Pub/Sub messages, and send an email, all from within the integration designer.

Before you begin

Ensure that you perform the following tasks before beginning the quickstart.

  • Assign the following IAM roles to the Apigee Integration Service Agent (service-PROJECT_NUMBER @gcp-sa-apigee.iam.gserviceaccount.com) in your Google Cloud project.
  • Create a new Cloud Pub/Sub topic.

    This quickstart assumes that you have a Pub/Sub topic that receives temperature readings in degrees Kelvin from a IOT device. It is not necessary to actually have the topic connected to a device. This quickstart tests the integration's ability to listen to the topic and perform tasks when triggered.

    To create a sample topic for the purposes of this quickstart:

    1. Go to the Pub/Sub topics page in the Cloud console.

      Go to the Pub/Sub topics page

    2. Click Create a topic.
    3. In the Topic ID field, provide a unique topic name. For example, enter temperaturesensor
    4. Click Save.

Create a new integration

To create a new integration, perform the following steps:

  1. In the Apigee UI, select your Apigee Organization.
  2. Click Develop > Integrations.
  3. Click CREATE INTEGRATION.
  4. Enter a name and description in the Create Integration dialog. For example, my-test-integration.
  5. Select a Region for the integration from the list of supported regions.
  6. Click Create to open the integration designer.

Add a Cloud Pub/Sub trigger

To add a Cloud Pub/Sub trigger to the integration, follow the steps below:
  1. In the Integration designer, select Add a task/trigger > Triggers to display a list of available triggers.
  2. Click and place the Cloud Pub/Sub trigger element to the designer.

Configure a Cloud Pub/Sub trigger

Click the Cloud Pub/Sub trigger element in the integration designer to view the trigger configuration pane.

Specify the topic the trigger should listen to in the Pub/Sub topic field in the following format, where:

  • PROJECT_ID is the Google Cloud project where your topic is created.
  • TOPIC_ID is the ID of the Cloud Pub/Sub topic you created in Before you begin.
projects/PROJECT_ID/topics/TOPIC_ID

For example, if your project is named my-project and you named your topic temperaturesensor, enter:

projects/my-project/topics/temperaturesensor.

To view all the available topics in your Google Cloud project, see the Topic name column in Topics.

The configuration pane will automatically populate the Trigger Output field with a variable to hold the Pub/Sub message, as shown below:

image of Trigger Output variable

Add and configure the Data Mapping task

To configure the Data Mapping task:

  1. Select Add a task/trigger > Tasks to display a list of available tasks.
  2. Click and place the Data Mapping element in the integration designer.
  3. Click on the Data Mapping task on the designer to open the configuration pane for the task.
  4. Click Open Data Mapping Editor.

    The Data Mapping Editor lets you map input variables to the desired output variables, using the available transform functions. The output is then available as a variable to any other integration task or trigger. For more details on passing data as variables, see Using variables in Apigee Integration.

    For this quickstart, follow these steps to create a mapping using the CloudPubSubMessage as input:

    1. Drag the CloudPubSubMessage variable from the Variables list to the first Input row.
    2. Click + (Add a function) in the CloudPubSubMessage variable chip to view the drop-down list of available functions.
    3. Click TO_DOUBLE() to convert the CloudPubSubMessage JSON value to a data type of double.
    4. Click + (Add a function) again in the CloudPubSubMessage variable chip to select and chain the SUBTRACT function.
    5. Enter a parameter of 273.15 to convert the Kelvin temperature to degrees Celsius.
    6. Click the first row in the Output column to create a new output variable to hold the value of the transformed data. Complete the following fields:
      • Name: enter TempInCelsius.
      • Check Use as an output of integration.
      • Click Create to create the variable and close the pane. The new TempInCelsius variable will appear in the Variables list.
    7. Drag the TempInCelsius variable from the Variables list to the second row in the Input column.
    8. Click + (Add a function) in the TempInCelsius variable to view the drop-down list of available functions.
    9. Click TO_STRING() to transform the data type of the variable from double to string.
    10. Click the second row in the Output column to create a new variable to hold the value of the transformed data. Complete the following fields:
      • Name: enter TempInCelsiusString.
      • Blank default value means: Select Empty String.
      • Select the Use as an output of integration checkbox.
      • Click Create to create the variable and close the pane. The new variable will appear in the Variables list on the left side of the data mapping editor.
    11. The completed mapping should appear as shown in the figure below:

      image showing data mapping editor image showing data mapping editor

    12. Close the Data Mapping Editor once your mapping is complete. Any changes will be autosaved.

Add and configure the Send Email task

To configure the Send Email task:

  1. Select Add a task/trigger > Tasks in the integration designer to display the list of available tasks.
  2. Click and place the Send Email element in the integration designer.
  3. Click the Send Email element on the designer to open the configuration pane of the task. Set the following properties:
    • To Recipient(s): Enter your email address. You will use this email to confirm the successful completion of the integration.
    • Subject: Enter Temperature in Celsius.
    • Body in Plain Text: Select the TempInCelsiusString variable created earlier in the Data Mapping task.
    • The remaining options can be left in the default configuration.
    Your changes to the properties are saved automatically.

Add the required edge connections

An edge is a connection between any two elements in an integration. The connection denotes the direction of the control flow from one element(task or trigger) to another. For more information on edges, see Edges.

  1. Add an edge connection from the Cloud Pub/Sub trigger element to the Data Mapping element by hovering over a control point on the Cloud Pub/Sub trigger element, then clicking and dragging a line to a control point on the Data Mapping task element. This edge denotes the flow of control from the Cloud Pub/Sub trigger task to the Data Mapping task.
  2. Add an edge connection from the Data Mapping element to the Send Email element by hovering over a control point on the Data Mapping element, then clicking and dragging a line to a control point on the Send Email task element. This edge denotes the flow of control from the Data Mapping task to the Send Email task.

    The completed connection should appear as shown in the figure below:

    image of integration trigger and tasks

Test the integration

To test the new integration:

  1. Click Test in the integration designer toolbar, and then select the Pub/Sub Trigger.
  2. In the Confirm Publish and Test dialog, click Publish & Test.
  3. Go to the Pub/Sub topics page in the Cloud console.

    Go to the Pub/Sub topics page

  4. Search for and then select the temperaturesensor topic you created in a previous step.
  5. From the topic detail page, click + Publish Message to open the Publish Message configuration pane.
  6. In the Message body field, enter 307.15. Creating this message simulates the publication of a temperature reading in Kelvin received by Pub/Sub from an IOT device.
  7. Click Publish to publish the message to the topic and trigger your integration.

Upon successful completion, the integration sends an email with the Kelvin temperature converted to degrees Celsius to the email address specified in the Send Email task. Confirm receipt of the email in your email client.

The email sent by the integration should have a message body containing the value 34.

In addition to verifying the contents of the email, you can inspect the logs to view the status and payload of a given integration. To view logs:

  1. Click Logs in the toolbar of the Integration designer.
  2. On the Execution Logs page, you can view details about each attempt to run an integration. Each entry includes details for the execution attempt, including:
    • Integration name
    • Execution ID
    • Status
    • Start time
    • Duration
    • Integration Version
    • Trigger ID
  3. Click the expander arrow (>) next to the executed integration to view an expanded list of tasks and variables in the integration, along with task status and variable payloads.