Apigee Integration with an API trigger

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.

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 this quickstart, enter the name my-test-integration and the description Integration for quickstart.

  5. Select a region for the integration.
  6. Click Create to open the integration editor.

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, do the following:

  1. In the integration editor, click Triggers to display a list of available triggers.
  2. Click and place the API trigger element in the integration editor.
  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, do the following:

  1. Select Tasks to display a list of available tasks.
  2. Click and place the Call REST Endpoint element in the integration editor.
  3. 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.

    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 about edges, see Edges.

  4. 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
      • Task should fail on HTTP Error: False
      • Error handling strategy
        • Strategy for synchronous executions: None
        • Strategy for asynchronous executions: None

    Changes to the properties save automatically.

Add and configure the Data Mapping task

To configure the Data Mapping task:

  1. Select Tasks to display a list of available tasks.
  2. Click and place the Data Mapping element in the integration editor.
  3. 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.
  4. Click on the Data Mapping task on the designer to open the configuration pane of the task.
  5. 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 pane to the first Input row.
    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) in the responseBody variable chip to select and chain the GET_PROPERTY() function.
      • To add the input parameter for GET_PROPERTY(), click Variable or Value and in Value enter items.

        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 Tasks in the integration editor to display the list of available tasks.
  2. Click and place the Send Email element in the integration editor.
  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.
  4. 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.

Verify the required edge connections

Verify that you've added edge connection between elements in your integration. The connection denotes the direction of the control flow from one element (task or trigger) to another. For more information about edges, see Edges.

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

image showing quickstart flow image showing quickstart flow

Test the integration

To test the new integration:

  1. Click Test in the integration editor toolbar.

    The Test Integration dialog appears.

  2. Click Test integration.

For more information about testing, see Test and publish 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 editor.
  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.