Organization-Activated Connections

If you rely on connections that are customer-specific, but are used in multiple integrations, organization-activated 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 and have 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 intances that your customer deploys that rely on that key will reference the customer-specific connection.

Creating a new organization-activated connection

To create a new organization-activated 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 Org-Activated Connection as the Configuration Type
• Select your custom component (or an existing component) and then your component's connection under Connection Type
  Organization-activated connections must be non-OAuth 2.0

  The connection you select must contain static inputs (API Key, username, password, host, port, etc). OAuth 2.0 organization-activated connections are not currently supported.

• Give your organization-activated connection a recognizable name and description.
• If you have more than one Prismatic tenant (e.g. US and EU tenants, or dev and prod tenants), supply a Stable Key. That key will be used to match up organization-activated connections across your tenants.

Under the Stable Key is a section called Configuration. Here, you can specify if each of the connection's inputs are per-customer, or global. 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 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 connection.

If you'd like to change your test credentials at any time, you can return to the Connections tab in your orgnaization settings, select your connection, and click Edit test credentials. 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 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 configuration and then select the orgnaization-activated 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 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 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 connections in an integration

The next time you add a connection to an integration, if you have an organization-activated 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 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 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 connections the same Stable Key in each tenant. Then, when you sync integrations between tenants, your integrations will automatically use the correct organization-activated connection in the new tenant.