Skip to main content

User Level Configuration

Typically, one instance of an integration is configured and deployed to one customer. That "one instance for one customer" setup works well for many integrations, but what do you do when multiple users of a single customer each have their own third-party credentials or configuration needs?

User Level Configuration (ULC) allows your customers' users to each configure user-specific settings on an instance of an integration. One instance is deployed to a customer, but it contains user configuration information for one or more users within that customer. The instance then runs using the appropriate user's configuration depending on some rules you set.

Example use case: Suppose your customers use Dropbox for file storage. Your customer would like to sync data from your app with some subset of their users' Dropbox accounts. Using ULC, your customer would deploy an instance of your Dropbox integration using the usual deployment process. Then, the users who would like to use the integration within that customer would each go through a ULC configuration, each supplying connection information for their Dropbox account.

ULC is an opt-in feature

ULC is enabled on an as-needed basis. Please contact support to discuss enabling ULC for your organization.

User level configuration wizard​

When ULC is enabled in your account, you will see a User Level Configuration Wizard button next to the standard Configuration Wizard button in the integration designer.

The ULC configuration wizard designer is very similar to the configuration wizard designer - you can add connections and other types of config variables like you would in the normal configuration wizard.

  • The configuration that you define in the Configuration Wizard Designer will be seen by an admin user of your customer. That user will initially create the instance of the integration for the customer and fill in any customer-wide configuration.
  • The configuration that you define in the User Level Configuration Wizard Designer will be seen by standard users of your customer. It will prompt individual users for user-specific credentials and config variables.

Testing user level configuration in the integration designer​

To test ULC in the integration designer, open up the Test Runner drawer and complete both the standard config wizard as well as user-specific config wizard.

Tests you run will load the test user level configuration that you set.

User level configuration in embedded marketplace​

When you authenticate users in the embedded marketplace you will need to include a role property in your signed JWT that has a value of either "admin" or "user". If a role property is omitted, it defaults to "admin".

If you plan to use shared endpoints for ULC integrations, ensure your signed JWT includes an external_id property. This represents the customer user's external ID. This property generally matches sub, and is used to invoke ULC instances with shared endpoints.

Marketplace admins​

A user with role: "admin" can deploy an instance of a ULC integration for the customer. They can also supply user-specific configuration on their own behalf after creating the instance.

An admin user will configure a ULC instance like they would a non-ULC instance - by stepping through a configuration wizard to set up customer-wide configuration settings.

Once an instance is deployed, a marketplace admin can click Configure User Level Configuration to add their own user-specific credentials and config vars to the instance. The admin user is not required to enter those - they only need to set them if they themselves would like to use the integration.

Marketplace users​

A user with a role: "user" cannot deploy the instance, but can add user-specific configuration on their own behalf. A standard user will only see ULC integrations on the listview screen within the embedded marketplace. When a standard user selects an integration to configure, they will walk through the user level configuration wizard.

A standard user will not be able to see the instance's executions, logs, or other tabs. Clicking an integration again will show the ULC config wizard, where they can update or remove their user-specific configuration.

Managing a instance's user level config​

An organization user can view the various user-specific configuration by opening an instance and then opening the User Configurations tab.

You can click the Details button beside a user to view a user-specific webhook URL that can be used to all the instance using that user's configuration.

User level configuration and endpoint config​

You have the same options for endpoint configuration in ULC integrations that you do for non-ULC integrations, with the caveat that when you use shared endpoints you also need to specify a user by external user ID (like you do for flow name and external customer ID):

  • When endpoint type is Instance and Flow Specific, each flow for each user configured for each instance receives its own unique webhook URL. In other words, Bob's "Import Records" flow webhook URL differs from Jane's "Import Records" flow webhook URL and differs from Bob's "Export Documents" flow webhook URL. User config is loaded based on unique webhook URL when the instance is invoked.

  • When endpoint type is Instance Specific, all flows for all users of a particular customer share a webhook URL. Executions are dispatched to specific flows running with user-specific configurations by sourcing a Flow Name and External Customer User ID. The external customer user ID should match the external_id that you set in your embedded users' JWT tokens, and often matches the JWT's sub property.

  • When endpoint type is Shared, all users and their flows of all customers share a single webhook URL. In addition to specifying Flow Name and External Customer User ID, like in Instance Specific, you also need to specify External Customer ID.

ULC Shared Endpoints require ULC configurations for customer users

An organization team member can create a ULC configuration on an instance deployed to a customer. However, such configurations are only meant for testing purposes from within the Prismatic web app.

If you try to invoke a shared endpoint for a ULC instance and include an organization user's external ID (rather than a customer user's external ID), the execution will fail as the organization team member is not a customer user.

Like non-ULC integrations, ULC integrations with Instance Specific and Shared endpoint configuration can leverage a preprocess flow to process incoming data and dispatch executions to the proper instance / user / flow.

User level configuration information in trigger payloads​

The default webhook trigger and most other non-custom triggers include information about the user whose user level config was used for an execution. To get ULC information for the current execution within an integration, reference the trigger's results.user, which is an object containing the user's id, email (which may be a UUID or or their ID), name and externalId.