Get started with Apigee Integration

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

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

This quickstart shows you how to create a sample integration in Apigee Integration. The following steps describe how to configure the trigger, tasks, edges, variables, and data mappings required to run a complete integration.

In this quickstart, you will retrieve a the number of page views from a public API, transform the data into a usable format, and send the resulting list in an email, all from within the integration designer.

Enable integrations

To enable the integrations feature in Apigee, you can either create an evaluation (eval) org for trials or pay for the integrations if you have an Apigee subscription.

Enable integrations in an eval org

An eval org lets you try out the Apigee integrations feature without getting billed for the usage. To understand how to provision an eval org, see Provision an eval org. Use an eval org if your objective is only to explore and play with the integration feature, as the integrations created in an eval org have some limitations. For more information, see Comparing eval and paid organizations.

The eval org will already have the integrations and the connectors add-on enabled. The connectors add-on is required to access external data sources from your integrations. So after provisioning the eval org, you only have to enable the following APIs for the eval org, and you are good to use the integrations feature.

  • Cloud Integrations API (integrations.googleapis.com)
  • Connectors API (connectors.googleapis.com)

After enabling the APIs, you can start creating integrations. For more information, see the Create a new integration section.

Enable integrations in a paid org

If you want to use Apigee integrations without any limitations, you can pay for the integrations. Apigee Integration is available as an add-on service for your subscription. As a first step, contact Apigee support to add Integration and Connectors to your subscription. After adding them to your subscription, perform the following tasks:

  1. Enable the following APIs:
    • Apigee API (apigee.googleapis.com)
    • Cloud Integrations API (integrations.googleapis.com)
    • Secret Manager API (secretmanager.googleapis.com)
    • Connectors API (connectors.googleapis.com)

    For information on how to enable the APIs, see Enabling services.

  2. Enable the Integration and the Connectors add-ons for your Apigee organization.
    • If you are creating a new organization to use for Integration, run the following command:

      curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" -d '{"name":"${ORG_ID}", "analyticsRegion":"us-west1", "authorized_network":"${NETWORK_ID}", "runtimeType":"CLOUD", "runtimeDatabaseEncryptionKeyName":"${ENCRYPTION_KEY_NAME}", "addonsConfig": {"integrationConfig": {"enabled": true}, "connectorsPlatformConfig":{"enabled":true}}}' "https://apigee.googleapis.com/v1/organizations?parent=projects/${PROJECT_ID}"
    • If you are using an existing organization, run the following command:

      curl -H "Authorization: Bearer $TOKEN" -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}:setAddons" -XPOST -d '{"addonsConfig":{"integrationConfig":{"enabled":true},"connectorsPlatformConfig":{"enabled":true}}}'

    To verify if the add-ons are successfully enabled, run the following command:

    curl -H "Authorization: Bearer $TOKEN"  -H "content-type:application/json" "https://apigee.googleapis.com/v1/organizations/${ORG_ID}"

    Running the command, should display a message similar to the following:

    {
      "name": "Test....",
      "createdAt": "1615483867669",
      "lastModifiedAt": "1615483873468",
      …...
      "addonsConfig": {
        "integrationConfig": {
          "enabled": true,
        "connectorsPlatformConfig": {
          "enabled": true
        }
      }
    }
  3. Grant the required IAM roles and permissions to the Apigee Service Agent (service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com).

    To grant the permissions, do the following:

    1. In the Cloud console, go to the IAM and Admin > IAM page.
    2. Select Include Google-provided role grants. This displays the Apigee Service Agent along with other principals.
    3. Grant the required roles to the Apigee Service Agent.
    4. Click Save.
  4. Grant the following roles to your Google Cloud project:
    • Editor
    • Apigee Organization Admin
    • Apigee Integration Admin
    • Connector Admin

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. Select an existing integration or create a new integration by clicking CREATE INTEGRATION.

    This opens the integration in the integration designer page.

  4. In the integration designer, click +Add a task/trigger > Tasks to view the list of available tasks.
  5. Select an existing integration or click CREATE INTEGRATION.
  6. Enter a name and description in the Create Integration dialog. For example, my-test-integration.
  7. Select a Region for the integration from the list of supported regions.
  8. Click Create to open the Integration designer.

Add and configure an API trigger

Triggers are required to start the sequence of tasks that make up an integration. Any available trigger can be used to start an integration. For this quickstart, use the API trigger.

To configure the API trigger:

  1. In the Integration designer, select Add a task/trigger > Triggers to display a list of available triggers.
  2. Click and place the API trigger element in the integration designer.
  3. Click the API trigger element on the designer to open the trigger configuration pane.
  4. Apigee Integration automatically populates the trigger Label, Trigger name, and Trigger ID. The Trigger ID is machine-generated and you cannot edit the value. However, you can edit the value of the Label and the Trigger name properties.

    Changes to the properties save automatically.

Add and configure tasks

A task is an executable set of steps that can take variables as inputs and generate variables as outputs. As with triggers, any available task can be used in an integration. This quickstart uses the Call REST Endpoint, Data Mapping, and Send Email tasks. Configuration details for each task are described in the steps below.

Configure the Call REST Endpoint task

To configure the Call REST Endpoint task:

  1. Select Add a task/trigger > Tasks to display a list of available tasks.
  2. Click and place the Call REST Endpoint element in the integration designer.
  3. Click the Call REST Endpoint element on the designer to open the task configuration pane. Set the following properties:
    • Label: Enter a custom name for this task. For example, enter Call REST Endpoint Task.
    • Authentication: For this quickstart, an authentication profile is not required. For more information on using authentication profiles for other use cases, see Create authentication profiles in Apigee Integration.
    • Task Input: Enter the details for calling the REST endpoint. The information entered here is used as input for the Call REST Endpoint task. Enter the following information:
      • Endpoint base URL: Enter https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/en.wikipedia/desktop/user/Tree/monthly/20201001/20201031. This public API from wikimedia.org returns the number of page views for an article named Tree for a given month.
      • HTTP method: Select GET using the dropdown list.
    • Task Output: Here Apigee Integration populates three variables to hold the response data output of calling the REST endpoint:
      • responseHeader(Call REST Endpoint): This variable holds the response header data associated with the Call REST Endpoint task. The variable data is of type String (STR).
      • responseBody(Call REST Endpoint): This variable holds the response body data associated with the Call REST Endpoint task. The variable data is of type String (STR).
      • responseStatus(Call REST Endpoint): This variable holds the response status data associated with the Call REST Endpoint task. The variable data is of type String (STR).
    • View the details of each variable by clicking the variable name in the task configuration pane. For this quickstart, leave the default values for each of these variables.
    • The remaining fields should contain the following default values:
      • Follow redirects: True
      • Throw error: False
      • Retry on Failure
        • When integration is run synchronously: None
        • When integration is run asynchronously: None

    Changes to the properties save automatically.

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 of the task.
  4. Click Open Data Mapping Editor.

    The Data Mapping Editor lets you to map input variables to the desired output variables, using the available transformation 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, create a mapping using the responseBody(Call REST Endpoint) as input:

    1. Drag the responseBody variable from the Variables list on the left side of the Data Mapping Editor to the first Input field.
    2. Click + (Add a function) in the responseBody variable chip to view the drop-down list of available functions.
    3. You can apply a number of functions to transform the data in the input variable.

      In this case, you can convert the payload to JSON and then iterate over the response array to get the list of product names required for your email notifications.

      • Select TO_JSON() to convert the responseBody string to JSON.
      • Click + (Add a function) again in the responseBody variable chip to select and chain the GET_PROPERTY() function.

        This function will extract a property from the JSON payload. Pass in the items property as the parameter for this function. This will return a list of ONLY the product names, with no other product information. Your function should read as follows:

        responseBody(Call REST Endpoint).TO_JSON().GET_PROPERTY(items)
      • If you need to remove or delete a function, click the - symbol.
    4. Click the first field in the Output column to create a new output variable to hold the value of the transformed data. Complete the following fields:
      • Name: enter JSONList.
      • Data Type: JSON
      • Select the Use as an output of integration checkbox.
      • Click Create to create the variable and close the pane. The new JSONList variable will appear in the Variables list on the left side of the Data Mapping editor.
    5. 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 Email from Apigee Integration.
    • Body in Plain Text: Select the JSONList variable created earlier in the Data Mapping task.
    • The remaining options can be left in the default configuration.

    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 API trigger element to the Call REST Endpoint element by hovering over a control point on the API trigger element, then clicking and dragging a line to a control point on the Call REST Endpoint task element. The edge denotes the flow of control from the API trigger to the Call REST Endpoint task.
  2. Add an edge connection from the Call REST Endpoint element to the Data Mapping element by hovering over a control point on the Call REST Endpoint 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 Call REST Endpoint task to the Data Mapping task.
  3. 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 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 completed edge connection

Test the integration

To test the new integration:

  1. Click Test in the integration designer toolbar, and then select the API Trigger.
  2. In the Confirm Publish and Test dialog, click Publish & Test.

For more information about testing, see Testing integrations.

Upon successful completion, the integration sends an email with the JSON values 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 contain a body similar to the following:

[{
   "project": "en.wikipedia",
   "article": "Tree",
   "granularity": "monthly",
   "timestamp": "2020100100",
   "access": "desktop",
   "agent": "user",
   "views": 33828.0
}]

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.