Salesforce Extension

Version: 1.0.1

Access data in your Salesforce account. Insert, update, retrieve, and query data.

This content provides reference for configuring and using this extension.

Prerequisites

This content provides reference for configuring and using this extension. Before using the extension from an API proxy using the ExtensionCallout policy, you must:

  1. Create an RSA x509 private key/certification pair.

    You will use the private key (.key) as credentials when configuring the extension. You'll use the certificate (.crt) file when creating a connected app that will give the extension access to Salesforce.

    openssl req -x509 -sha256 -nodes -days 36500 -newkey rsa:2048 -keyout salesforce.key -out salesforce.crt
    
    
  2. Set up a connected app.

    A Salesforce connected app will provide access for the Salesforce extension. See the instructions below for setting up the app.

  3. Get the consumer key for the connected app. The extension will use this when authenticating with the app.

    1. In Salesforce setup, in the left navigation, go to Apps > App Manager.
    2. In the list, locate the connected app you created.
    3. From the dropdown at the right in the application's row, click View.
    4. Under API (Enable OAuth Settings), locate the Consumer Key and copy its value to a safe place for use when configuring the extension.

Set up a connected app for access by the extension

Before the Salesforce extension can access Salesforce, you'll need to create a Salesforce connected app through the extension can connect with Salesforce.

In Salesforce, a connected app provides a way for external applications to connect to Salesforce through APIs.

To set up a connected app

  1. Log in to Salesforce.
  2. Click the gear icon in the upper-right, then click Setup.
  3. In the navigation on the left, expand Apps > App Manager.
  4. In the App Manager page, click New Connected App.
  5. Under Basic Information, fill in the required fields. The values are for bookkeeping; they are not used by the extension.
  6. Under API (Enable OAuth Settings), select the Enable OAuth Settings check box.
  7. Although it isn't used by the extension, enter a Callback URL. You can use http://localhost/ or some other placeholder host.
  8. Select the Use digital signatures check box.
  9. Under Use digital signatures, click Choose File to locate and upload the salesforce.crt that you generated earlier.
  10. In the Selected OAuth Scopes section, add the following so they're under Selected OAuth Scopes:
    • Access and manage your data (api)
    • Perform requests on your behalf at any time (refresh_token, offline_access)
  11. Click Save. If there are any errors, you may need to re-generate and upload the salesforce.crt file.
  12. On the resulting app page, click Manage.
  13. On the App Manager page for the app you just created, click Edit Policies.
  14. Under OAuth policies, click the Permitted Users dropdown, then click Admin approved users are pre-authorized.
  15. Click Save.
  16. Back on the app page, under Profiles, click Manage Profiles.
  17. On the Application Profile Assignment page, select check boxes for the profiles representing users who will have access to this app.

    Be sure to select a profile that corresponds to the user whose username you'll use when configuring the extension. This should be a user who has permission to do the things you'll want to do with the extension.

    You can view the profile setting for the user in the Salesforce. In the Setup area, expand Users > Users, locate the user that the extension will represent, then locate their profile in the Profile column.

About Salesforce

Salesforce is a customer relationship management (CRM) platform. Customer Relationship Management helps companies understand their customers' needs and solve problems by better managing customer information and interactions — all on a single platform that’s always accessible from any desktop or device.

Actions

insert

Insert records as sObject types.

Syntax

<Action>insert</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "records":[ records-to-insert ],
  "allOrNone": true | false
}]]></Input>

Example

<Action>insert</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "records":[
    { "Name": "MyAccountName" }
  ],
  "allOrNone": true
}]]></Input>

Request parameters

Parameter Description Type Default Required
sobject The sObject type of records to insert. String None. Yes.
records Array of sObject records in JSON. Maximum: 1000. Array None. Yes.
allOrNone true to fail the entire update if any part of the update fails. Boolean false No.

Response

A results array with results from the insert operation.

{
  results: [
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
Property Description Type Default Required
results[*].id The sObject ID generated for the new record. String None. Yes.
results[*].success true if inserting that record succeeded. Boolean None. Yes.
results[*].errors Array of errors, if any, caught during execution. Array None. Yes.

update

Update salesforce records.

Syntax

<Action>update</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "records": [ records-to-update ],
  "allOrNone": true | false
}]]></Input>

Example

<Action>update</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "records":[
    { 
      "id":"0011U00000LQ76KQAT",
      "Name": "MyNewAccountName" 
    }
  ],
  "allOrNone": true
}]]></Input>

Request parameters

Parameter Description Type Default Required
sobject The sObject type of records to update. String None. Yes.
records Array of sObject records in JSON. Each record to update must include the record's ID value. Maximum: 1000. Array None. Yes.
allOrNone true to fail the entire update if any part of the update fails. Boolean false No.

Response

A results array containing results from the update.

{
  results: [
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
Parameter Description Type Default Required
results[*].id The sObject ID generated for the updated record. String None. Yes.
results[*].success true if inserting that record succeeded. Boolean None. Yes.
results[*].errors Array of errors, if any, caught during execution. Array None. Yes.

retrieve

Retrieve records as sObjects by their IDs. Returns all fields of the sObject type.

Syntax

<Action>retrieve</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "ids":[ IDs-of-records-to-retrieve ]
}]]></Input>

Example

<Action>retrieve</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "ids":["0011U00000LQ76KQAT"]
}]]></Input>

Request parameters

Parameter Description Type Default Required
sobject The sObject type of records to retrieve. String None. Yes.
ids Array of sObject IDs records to retrieve. Maximum: 1000. Array None. Yes.
allOrNone true to fail the entire operation if any part of the request fails. Boolean false No.

Response

A records array of sObjects represented as JSON. Note that all the properties of the objects are included in the JSON, even if the property value is null.

{
  records: [
    { sobject-json },
    { sobject-json }
  ]
}

querySOQL

Query Salesforce.com using Salesforce Object Query Language (SOQL).

Syntax

<Action>querySOQL</Action>
<Input><![CDATA[{
  "soql": soql-query-statement
}]]></Input>

Example

<Action>querySOQL</Action>
<Input><![CDATA[{
  "soql": "SELECT Id, Name FROM Account"
}]]></Input>

Request parameters

Parameter Description Type Default Required
soql SOQL statement to query with. String None. Yes.

Response

Results of the query.

{
  totalSize: 2,
  records: [
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76KQAT',
      Name: 'AccountName1'
    },
    {
      attributes: { attributes-of-record },
      Id: '0011U00000LQ76LQAT',
      Name: 'AccountName2'
    }
  ],
  done: true
}
Parameter Description Type Default Required
totalSize Number of records returned by the query. Integer None. Yes.
records Array of returned records as sObjects in JSON. Maximum: 1000. Array None. Yes.
done true if the query operation completed. Boolean None. Yes.

list

List Salesforce.com records. Returns all fields of the specified sObject type.

Syntax

<Action>list</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "limit": max-number-of-records,
  "offset": record-index-at-which-to-begin-response-set
}]]></Input>

Example

<Action>list</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "limit": 1000,
  "offset": 0
}]]></Input>

Request parameters

Parameter Description Type Default Required
sobject The sObject type of records to list. String None. Yes.
limit Maximum number of records to return. Integer 1000 No.
offset Offset for records to list. Integer 0 No.

Response

A records array containing listed sObjects as JSON.

{
  records: [
    { sobject-json },
    { sobject-json }
  ]
}

del

Delete records with the specified IDs.

Syntax

<Action>del</Action>
<Input><![CDATA[{
  "sobject": records-sObject-type,
  "ids":[ IDs-of-records-to-retrieve ]
}]]></Input>

Example

<Action>del</Action>
<Input><![CDATA[{
  "sobject": "Account",
  "ids":["0011U00000LQ76KQAT"]
}]]></Input>

Request parameters

Parameter Description Type Default Required
sobject The sObject type of records to delete. String None. Yes.
ids Array of sObject IDs for records to delete. Maximum: 1000. Array None. Yes.

Response

A results array containing results of the operation.

{
  results:[
    { id: '0011U00000LQ76KQAT', success: true, errors: [] },
    { id: '0011U00000LQ76LQAT', success: true, errors: [] }
  ]
}
Property Description Type Default Required
results[*].id sObject ID of the record specified. String None. Yes.
results[*].success true if the operation succeeded for the record. Boolean None. Yes.
results[*].errors Array of errors, if any, caught during execution. Array None. Yes.

getAccessToken

Get Salesforce.com API access token. Can be used to query REST APIs.

Syntax

<Action>getAccessToken</Action>
<Input><![CDATA[{}]]></Input>

Request parameters

None.

Response

The access token in JSON.

{
  "accessToken":"00D1U0000014m3hqswvoM22I5GTw9EJrztlZ8eSSka88Q",
  "scope":"api",
  "instanceUrl": "https://na85.salesforce.com",
  "id": "https://login.salesforce.com/id/00D1U0004564mutUAA/0051U43214qecVQAQ",
  "tokenType": "Bearer"
}
Property Description Type Default Required
accessToken The access token. String None. Yes.
scope Scopes within which the token provides access. String None. Yes.
instanceUrl URL for the instance used by the Salesforce org. String None. Yes.
id ID of the connected app. String None. Yes.
tokenType Type for the access token. String Bearer Yes.

Configuration Reference

Use the following when you're configuring and deploying this extension for use in API proxies.

Common extension properties

The following properties are present for every extension.

Property Description Default Required
name Name you're giving this configuration of the extension. None. Yes.
packageName Name of the extension package as given by Apigee Edge. None. Yes.
version Version number for the extension package from which you're configuring an extension. None. Yes.
configuration Configuration value specific to the extension you're adding. See Properties for this extension package None. Yes.

Properties for this extension package

Specify values for the following configuration properties specific to this extension.

Property Description Default Required
Authorization server URL The URL to use when getting authorization from Salesforce. Typically, this is https://login.salesforce.com None. Yes.
Connected app consumer key The consumer key provided by Salesforce for the connected app you created. See the instructions under Prerequisites for retrieving your consumer key. None. Yes.
Credential When entered in the Apigee Edge console, this is the contents of the salesforce.key file you generated in the steps above. When sent via the management API, it is a base64-encoded value generated from the salesforce.key file. None. Yes.
Username of the Salesforce user The username associated with the connected app you created. The Salesforce extension will use this to get authorization from Salesforce. None. Yes.