Read Salesforce Record task

Announcement: Application Integration is now available for your Google Cloud project. You can now use both Apigee Integration and Application Integration within the same Google Cloud project. Learn more

There are two types of tasks available in Apigee Integration - Core tasks and Connector tasks. The Read Salesforce Record task is a Connector task that lets you read an existing Salesforce object in your Salesforce instance.

Before you begin

This section outlines the steps required to connect and configure a Salesforce instance to use Change Data Capture (CDC) or Platform events to stream changes to your Apigee Integration in a pub/sub manner. The following steps must be completed before configuring any Salesforce-related task or trigger in Apigee Integration:

• Set up an integration user
• Configure a permission set
• Set up a security token
• Create a connected app

Note: To complete these steps, system administration access to your Salesforce instance is required. If you do not have admin access, share these instructions with your Salesforce Administrator.

This tutorial provides in-depth instruction, but we recommend that you have some understanding of Salesforce configuration options. Salesforce provides detailed Developer Documentation to help you get started.

Set up an integration user

Note: If you already have an integration user and you know the password, you can skip to the next step. If you need to reset the password, see Step 6 below.

Set up an Integration user with the following steps:

1. Log in to your Salesforce instance with your sysadmin credentials.
2. Click the Gear icon and then select Setup, as shown in the image below:
3. Click Users > Users from the Administration menu.
4. From the Users pane, select the New User button.
5. In the User Edit dialog, fill in the following details:
   1. First Name: First name of the integration user.
   2. Last Name: Last name of the integration user.
   3. Email Address: Email for the integration user. Ideally, this should be a group email.
   4. Username: User name that complies with any org-level naming conventions.

      If you are creating a new integration user, use the following format: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      If you have an existing integration user, confirm that the username is entered here.

   5. Role: Select from the dropdown of options.
   6. User License: Enter Salesforce or, if using a trial org, enter Salesforce Platform.
   7. Profile: Select the permissions profile for integration users from the dropdown.

      We recommend assigning a profile with no permissions, to protect your integration user Salesforce access from unauthorized usage.

   8. Click Save.
6. To update the password for the new integration user, follow these steps:
   1. Click the Reset password(s) button on the Users pane. A password reset email is sent to the email address associated with the user.
      Note: Confirm that you have access to the email account associated with the integration user before triggering the reset password flow. In addition, if you have if you have SSO enabled for this user, you will not be able to reset the password. To enable the reset option, go to Profile > System Permissions and uncheck the option for SSO Login Enabled.
   2. Follow the reset password flow from the email account. Take note of the new password, as you will need it for a later step.

Configure a Permission Set

If you have already have access to a Permission Set that is appropriate for an integration user, you can skip this step and proceed to Set up a security token. Otherwise, follow these steps to configure a Permission Set for the integration user and the Salesforce object.

To configure a Permission Set for the integration user:

1. From the Setup menu, click Users > Permission Sets.
2. In the Permission Sets pane, click the New button.
3. In the Permission Sets dialog, enter the following details:
   • Label: Enter a name for the Permission Set.
   • License: Select Salesforce from the License dropdown.
   • Click Save.
4. From the list of Systemsetting options, scroll down and select System Permissions
5. On the System Permissions page, click the Edit button.
6. Scroll down the list of available permissions and select the API Enabled checkbox.

   The Api Only User permission is also required, but cannot be enabled until the required security token is reset. This permission is added in a later step.

7. (Optional) Scroll and select Modify All Data and View All Data, if applicable. These permissions are not required, but can be helpful if you want to automatically give the integration user access to new objects. We recommend only enabling these permissions for testing in a sandbox.
8. Scroll to the top of the permissions list and click Save.
9. Confirm your settings and click Save.

To configure the Permission Set for the Salesforce object:

1. Click Permission Set Overview to return to the main Permissions Set configuration page.
2. Select Object Settings from the Apps section of the Permissions Set pane.
3. Scroll down and select the Salesforce object(s) requiring a Permission Set. This example uses the Opportunity object.
   NOTE: CDC only supports a subset of standard Salesforce objects. To learn more, see: Change Event Object Support.
4. Click the Edit button on the object detail page.
5. Select the checkboxes for record types If you know which record types are required select those. If you don't know which record types are required, select them all.
6. Select the checkboxes for the Object Permissions to enable. Read and View All are recommended.
7. Grant Read Access or Edit Access for each object field by selecting the corresponding checkbox.
   Note: Write access is not required for use with CDC.
8. Scroll to the top of the page and click Save.

Set up a Security Token

If you have created a security token for the integration user previously, and reset the password, an email with a new security token is sent automatically. You can use the new token and skip to Create a connected app.

Otherwise, use the following steps to reset the security token for the integration user:

1. Log in to Salesforce as the integration user, using the username and password set in a previous step.
2. From the main menu, click the profile picture, then click Settings.
3. From the Settings menu, select Reset My Security Token to open the Reset Security Token pane.
4. Click the Reset Security Token button.
5. Check the email account associated with the integration user for an email containing the new security token. Take note of the new security token, as you will need it for a later step.
6. (Optional) Enable the Api User Only permission in System Permissions for your permission set, as described in Configure a permission set above.

Create a Connected App

System administration permission is required to set up a Connected App. If you are currently logged in as the integration users, make sure to log out and then log in again as sysadmin.

Follow these steps to set up a Connected App:

1. Click the Gear icon and then select Setup.
2. From the Setup menu, search for and select App Manager, as shown in the image below:
3. Click New Connected App.
4. In the configuration pane, provide the following details:
   • Connected App Name: Enter a name for your connected app.
   • API Name: Enter the name of the API.
   • Contact email: Enter an email for your connected app, ideally a group email alias.
   • API (Enable OAuth Settings): Select Enable OAuth Settings. Then, set the following:
     1. (Optional) Callback URL: This is only required if you want an external service to perform validation. If you do choose to provide a callback, make sure to include the http(s):// prefix.
     2. Selected OAuth Scopes: Select:
        • Access and manage your data (api)
        • Perform requests on your behalf at any time (refresh_token, offline_access)
5. Click Save.
   Note: Your newly created connected app will not work for the initial 2-10 minutes after creation.
6. Click Continue.
7. A consumer secret and a consumer key are displayed on the next page. Note these values, as they will be used when setting up the Auth Module for Apigee.
8. Click the Manage button.
9. Once on the Connected App Detail page, click the Edit Policies button.
10. In the OAuth Policies section, change the value in the Permitted Users dropdown to Admin approved users are pre-authorized.
11. Click Save.
12. Scroll to the Profiles and Permission Sets section of the page to select the profile or Permission Set you want to apply to the connected app.
    You can select either a profile or a Permission Set, or a mixture of both, which will allow users with either the correct profile or Permission Set to access the connected app.
13. Select the desired profile or Permission Set.
14. Click Save.

Authentication

To use this task, you have to set up an authentication profile with the OAuth 2.0 client credentials. Apigee Integrations uses the authentication profile to connect to the Salesforce instance. To create an authentication profile, perform the following steps:

1. In the editable properties of the task, click +New authentication profile to open the Authentication profile dialog.
2. Set the following properties:
   • In the Authentication type, select OAuth 2.0 resource owner password credentials.
   • Token endpoint:
     • For sandbox, enter https://test.salesforce.com/services/oauth2/token
     • For production, enter https://login.salesforce.com/services/oauth2/token
   • Client ID: Enter the unique identifier of the client.

     The client ID is the connected app's consumer key. You can find the consumer key in the connected app's Manage Connected Apps page or from the connected app's definition.

   • Secret: Enter the client secret.

     The client secret is the connected app's consumer secret. You can find the consumer secret in the connected app's Manage Connected Apps page or from the connected app's definition.

   • Scope(s): Scope of the access token.

     Scopes allow you to specify access permissions for users. You can specify multiple scopes separated by a space.

   • Username: Username for authentication.
   • Password: User password.
   • Request types: Select any one of the following values:
     • Query parameters
     • Request body

     The type of request you select should be supported by the Salesforce instance.

   • Token parameters: Request parameters required to get the token.
   • Authentication profile name: Name of the authentication profile.
   • Authentication profile description: Description of the authentication profile.
   • SSL Certificate: Upload the SSL/TLS certificate and the corresponding Private key.

     If the private key has a passphrase, enter the passphrase.

3. Click Save.

Configure the Read Salesforce Record task

To configure the Read Salesforce Record task:

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. Search for or select the integration to edit from the Integrations list and click to open the integration designer.
5. Click +Add a task/trigger > Tasks to view the list of available tasks.
6. Drag the Read Salesforce Record element to the integration designer.
7. Click the Read Salesforce Record element on the designer to view the Read Salesforce Record task configuration pane.
8. Choose the Authentication profile you created earlier from the Authentication dropdown.
9. Configure the remaining fields using the configuration properties of the task.
10. Changes to the properties are saved automatically.

Configuration properties

The following table describes the configuration properties of the Read Salesforce Record task.

Property	Data type	Description
Salesforce domain	String	Name of the Salesforce instance to which you want to connect. The Salesforce domain is available in the Salesforce instance URL. For example, INSTANCE_NAME.my.salesforce.com
Salesforce API version	String	Current API version in your Salesforce instance. The current API version is available in your Salesforce instance under Setup > API > Generate Partner WSDL.
Object Name	String	Name of the Salesforce object that you want to read.
Record ID	String	ID of the record to be updated. The ID value is automatically created when you insert a record. The ID value uniquely identifies the record and does not change over the lifetime of the record.
Record	String	Return value of the task. If the read operation is successful, this variable contains the details of the Salesforce object that is read.

Retry on failure

You can configure various retry strategies to handle errors in a task. The retry strategies allow you to specify how to rerun the task in case of an error. For more information, see Error handling strategies.

Considerations

Quota limitations in your Salesforce instance might impact the use of this task. Speak to your Salesforce Admin to ensure that your integration design is compatible with your Salesforce quota.