Concepts

Understand how Ampersand integrations, installations, revisions, connections, and configs fit together, and how a customer’s config overrides a revision.

Ampersand has one core idea: you define an integration once, and each of your customers gets their own installation of it.

You describe what the integration can do in amp.yaml (also called the manifest). Each customer then connects their own account and chooses how much of that to enable. Ampersand stores those choices as a config and runs the integration against that customer’s account on their behalf.

Integration

An integration defines how your application works with a third-party system. You build it once, and every customer who connects that system uses it. For example, one integration called salesforce-accounts serves all of your Salesforce customers. Salesforce is the provider.

You create an integration by defining it in your amp.yaml and deploying it with the amp CLI.

Your amp.yaml describes what is possible, not what any particular customer has turned on. It can say:

• objects and fields that are always read (requiredFields)
• fields the customer may choose from (optionalFields, or optionalFieldsAuto: all)
• fields the customer must map to one of their own fields (mapToName)
• a schedule, a destination, and backfill behavior

What's the difference between an integration and an installation?

The integration is what you build, once, for all your customers. An installation is created for each customer that uses that integration.

Revision

Every time you change amp.yaml and run amp deploy, Ampersand stores a new revision, a versioned snapshot of the integration’s definition.

If I add an object to amp.yaml and deploy, do existing customers get it?

Only if the object is under read and you mark it enabled: always. Then all installations start reading from that object. See always-enabled objects. Otherwise only new installations read that object by default. To have an existing installation read it, ask that customer to reopen the page where you embedded the Ampersand UI and go through the setup process for that object. Alternatively, call the Update an installation API.

Installation

There’s an installation for each customer that uses an integration. For example, an integration called salesforce-accounts might have 30 installations, one for each customer who has connected their Salesforce.

An installation is created when a customer finishes setup in the InstallIntegration component, or when you call the Create installation endpoint. Deploy your amp.yaml first: without a deployed integration, there’s nothing to install.

When you add the component to your product, you tell Ampersand which integration to install and who it’s for:

<InstallIntegration
  integration="salesforce-accounts" // The name in your amp.yaml
  consumerRef={userId}              // The person setting it up
  consumerName={userFullName}
  groupRef={companyId}              // The company that the person works at
  groupName={companyName}
/>

Your “customer” is the group: the company, team, or workspace in your app. The consumer is the person in that group who does the integration setup. One installation serves the whole group.

Each installation holds two things:

Connection

The credentials for that customer’s account. Ampersand supports many auth methods, and handles token refresh for you.

Config

That customer’s choices, which act as overrides on the integration’s definition: fields, mappings, schedule, etc.

What's the difference between a connection and an installation?

A connection is only the customer’s credentials. Connecting an account on its own, for example with the ConnectProvider component, creates a connection but not an installation. A connection alone doesn’t do anything. An installation is needed for anything to actually happen (like reading data, writing data).

That’s also why you can change a customer’s setup without them signing in again: update their config by showing them the InstallIntegration component again, or call Update an installation API. Their connection stays as it is.

Putting it together

1. You deploy an integration

   amp deploy creates a revision. Nothing runs yet.

2. A customer connects

   They sign in to their own account in your product. That creates a connection.

   
3. They configure the integration

   Their selections become the config. Each part of your amp.yaml shows up on this screen. Required fields are listed as fields your app reads. Each mapToName becomes a “Map the following fields” dropdown, with your prompt as the tooltip. Optional fields are a list they can check. When they click the “Install” button, that creates an installation.

   
4. Ampersand runs it

   Ampersand uses your revision with their config’s overrides applied. Reads and subscriptions run on their own and deliver results to your destination. Writes, searches, and proxy calls run against their account whenever your app calls the API.

How config overrides a revision

The config records one customer’s choices for an installation, as overrides on top of the revision.

Anything the config specifies wins for that installation. Anything it leaves unset falls back to what the integration’s revision defines.

Is my amp.yaml the same as a customer's config?

No. Your amp.yaml defines what’s possible for everyone. A config holds only what one customer chose or changed. What runs for that customer is your revision with their config applied on top.

What a config can override

For a	Examples of what config can set
Read object	Selected fields (selectedFields or selectedFieldsAuto: all), mappings (selectedFieldMappings, selectedValueMappings), schedule, destination, backfill, fieldFilters, and disabled to pause the object
Write object	deletionSettings, selectedFieldSettings, and selectedValueDefaults

What a config can’t do

• Remove a required field from a read action. Required fields always come from your revision. A config can only add fields to read.

Example

Suppose your amp.yaml declares:

specVersion: 1.0.0
integrations:
  - name: my-salesforce-integration
    provider: salesforce
    read:
      objects:
        - objectName: account
          destination: defaultWebhook
          schedule: "*/10 * * * *" # Every 10 minutes
          requiredFields:
            - fieldName: name
            - mapToName: renewalDate
              mapToDisplayName: Renewal date
              prompt: Which field holds the renewal date?

A customer installs it and maps renewalDate to their contract_end__c field, adds two optional fields, and leaves everything else alone. This is what their config would look like. If you are using the UI library, it will construct this for you.

{
  "provider": "salesforce",
  "read": {
    "objects": {
      "account": {
        "objectName": "account",
        "selectedFields": { "industry": true, "website": true },
        "selectedFieldMappings": { "renewalDate": "contract_end__c" }
      }
    }
  }
}

So for this customer, we would read the following fields:

• name (required field from your amp.yaml file)
• industry (optional field from config)
• website (optional field from config)
• contract_end__c delivered as renewalDate (field mapping from config)

We would read their accounts every 10 minutes (which is the schedule defined in your amp.yaml file).

If that customer later asks for every 30 minutes, you set schedule on their config to */30 * * * *. It now overrides the default schedule, but only for them. Every other installation still reads accounts every 10 minutes.

You can read the existing config of an installation with Get an installation API. You can change it with Update an installation API, or ask your customer to re-open the page where you embedded the InstallIntegration component to modify their choices.

Related terms

A provider is the third-party API you integrate with. A provider app is the OAuth app you register with that provider, stored in Ampersand so customers can authenticate against it. A destination is where read and subscribe results are delivered: a webhook, warehouse, or queue.

A project holds your integrations. Use one project per environment, like dev and prod, each with its own provider apps. See Dev and prod environments. An operation is logged every time Ampersand makes a read, write, or proxy request to a provider, so you can trace it in the dashboard.

For the full glossary, see Terminology.