Quickstart
For this Quickstart, we are going to build integrations for a cool new SaaS app called MailMonkey - an email campaign manager that integrates with Salesforce. You can see the final amp.yaml
file on Github.

Define the integrations
To make MailMonkey interoperate seamlessly with our customers' Salesforce, we want to create 3 integrations:
- Read Contacts and Leads: An integration which pulls all Contacts and Leads from Salesforce into MailMonkey.
- Create Leads: An integration which creates a new Lead in Salesforce whenever somebody replies to to a MailMonkey email campaign.
- Subscribe to Lead Conversions: An integration which inserts Salesforce Leads into the "customer" audience segment in MailMonkey whenever a Lead's status becomes "converted" in Salesforce.
We'll use the amp CLI's init command to generate the basic file structure for our integrations:
amp login
amp init
After answering a few questions, we'll get a new folder called amp
, with a file inside called amp.yaml
, this is where we will define our integrations, and it will look pretty bare bones to start with.
Read Contacts and Leads
Our first integration will have Read Actions. We'll read 2 standard objects from Salesforce: contacts and leads. We'll also define 2 Destinations for these objects, which are 2 Postgres tables, one for each object. (Alternatively, we could have decided to use an Ampersand-hosted data store and make API requests to retrieve our data.)
integrations:
- name: readContactsAndLeads
displayName: Read Contacts and Leads
api: salesforce
actions:
- type: read
schedule: every 12 hours
standardObjects:
- objectName: contact
destination: contactTable
# Always read these fields
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
# Customer can decide during set-up if they want us to read these fields
optionalFields:
- fieldName: salutation
- objectName: leads
destination: leadsTable
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
- fieldName: isConverted
# ...
destinations:
# Sync Contacts to a Postgres table
- name: contactsTable
type: postgres
tableName: SalesforceContacts
# Sync Leads to a Postgres table
- name: leadsTable
type: postgres
tableName: SalesforceLeads
Create Leads
Our second integration will have Write Actions. We want to insert new leads into our customer's Salesforce. As soon as we deploy our integration using the Ampersand CLI. Ampersand will expose an API endpoint with the URL of https://store.withampersand.com/project/<ampersand-project-id>/create-account
. MailMonkey's application backend will make an API call to it to create the new lead whenever there's an email reply that we detect.
- name: createLeads
displayName: Create Leads
api: salesforce
actions:
- type: write
standardObjects:
# Create a new lead in Salesforce whenever we make an API request.
- objectName: lead
mode: insert
# Specify the how the URL that Ampersand exposes to you should be named.
endpoint: create-account
Subscribe to Lead Conversions
Our third integration will have Subscribe Actions. We want to watch for updates to the isConverted
field of Salesforce leads, and Ampersand will make a POST request to our webhook whenever that happens. We'll define a Destination for our webhook. Once our webhook receives a request, our application code will add that lead to a customer audience segment within MailMonkey.
- name: subscribeToLeadConversions
displayName: Subscribe to Lead Conversions
api: salesforce
actions:
- type: subscribe
standardObjects:
- objectName: lead
destination: leadConvertedWebhook
event: update
# We watch for changes on these fields
watchFields:
- fieldName: isConverted
# We also want the values of these fields to be sent to our webhook.
additionalFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
destinations:
# Webhook that Ampersand should make requests to
- name: leadConvertedWebhook
type: webhook
url: webhooks.mailmonkey.com/salesforce-lead-converted
Deploy the completed config file
You can see the final amp.yaml
file on Github.
Once we are happy with the definition of our integrations, we can deploy them with the amp CLI:
amp deploy
Embed UI components
Next, we will use Ampersand's react library to embed ready-made UI components into our app, so that our customers can start using our shiny new integrations! We'll use the InstallIntegration
component for the auth flow and configuration steps. Check out Embed UI components for more details on this component and other components to help your users set up and manage their integrations.
We decide that we want each integration to have its own page, and we are going to use react-router-dom
to help us with page routing.
Here's a simplified version of what our frontend code would look like:
import { ChakraProvider } from '@chakra-ui/react';
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';
import { Routes, Route } from 'react-router-dom';
const options = {
projectId: 'PROJECT_ID', // Your Ampersand project ID.
apiKey: 'API_KEY',// Your Ampersand API key.
};
function App() {
return (
// Wrap your app with AmpersandProvider.
<AmpersandProvider options={options}>
// Wrap the app in ChakraProvider if you're also using it to style
// the rest of your app, otherwise wrap individual components.
<ChakraProvider>
<Routes>
<Route path = '/first-integration' element =
{<InstallIntegration
// The name of the integration from amp.yaml
integration = "readContactsAndLeads"
// The ID that your app uses to identify this end user.
userId = {userId}
// The ID that your app uses to identify the user's company, org, or team.
groupId = {groupId}
/>}
/>
<Route path = '/second-integration' element =
{<InstallIntegration
integration = "createLeads"
userId = {userId}
groupId = {groupId}
/>}
/>
<Route path = '/third-integration' element =
{<InstallIntegration
integration = "subscribeToLeadConversions"
userId = {userId}
groupId = {groupId}
/>}
/>
</Routes>
// Rest of the MailMonkey app goes here
</ChakraProvider>
</AmpersandProvider>
)
}
Updated 5 months ago