Organization-Activated Customer Connections

---

---

If you rely on connections that are customer-specific, but are used in multiple integrations, organization-activated customer connections help you (the organization) configure a connection once for a customer that can be used in several of the customer's instances.

For example, suppose you are Acme SaaS. Several of your integrations interact with your API, and each of your customers have their own Acme SaaS API key. You know their Acme SaaS API keys. It would feel strange for a customer user who is logged in to your Acme SaaS web app to enter their own Acme SaaS API key into an embedded config wizard. So, you can set each of your customers' Acme SaaS API keys on their behalf once and the instances that your customer deploys that rely on that key will reference the customer-specific connection.

Creating a new organization-activated customer connection

To create a new organization-activated customer connection, open your organization's settings page by clicking your organization's name on the bottom-left, and then open the Connections tab.

• Select + Add Connection.
• Select a connector and connection type
• Under Connection Type select Organization-Activated Customer Connection
• Give your organization-activated customer connection a recognizable name and description.
• If the connector supports more than one connection type (like OAuth 2.0 and Personal API Key), select the connection type you'd like to use.
• If you have more than one Prismatic tenant (e.g. US and EU tenants, or dev and prod tenants), update the default Stable Key to the same value in each tenant. That key will be used to match up organization-activated customer connections across your tenants.

Under the Stable Key is a section called Inputs. Here, you can specify if each of the connection's inputs are Global (same value for all customers) or Customer-Specific (unique for each customer).

For example, if your customers all have accounts on an SFTP server, their username and password may be unique, but they may all use the same host and port.

Check global values carefully

Be sure to check global values that you set carefully. Once set, they cannot be changed.

When ready, click Create.

Configuring a test connection for building integrations

After creating a new organization-activated customer connection, you'll be prompted to supply test credentials for that connection. These test credentials will be used in the integration designer as you're building your integrations if your integration relies on an organization-activated customer connection.

If you'd like to change your test credentials at any time, you can return to the Connections tab in your organization settings, select your connection, and edit your credentials under Test Runner Connection. Your test instances that run as you test your integration in the integration designer will immediately begin using the new test credentials that you supply.

Configuring a customer's connection

Once an organization-activated customer connection is created, you can assign connection values for each of your customers. You can do this through the UI or programmatically.

Through the UI, open Customers and select a customer. Under the customer's Connections tab, select + Add connection and then select the organization-activated customer connection you just created.

Fill in the fields that your connection requires (API key, username, password, endpoint URL, etc) with customer-specific values.

The values you fill in here will be used whenever this customer deploys an instance of an integration that relies on your connection.

Programmatically creating a customer's connection

Programmatically setting a customer's connection values is a three-query process using the Prismatic GraphQL API:

1. Fetch the organization-activated customer connection's ID You can do this by running a scopedConfigVariables query:

   query {
     scopedConfigVariables(stableKey: "acme-api-key") {
       nodes {
         id
         key
         stableKey
         connection {
           inputs {
             nodes {
               id
               key
             }
           }
         }
       }
     }
   }

   This will yield your organization-activated customer connection's ID along with its inputs and their keys. Take note of the ID you get back - it should start with U2Nvc....

2. Fetch your customer's ID. You can do that through a customers query.

   query {
     customers(externalId: "my-external-id") {
       nodes {
         id
         name
       }
     }
   }

   Take note of your customer's ID (note: not they're external ID) - it should start with Q3Vzd....

3. Create a connection for your customer with some values you know. You can do that with a createCustomerConfigVariable mutation using the connection and customer ID you noted, along with an array of inputs. Inputs should have the shape

   { value: string, name: string, type: "value" }

   Each input's name is the key of the connection input (e.g. "username", "apiKey", "host", etc). value is the customer's value for that input.

   mutation {
     createCustomerConfigVariable(
       input: {
         scopedConfigVariable: "U2NvcGVkQ29uZmlnVmFyaWFibGU6NjIzZjM2NWItMzc3Ny00MWRkLWEyODAtNTBjNjliMjQyMGQ4"
         customer: "Q3VzdG9tZXI6NzFlY2NiYzQtYjc5OC00YzQzLWIzZDAtZjdmYzE5OTEyYzlj"
         inputs: [{ value: "Testing", name: "apiKey", type: "value" }]
       }
     ) {
       customerConfigVariable {
         id
       }
       errors {
         field
         messages
       }
     }
   }

Using organization-activated customer connections in an integration

The next time you add a connection to an integration, if you have an organization-activated customer connection defined for that connection type your integration designer will automatically reference it.

When running a test execution within the integration designer, the test connection that you set previously will be used. If you deploy this integration to a customer, that customer's organization-activated customer connection will be used. The customer will not see the connection as they walk through your integration's config wizard.

FAQ

What will customer users see?

Nothing. You as an organization will create the connection for your customer. When a customer configures an instance that relies on that connection, no UI elements will appear in their config wizard.

Can organization-activated customer connections be used if I have multiple tenants?

Yes. If your organization has multiple tenants (for example, a US and EU tenant, or a dev and prod tenant), be sure to assign your organization-activated customer connections the same Stable Key in each tenant. Then, when you sync integrations between tenants, your integrations will automatically use the correct organization-activated customer connection in the new tenant.