Getting Started with Apigee Integration and Cloud Pub/Sub

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

This tutorial shows you how to create a sample integration using Apigee Integration and the Cloud Pub/Sub Trigger. The steps below describe how to configure the Cloud Pub/Sub Trigger, tasks, variables, and data mappings required to run a complete integration. In this tutorial, 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

Before beginning the tutorial, follow these steps:

  • Confirm your Apigee login credentials and organization details. This information is required to access the Integration feature within the designer.
  • Create a new Cloud Pub/Sub topic. This tutorial imagines 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 tutorial test the integration's ability to listen to the topic and perform tasks when triggered.

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

    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 this tutorial, enter temperaturesensor
    4. Click Save.

Create a new integration

To create a new integration, perform the following steps:

  1. Go to the Apigee UI and sign in.
  2. Select your organization using the drop-down menu in the upper left corner of the UI.
  3. Click Develop > Integrations.
  4. Click CREATE NEW.
  5. Enter a name and description in the Create Integration dialog. For example, my-test-integration.
  6. Select a Region for the integration from the list of supported regions.
  7. 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, click + Add a task/trigger to view the task and trigger selection dialog.
  2. Click Triggers to view the available triggers.
  3. Drag 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

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. Drag the Data Mapping element to 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 tutorial, follow these steps to create a mapping using the CloudPubSubMessage as input:

    1. Drag the CloudPubSubMessage chip from the Variables list on the left side of the editor to the first Input field.
    2. Click + Add Function in the CloudPubSubMessage 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 + to chain an additional mapping function.
    5. Click SUBTRACT from the drop-down list and enter a parameter of 273.15 to convert the Kelvin temperature to degrees Celsius.
    6. Click the first field in the Output column to create a new variable to hold the value of the transformed data. Complete the following fields:
      • Name: enter TemperatureInCelsius.
      • Check Use as an output of integration.
      • Click Create to create the variable and close the pane. The new Temperature in Celsius variable will appear in the Variables list on the left side of the data mapping editor.
    7. Drag the Temperature in Celsius chip from the Variables list to the second field in the Input column.
    8. Click + Add Function in the Temperature in Celsius chip 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 field in the Output column to create a new variable to hold the value of the transformed data. Complete the following fields:
      • Name: enter TemperatureInCelsiusString.
      • Blank default value means...: Select Empty String.
      • Check Use as an output of integration.
      • 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 of completed data mapping and variables

    12. Click the X in the data mapping editor save the mapping and close the editor.
  5. 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. The edge denotes the flow of control from the Cloud Pub/Sub Trigger task to the Data Mapping task.

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.

    For this step, use the Send Email task.

  2. Drag the Send Email element to the integration designer.
  3. Click the Send Email element on the designer to open the configuration pane of the task. Set the following properties:
    • Recipients: Enter your email address. You will use this email to confirm the successful completion of the integration.
    • Subject: Enter Temperature in Celsius.
    • Email body: Select the TemperatureInCelsiusString 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.
  4. 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. The control points and edge line will turn yellow. The edge denotes the flow of control from the Data Mapping task to the Send Email task.

    Upon completion of this step, the integration is complete and should appear as shown in the figure below:

    image of integration trigger and tasks

Test the integration

To test the new integration:

  1. Click the Publish button in the integration designer toolbar.
  2. Go to the Pub/Sub topics page in the Cloud console.

    Go to the Pub/Sub topics page

  3. Search for and then select the temperaturesensor topic you created in a previous step.
  4. From the topic detail page, click + Publish Message to open the Publish Message configuration pane.
  5. 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.
  6. 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 ID
    • 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, as shown in the figure below:

    image of integration logs

Congratulations! You successfully configured and deployed an integration with Apigee Integration and a Cloud Pub/Sub Trigger.

What's next