Configuration Variables for Customers

The need for configuration variables

Configuration variables are a familiar concept for most developers at B2B software companies. Different customers' deployments of your software likely differ from one another in subtle, or sometimes substantial ways. Your customers might have different API endpoints that an integration needs to query, or different cloud regions where your product is deployed. They might have unique SFTP server directory structures or differing Azure Blob Storage container names. The list goes on.

Rather than hard-coding customer configuration values into your integration, which becomes very onerous for your development team to manage, it's much better to source configuration from a configuration storage system. That way, anyone in your organization can change configuration values without having to touch code or rely on the engineering team.

Prismatic uses configuration variables ("config variables") to solve the configuration problem: you create reusable, non-customer-specific integrations in Prismatic using configuration variables that will later be filled with customer-specific values when they are deployed to individual customers. The same integration can be deployed to multiple customers, and each deployment can be uniquely configured for a customer using different config variables. This empowers your onboarding and support teams to configure and deploy instances of integrations to customers without needing to rely on development.

Prismatic config variables can be stored for a specific customer, or can be be applied to all of your customers, and default values for required config variables of an integration can be set. In this post I'll walk through creating and deploying an integration with required config variables. We'll look at setting config variables at the organization, customer, or integration level, and examine when it's appropriate to use each. We'll also deploy an instance of our integration by assigning organization and customer config variables to our integration's required config variables.

Requiring configuration variables in an integration

Let's create a very simple integration that does the following:

1. Check for new jobs in a third-party application by querying its API and passing in the individual customer's credentials (We'll cover credentials in another blog post – stay tuned!)
2. Do some industry-specific business logic in a code component to process the jobs
3. Write some output to a shared AWS S3 bucket under a unique file path for each customer

To accomplish this, we will need to declare four config variables, as shown here:

Let's look at what each of those config variables will be used for:

1. thirdPartyApiBaseUrl will contain the third-party application's API endpoint that customers are going to query (something like https://thirdpartyapp.com/api/v1).
2. customerUUID will contain a unique identifier for the customer running the integration – it's a variable the third party API expects.
3. completedJobsFilePath will contain a file path within an AWS S3 bucket where the customer's output is stored.
4. bucketName will contain the name of an AWS S3 bucket where our integration will write output.

The integration will then reference those config variables using configVars.VARIABLE_NAME syntax, and will look like this in the integration designer:

What about testing configuration variables

We obviously don't want to use a real customer's configuration for testing purposes, so we can create a couple organization-level config variables for testing purposes, and set up our integration designer's testing pane to use those testing variables while we build our integration:

When we're satisfied that our integration is running smoothly, we just need to tap the Publish button to signal that our integration is ready to be deployed to customers.

At this point, we have a reusable integration that can be easily configured by onboarding or support teams for individual customers.

When to use organization, customer, or default integration config variables

Before we configure an instance of our integration for an individual customer, we should note that config variables can be set at the organization level, at the customer level, or we can use default config variables for an integration. Here are the general rules I follow to determine which variable store I should use:

• If a configuration variable is generic to all customers, and will be referenced by multiple integrations, I create an organization-wide config variable. For example, if multiple integrations store data in an Azure Blob Storage container, and that container is shared by all customers, I would save the name of the container as an organization config variable. If my team later needs to change the name of the container, we can simply change a single organization config variable in one place, and won't need to hunt through configuration for every customer and every integration to point integrations at the new container.
• If a configuration variable is specific to a customer, I set it at the customer level. Variables' values can be as short or long as we need them to be – we used file paths and UUIDs in our example integration, but variable values can be long documents if necessary. For example, every customer might have a differently formatted custom form that is populated by an integration. We can save the forms' XML (or whatever format they use) as a customer-specific variable, and instances of integrations could pull down and populate a customer's forms from the customer's variable store.
• Finally, we can set default config variable values at the integration level. These default values for required integration variables are handy if there's a value that most of our customers are going to use, but we want to be able to override the value for a small subset of customers. For example, suppose almost all of our customers are US-based and have files hosted in Google Cloud region us-central1, but we also have two customers in South Korea who prefer to use the asia-northeast3 region. We could create a default config variable for an integration called gcp_region and set it to us-central1, but override that value for our two Korean customers.

Setting configuration variables

With that clarification, let's look at what it takes to configure an instance of our integration for an individual customer – in this example, Smith Rocket Company. First, we need to populate our config variable store with values.

Two of the variables required by our integration, customerUUID and completedJobsFilePath, are customer-specific, so we'll set those for our customer by clicking into the customer and selecting the customer's Config Variables tab:

One of the variables required by our integration, thirdPartyApiBaseUrl, will be the same for all of our customers, so we'll set that at the organization level. We can do that by clicking the settings icon on the left-hand sidebar and then clicking the Config Variables tab:

Our integration's last required configuration variable has a default value, and we'll happily just use the default for this example, so we don't need to create a bucketName variable at the organization or customer level.

Deploying an instance of our integration with configuration variables

At this point, we have published an integration that requires four config variables, and have populated our organization and customer variable stores with values. Now it's time to configure and deploy an instance of our integration to a customer.

After clicking into a customer and tapping the + Instance button, and choosing our integration to deploy, we're greeted with a screen showing our four required config variables. We can use the dropdown menus to choose organization or customer config variable values, which we set up in the previous step, for each required variable:

Once we're satisfied with our configuration, we can deploy and enable our integration. That's it! At this point we have an instance of our integration configured and deployed to a customer using some organization and customer-specific configuration variables.

Recap and further reading

In this post we looked at how to set configuration variables at the organization, customer, and integration level, and when it is appropriate to use each. We also deployed an instance of an integration using some config variables that we set. For more information on config variables, check out our docs. You may also want to walk through our quickstart that guides you through driving integration logic through config variables.