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.
Create an Ampersand org and project
Sign up for an Ampersand account, and then follow the steps on the screen to create an org and then a project. Each org can have multiple projects, this is helpful for separating development and production environments.
Create a provider app
We’ll first set up a Salesforce Connected App and put the Client ID and Client Secret inside of Ampersand Dashboard. See the Salesforce guide for more information.
Create a destination
Next, we create a webhook destination for Ampersand to send data that it reads from Salesforce. See Destinations for more details.
Define the integrations
To make MailMonkey interoperate seamlessly with our customers’ Salesforce, we will create an integration which will:
- Read Contacts and Leads: pull all Contacts and Leads from a customer’s Salesforce into MailMonkey.
- Create Leads: create a new Lead in Salesforce whenever somebody replies to to a MailMonkey email campaign.
Let’s create a folder called source, with a file inside called amp.yaml, this is where we will define our integration.
Read Contacts and Leads
Our integration will have a Read Actions. We’ll read 2 objects from Salesforce: contacts and leads.
specVersion: 1.0.0
integrations:
- name: mailmonkey-salesforce
displayName: MailMonkey Salesforce Integration
provider: salesforce
read:
objects:
- objectName: contact
destination: contactWebhook
schedule: "*/30 * * * *" # every 30 minutes
# Always read these fields
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
# Customer can decide if they want us to read these fields.
optionalFields:
- fieldName: salutation
- objectName: lead
destination: leadsWebhook
schedule: "*/30 * * * *" # every 30 minutes
requiredFields:
- fieldName: firstName
- fieldName: lastName
- fieldName: email
- fieldName: isConverted
# Allow the customer to pick a field to map to priority score
- mapToName: priority
mapToDisplayName: Priority Score
prompt: Which field do you use to track the priority of a lead?
# All other fields in a Lead are optional,
# Customers can pick from all of them.
optionalFieldsAuto: all
Create Leads
Next we will add a Write Action. We want to insert new leads into our customer’s Salesforce.
...
# Append to the integration definition from above.
write
objects:
# Create a new lead in Salesforce whenever we make an API request.
- objectName: lead
Once a customer installs our integration, MailMonkey’s application backend will make an API call to Ampersand to create the new lead whenever there’s an email reply that we detect.
Deploy the completed manifest
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 login
# Our amp.yaml file is located in a folder called source.
amp deploy source --project=my-project-id-or-name
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.
Here’s a simplified version of what our frontend code would look like:
import { AmpersandProvider, InstallIntegration } from '@amp-labs/react';
const options = {
project: 'my-project', // Your Ampersand project name or ID.
apiKey: 'API_KEY',// Your Ampersand API key, created in the Dashboard.
};
function App() {
return (
<AmpersandProvider options={options}>
<InstallIntegration
// The name of the integration from amp.yaml
integration = "readContactsAndLeads"
// The ID that your app uses to identify this end user.
consumerRef = {userId}
// The display name that your app uses for this end user.
consumerName = {userName}
// The ID that your app uses to identify the user's company, org, or team.
groupRef = {groupId}
// The display name that your app uses for this company, org or team.
groupName = {groupName}
/>
</AmpersandProvider>
)
}