Skip to main content

Embedding Integration Designer

In addition to using productized integrations from your marketplace, some of your customers may need to build unique integrations between your product and the other apps they use. These are often one-off, custom integrations that a single customer needs, but that wouldn't be of value to others.

Embedded designer allows customers to log in to your product and build these integrations using the same integration designer your teams use. And along with the designer, you can give your customers access to private components and templates they can use as starting points for these custom integrations.

This article covers how to embed the integration designer in your product so that your customers can have the best integration building UX.

For information on how to install the embedded SDK and authenticate customer users, see Installing Embedded SDK. Note: you should include "role": "admin" in JWTs that you sign for customer users who build integrations.

Embedded Designer is an add-on feature

Embedded designer can be enabled for enterprise accounts as an add-on feature. Please contact support to discuss embedded designer.

Enabling embedded designer for a customer​

Embedded designer is disabled for all customers by default. To enable embedded designer for a customer, open the customer from the Customers screen and then select the Details tab. Toggle the Allow Embedded Designer option.

Embedded screen configuration​

Most embedded screens that show components, integrations, instances, etc., take three properties:

  • usePopover is a boolean that determines if the screen should display as a popover. By default, the screen is injected as an iframe into an existing DOM element.
  • selector identifies which element in the DOM to inject the iframe into when usePopover is false.
  • theme can override custom theming default behavior, and can be set to "LIGHT" or "DARK" mode.

Showing component screens​

You can embed the component screens in your app using the prismatic.showComponents and prismatic.showComponent functions respectively. To show all components that are available in your tenant, use the showComponents() function:

Showing all components - ReactJS example
import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "my-embedded-builder-div";

function ComponentListView() {
  useEffect(() => {
    prismatic.showComponents({
      selector: `#${id}`,
    });
  }, []);

  return <div id={id}>Loading...</div>;
}

export default ComponentListView;

To show details about a specific component, use the showComponent() function and provide the function with the ID of a component. You will need to query for the ID of the component using prismatic.graphqlRequest function, which you can use to query the Prismatic API:

Showing a specific component
import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "my-embedded-builder-div";

const getComponentId = async (key: string) => {
  const query = `query getComponentByKey($componentKey: String!) {
  components(key: $componentKey) {
    nodes {
      id
    }
  }
}`;
  const result = await prismatic.graphqlRequest({
    query,
    variables: { componentKey: key },
  });
  return result.data.components.nodes[0].id;
};

function DropboxComponent() {
  useEffect(() => {
    const showDropbox = async () => {
      const componentId = await getComponentId("dropbox");
      prismatic.showComponent({
        componentId,
        selector: `#${id}`,
      });
    };
    showDropbox();
  }, []);

  return <div id={id}>Loading...</div>;
}

export default DropboxComponent;

Additional documentation on querying the Prismatic API as a customer user from the embedded SDK is available on the Embedded API Requests article.

For an example of embedding the integration designer, including a check if the current user has integration designer permissions, see GitHub.

Showing integrations​

The prismatic.showIntegrations function shows the customer user all of the integrations that are owned by their customer. Customers can create their own integrations, or integrations can be assigned to them.

import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "integration-list-div";

function IntegrationList() {
  useEffect(() => {
    prismatic.showIntegrations({ selector: `#${id}` });
  }, []);

  return <div id={id}>Loading...</div>;
}

export default IntegrationList;

From the showIntegrations screen, customer users will be able to open existing integrations or create new integrations by clicking the +Add integration button (like an organization team member would do).

integrations are scoped to the customer

Integrations are scoped to a customer. If a customer creates a new integration, or if you assign an integration to a customer, only customer users for that customer see that integration.

Assigning an integration to a customer​

You can build an integration and assign ownership of it to a customer. To do that, open the integration, select the Details tab on the top of the screen, and select the customer who should own the integration from the Customer dropdown menu.

Opening the integration designer directly​

If you know the ID of an integration that you would like to open, you can open an integration directly using prismatic.showDesigner. You will need to query for the ID of the component using prismatic.graphqlRequest function, which you can use to query the Prismatic API:

Open an integration designer directly
import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "my-embedded-builder-div";

/**
 * Get an integration's ID given its name
 */
async function getIntegrationId(integrationName: string) {
  const query = `query getMyIntegration($integrationName: String!) {
  integrations(name: $integrationName) {
    nodes {
      id
      name
    }
  }
}`;
  const variables = { integrationName };
  const result = await prismatic.graphqlRequest({ query, variables });
  return result.data.integrations.nodes?.[0].id;
}

function EmbeddedDesigner() {
  useEffect(() => {
    const showDesigner = async () => {
      const integrationId = await getIntegrationId("Acme Inc");
      prismatic.showDesigner({
        selector: `#${id}`,
        integrationId,
        theme: "LIGHT",
      });
    };
    showDesigner();
  }, []);
  return <div id={id}>Loading...</div>;
}

export default EmbeddedDesigner;

Filtering components in the embedded designer​

If you would like to limit the components that a customer user can use in the embedded designer, you can do so by specifying a filters.components.filterQuery object when you call prismatic.showIntegrations or prismatic.showDesigner. You can filter using a component's key, whether or not it's a public component, and component category.

In this example, we list the Code and Dropbox components, as well as a private version of the Slack component and all components in the "Logic" category (like Branch, Loop, etc):

Filter components in the embedded designer
import prismatic, {
  BooleanOperator,
  TermOperator,
} from "@prismatic-io/embedded";

prismatic.showIntegrations({
  selector: `#my-integrations-div`,
  filters: {
    components: {
      filterQuery: [
        BooleanOperator.or,
        [TermOperator.equal, "key", "code"],
        [TermOperator.equal, "key", "dropbox"],
        [
          BooleanOperator.and,
          [TermOperator.equal, "key", "slack"],
          [TermOperator.equal, "public", false],
        ],
        [TermOperator.equal, "category", "Logic"],
      ],
    },
  },
});

Showing logs​

The prismatic.showLogs function presents a customer user with the logs listview page. This gives them the chance to view logs from all of their instances in one place. It is the same view that you would see as an organization team member if you opened a customer's logs tab.

import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "logs-div";

function InstanceLogs() {
  useEffect(() => {
    prismatic.showLogs({ selector: `#${id}` });
  }, []);

  return <div id={id}>Loading...</div>;
}

export default InstanceLogs;

Showing the customer dashboard​

To give your customer a holistic view of their integrations, instances, etc, you can show them the customer dashboard.

import prismatic from "@prismatic-io/embedded";
import { useEffect } from "react";

const id = "dashboard-div";

function Dashboard() {
  useEffect(() => {
    prismatic.showDashboard({ selector: `#${id}` });
  }, []);

  return <div id={id}>Loading...</div>;
}

export default Dashboard;

Hiding tabs in the embedded customer dashboard​

By default, all tabs are shown to customers when showDashboard() is invoked. To hide certain tabs, include screenConfiguration.dashboard.hideTabs parameter when you call showDashboard():

prismatic.showDashboard({
  selector: `#${id}`,
  theme: "LIGHT",
  screenConfiguration: {
    dashboard: {
      hideTabs: ["Attachments"], // Hide the Attachments tab
    },
  },
});

Customer users and custom components​

Your customers can build their own custom components and use them in their integrations. These private components are scoped to the customer, and are not visible to other customers. This is helpful if your customer needs to build a custom component that is specific to their business (for example, to wrap their own API).

The building of customer-scoped custom components is done in the same way as it is for organization-wide custom components. For information on building custom components, see the Building Custom Components article or the custom component getting started guide.

Customer users must be able to log in to Prismatic

In order for a customer user to publish a custom component, you must create a customer user account and assign them the "Admin" role. The customer user needs to be able to log in to Prismatic in order to authenticate the Prism CLI tool to publish custom components. A customer user cannot use a signed JWT to publish custom components.

Once a customer user has logged in to Prismatic, they can authenticate the Prism CLI tool by running prism login and then publish a component scoped to their customer with prism components:publish, as an organization team member would do.

If you would like to publish a component as an organization team member for a specific customer, you can run prism components:publish --customer <CUSTOMER ID> using an ID that you can fetch by running prism customers:list --columns id,name.