Getting Started with Apigee Integration and Salesforce

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

This tutorial shows you how to use Apigee Integration to detect and evaluate data changes in Salesforce and send key information about the changes to other data sources.

In this example, data changes to a Salesforce opportunity trigger an Apigee Integration. The integration extracts the status of the opportunity. If the status is "closed," the integration extracts opportunity details and writes the data to a Cloud SQL instance. If there is a data change, but the opportunity remains open, the integration sends a message to a Pub/Sub topic identifying the opportunity as remaining open.

The steps below describe how to configure the trigger, tasks, authentication profiles, edges, variables, and data mapping required to run a successful integration.

Before you begin

Before beginning the tutorial, confirm your Apigee login credentials and organization details. This information is required to access the 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 Integration designer.
  3. Click Develop > Integrations.
  4. Click CREATE NEW.
  5. Enter a name and description in the Create Integration dialog.
  6. 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. This tutorial uses the Salesforce Trigger to trigger an integration when Salesforce objects are changed (Change Data Capture).

To configure the Salesforce Trigger:

  1. In the integration designer, select Add a task/trigger > Triggers to display a list of available triggers.
  2. Drag the Salesforce CDC element to the integration designer.
  3. Click the Salesforce Trigger element on the canvas to open the configuration pane of the trigger.
  4. Configure the following fields:
    • Label (optional): Enter a custom name for the trigger.
    • INPUTS: Enter the following values:
      • Salesforce instance: the name of your Salesforce instance
      • Salesforce channel: Click + Add new Salesforce channel to open the Add Salesforce channel dialog. Enter the following values:
        • Salesforce channel alias: For example, opportunity
        • Description: For example, opportunity
        • Salesforce channel topic: For example, /data/OpportunityChangeEvent
        • Click Save.
      • Operation: Select Update from the Operation dropdown list
    • TRIGGER OUTPUT: Apigee Integration automatically populates this field with the CDCTriggerPayload variable. To see the details of the variable, click the CDCTriggerPayload element to open the Edit Variable dialog.
  5. Changes to the properties are saved 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 tutorial uses the Data Mapping, Insert Row into Cloud SQL, and Publish Cloud Pub/Sub Message tasks. Configuration details for each task are described in the steps below.

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

    1. Click + Add Mapping.
    2. Click + Build expression in the Input field.
    3. If you wan to select a variable, click Variable and begin typing the variable name. If the variable is not available, click + Add new variable to enter the name and data type of the new variable. You can also choose to enter a value by clicking on Value.

    4. Configure the following Input and Output fields.
    5. Input Output
      CdcTriggerPayload.snapshot (JSON) Opportunity (JSON)
      Opportunity.IsClosed (JSON) IsClosed (Boolean)
      Opportunity.Name (JSON) SFOpportunityName (String)
      Opportunity.AccountId (JSON) SFAccountID (str)
      Opportunity.Amount (JSON) SFAmount (Double)
      Opportunity.Id (JSON) SFId (String)
      SFId(CONCAT(* is still open) (String) CPSMessage (String)
    6. Click Save and Close to save the mapping and close the data mapping editor.
    7. Add an edge connection from the Data Mapping element to the Salesforce Trigger 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 Salesforce Trigger task to the Data Mapping task.

    Configure the Insert Row into Cloud SQL task

    To configure the Insert Row into Cloud SQL task:

    1. Select Add a task/trigger > Tasks in the integration designer to display the list of available tasks.

      For this step, use theInsert Row into Cloud SQL task.

    2. Drag the Insert Row into Cloud SQL element to the integration designer.
    3. Click on the Insert Row into Cloud SQL element on the designer to open the configuration pane of the task. Set the following properties:
      • Label (optional): Enter a custom name for the task.
      • Authentication: For this tutorial, an authentication profile is required to your Cloud SQL instance. If the profile already exists, select it from the Authentication profile to use drop-down list. If you have not configured an authentication profile for the Cloud SQL instance, click + Add new authentication profile to open the Authentication profile dialog. Follow the steps outlined in Create Authentication profiles in Apigee Integration to configure a profile using your Cloud SQL credentials.
      • TASK INPUT: Enter the details required to call connect to the Cloud SQL instance:
        • Instance connection name: Connection name in the format PROJECT: LOCATION:INSTANCE
        • Database: The name of the database you want to use.
        • Table name: The name of the table where you want to insert a row.
        • Row: Values are in the form of key-value pairs, where the key is the column name, and the value is the corresponding column value. You can enter more than one key-value pair.
      • TASK OUTPUT: Here Apigee Integration populates a Boolean variable to hold the status of the task, that is, whether or not the row was inserted.
      • The remaining fields should contain the following default values:
        • Follow redirects: True
        • Throw error: False
        • SYNCHRONOUS ERROR HANDLING STRATEGY: Unspecified
        • ASYNCHRONOUS ERROR HANDLING STRATEGY: Unspecified
      Changes to the properties are saved automatically.
    4. Add an edge connection from the Data Mapping element to the Insert Row into Cloud SQL element by hovering over a control point on the Data Mapping element, then clicking and dragging a line to a control point on the Insert Row into Cloud SQL task element. The control points and edge line will turn yellow.

      The edge denotes the flow of data from the Data Mapping task to the Insert Row into Cloud SQL task. Because Cloud SQL should only be updated if the Salesforce opportunity has the status "closed", an Edge Condition is required for the edge. To add an Edge Condition:

      • Click on the edge line between the Data Mapping element and the Insert Row into Cloud SQL element to open the Edge dialog.
      • In the label field, enter Closed.
      • In the EDGE CONDITION field enter $IsClosed$=True
      Changes to the properties are saved automatically.

    Configure the Publish Cloud Pub/Sub message task

    To configure the Publish Cloud Pub/Sub message task:

    1. Select Add a task/trigger > Tasks in the integration designer to display the list of available tasks.

      For this step, use the Publish Cloud Pub/Sub message task.

    2. Drag the Publish Cloud Pub/Sub message element to the integration designer.
    3. Click on the Publish Cloud Pub/Sub message element on the canvas to open the configuration pane of the task. Set the following properties:
      • Label (optional): Enter a custom name for the task.
      • Authentication: For this tutorial, an authentication profile is required to connect to Pub/Sub. If the profile already exists, select it from the Authentication profile to use drop-down list. If you have not configured an authentication profile for Pub/Sub, click + Add new authentication profile to open the Authentication profile dialog. Follow the steps outlined in Configuring Authentication to configure a profile using your Pub/Sub credentials.
      • TASK INPUT: Enter the details required to publish a message to Pub/Sub:
        • Topic: The name of the Pub/Sub topic where the message will be published. In the format projects/PROJECT/topics/topic
        • Message: The message you want to publish to the topic. Select the CPSMessage output variable configured in the Data Mapping task.
        • Attributes: Can be left empty
        • Ordering Key: Can be left empty
      • TASK OUTPUT: Here Apigee Integration populates a String variable to hold the response data of the task.
      • The remaining fields should contain the following default values:
        • Follow redirects: True
        • Throw error: False
        • SYNCHRONOUS ERROR HANDLING STRATEGY: Unspecified
        • ASYNCHRONOUS ERROR HANDLING STRATEGY: Unspecified
      Changes to the properties are saved automatically.

    Test the integration

    To test the new integration:

    1. Click the Publish button in the integration designer toolbar.
    2. Test the Cloud SQL task by logging in to the Salesforce instance and changing an opportunity status to "closed."
    3. Test the Pub/Sub task by logging in to the Salesforce instance and changing another detail about the opportunity, but leave the status of the opportunity "open."

    To verify the success of your integration:

    • Go to the Cloud SQL page.

      Go to Cloud SQL

      Check your database and Cloud SQL logs to confirm the insertion of the new row.
    • Go to the Pub/Sub page.

      Go to Pub/Sub

      Select your Pub/Sub topic and then click View messages to confirm receipt of the message sent by the integration.
    • Inspect the Apigee Integration logs to view the status 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.