Skip to main content

Custom integrations

While Uniform comes with a large set of prebuilt integrations, you may need to integrate systems that Uniform has not built integrations for. The Uniform Mesh SDK enables you to build your own integrations for such systems and incorporate those integrations into the Uniform Dashboard.

tip

If you prefer to jump directly to writing code, go to the custom integration tutorial.

A custom integration consists of the following:

  • Configuration app that you build that provides the user interface for interacting with the system you are integrating.
  • Design system that provides components you can use to build the user interface for the configuration app.
  • Locations in Uniform where the configuration app is used.
  • Registration that incorporates the configuration app and location settings into the Uniform Dashboard.

Configuration app

A custom integration for Uniform enables you to extend the Uniform dashboard to allow Uniform users to interact with external systems. You build a custom user interface that is incorporated into the dashboard using an iframe. This means a custom integration needs a web application that the iframe can point to. This web app is called the configuration app

When you build a custom integration, you build this web application. The web app does the following:

  • Provides the user interface that is incorporated into the Uniform dashboard.
  • Implements logic to interact with an external system.
  • Implements logic to save values that are selected to Uniform.
config-app-iframe
The dotted border indicates where the iframe is located.

Design system

Uniform provides a design system so you can ensure that the user interface for any screens required to configure or use your custom integration are consistent with the rest of the Uniform Dashboard. For more information, see the design system reference.

Front-end

You can use whatever front-end technology to build this web app. Uniform provides a design system with components that facilitate building UI extensions for the Uniform Dashboard. Using a front-end technology that is supported by the design system will make it much easier to build your UI extensions, but using it is not a requirement.

If you are using the Uniform design system, the following requirements apply to your front-end application:

Hosting

Where this web app runs is up to you. The Uniform dashboard uses an iframe to include the web app when needed. The only requirement is that your Uniform users can access the web app. This web app can run on an internal network as long as Uniform users can reach the network.

Locations

A custom integration enables you to extend the Uniform dashboard with custom user interfaces from a configuration app you build. There are a number of different locations in the Uniform dashboard where your custom integration can be included.

Install

When a custom integration is installed, it is helpful to show the Canvas administrator a description of the custom integration.

You are able to provide one or more paragraphs of text that is displayed to the Canvas administrator when the custom integration is assigned to a project.

install-example
info

The "install" location is not an interactive location. The information provided in this location is displayed to the user, but the user cannot change it.

Settings

Each custom integration has project-specific settings that might need to be configured. For example, an integration that creates a connection to a commerce system might enable a Uniform user to specify credentials for Uniform to use to communicate with the commerce system.

When a custom integration is added to a project, its settings are available as a new link in the left menu on the Settings section of the Uniform dashboard.

settings-example
The custom integration name appears in the left menu. The page identified by the custom integration's settings location appears in the content area.

The user inteface displays the settings that are currently configured, and allows the user to make changes to those settings. You can implement this logic in your preferred framework.

Parameter configuration

Configuration happens when the parameter is added to a component definition. When a parameter is a simple value like text or a number, no additional options are necessary. But even a numeric type could have additional options, such as minimum and maximum values.

When you create a custom integration, you may want to allow the Canvas user who is adding the parameter to a component to be able to configure some additional settings. The parameter configuration location allows you to add form fields between the Type field and the OK button.

configure-parameter-example

Parameter editing

Editing happens when a Canvas user sets the value on a specific parameter on a specific component. If the parameter represents a product from a commerce system's product catalog, you might want to provide the Canvas user a visual representation of the product catalog to make it easier for the user to select the appropriate product.

The parameter editing location allows you to add form fields to the component parameters section.

edit-parameter-example

Registration

Registering a custom integration makes the integration available to Uniform users. Registration involves:

  • Adding the integration to your Uniform team
  • Assigning the integration to one or more projects
  • Mapping the screens from your configuration app to locations in the Uniform UI

For details, see the guide on how to custom integrations.