Quickstart

For this Quickstart, we are going to build integrations for a cool new app called MailMonkey - an AI-powered 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.

Claim your domain

Claim your domain to let teammates auto-join your organization when they sign up. You can do this as an org owner in the dashboard under org settings. Once enabled, anyone with a @yourcompany.com email will automatically be added to your org.

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:

1. Read Contacts and Leads: pull all Contacts and Leads from a customer’s Salesforce into MailMonkey.
2. Create Leads: create a new Lead in Salesforce whenever somebody replies 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. Later on, you can refer to the Manifest Reference for a comprehensive guide to this file.

Read Contacts and Leads

Our integration will have a Read Actions. We’ll read 2 objects from Salesforce: contacts and leads.

YAML

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
          backfill:
            defaultPeriod:
              fullHistory: true
          # 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
          backfill:
            defaultPeriod:
              fullHistory: true
          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.

YAML

...
    # 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. If you don’t already have a frontend codebase, you can use our Starter Project.

Here’s a simplified version of what our frontend code would look like:

TypeScript

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>
  )
}