Getting Started with Apigee Integration

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

This quickstart shows you how to create a sample integration using Apigee Integration. The steps below 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 product list from a URL endpoint, transform the data into a usable format, and send the resulting list in an email, all from within the Integration designer.

Before you begin

Before beginning the quickstart, confirm your Apigee login credentials and organization details. This information is required to access the Apigee Integration feature within the designer.

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.

Configure a 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 the 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. Drag the API Trigger element to 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. Drag the Call REST Endpoint element to 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://apigee-pm4-prod.apigee.net/v1/hipsters/products. This endpoint returns an array of product objects, each with an id, name, description, picture, price, and array of categories.
      • HTTP method: Select GET using the dropdown list.
      • Additional HTTP headers: Enter any additional headers required to access the endpoint. For this quickstart:
        • Enter x-apikey in the HTTP header key field.
        • Enter H7WpkpvdCAC2jSffbmKpQLVduxC6nOO9 in the Value field.
    • 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.

    The completed configuration should match the figure below:

    Call REST Endpoint trigger

  4. 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 control points and edge line will turn yellow, as shown in the image below:

    integration designer showing edge connection

    The edge denotes the flow of control from the API Trigger to the Call REST Endpoint task.

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 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, follow these steps to create a mapping using the responseBody(Call REST Endpoint) as input:

    1. Drag the responseBody chip from the Variables list on the left side of the editor to the first Input field.
    2. Click + Add Function in the responseBody chip to view the drop-down list of available functions.
    3. You can apply a number of Data Mapping 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. Click the + Add function symbol on the responseBody variable to open the list of available functions. Use the following functions:
      • Select TO_JSON() to convert the responseBody string to JSON.
      • Click the + Add function symbol on the responseBody variable chip again to select and chain the GET_PROPERTY() function. This function will extract a property from the JSON payload. Pass in the products.name 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(products.name)
      • If you need to remove or delete a function, click the - symbol. This will remove the most recently added function.
    4. 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 JSONProdNameList.
      • Data Type: JSON
      • Check Use as an output of integration.
      • Click Create to create the variable and close the pane. The new JSONProdNameList variable will appear in the Variables list on the left side of the Data Mapping editor.
    5. In the Data Mapping Editor, click the X to save the mapping and close the editor.
    6. The completed mapping should appear as shown in the figure below:

      image of completed Data Mapping and variables

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

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 Email from Apigee Integrations.
    • Email body: Select the JSONProdNameList 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.

    The completed configuration should match the figure below:

    Email task config

  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.

Test the integration

To test the new integration:

  1. Click the Publish button in the integration designer toolbar. Publishing the integration activates the Test button in the toolbar.
  2. Click Test and then select API Trigger.
  3. 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 product name list 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:

["Vintage Typewriter", "Vintage Camera Lens", "Home Barista
Kit", "Terrarium", "Film Camera", "Vintage Record Player", "Metal Camping
Mug", "City Bike", "Air Plant"]

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.

Congratulations! You successfully configured and deployed an integration with Apigee Integration.

What's next