Embedding Workflow Builder

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 typically one-off, custom integrations that serve a single customer's needs but would not provide value to others.

The embedded workflow builder enables customers to log into your product and build these integrations using the same workflow builder your teams use. Alongside the builder, you can provide customers with access to private components and templates as starting points for custom integrations.

This article covers how to embed the workflow builder in your product to provide customers with an optimal integration building experience.

For information on installing the embedded SDK and authenticating customer users, see Installing Embedded SDK. Note: Include "role": "admin" in JWTs signed for customer users who build integrations.

Feature Availability

The embedded workflow builder feature is available to customers on specific pricing plans. Refer to your pricing plan or contract, or contact the Prismatic support team to learn more.

Enabling embedded workflow builder for a customer

Embedded workflow builder is disabled for all customers by default. To enable embedded workflow builder for a customer, open the customer from the Customers screen and select the Details tab. Toggle the Allow Embedded Workflow Builder option.

Embedded screen configuration

Most embedded screens that display components, integrations, instances, etc., accept three properties:

• usePopover: A boolean that determines whether the screen should display as a popover. By default, the screen is injected as an iframe into an existing DOM element.
• selector: Identifies which DOM element 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 component screens in your application using the prismatic.showComponents and prismatic.showComponent functions respectively. To display all components 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 display details about a specific component, use the showComponent() function and provide the component's ID. You will need to query for the component ID using the prismatic.graphqlRequest function 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 in the Embedded API Requests article.

For an example of embedding the workflow builder, including a verification of the current user's workflow builder permissions, see GitHub.

Showing integrations

The prismatic.showIntegrations function displays all integrations owned by the customer user's customer. Customers can create their own integrations or have integrations 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 can open existing integrations or create new integrations by clicking the +Add integration button (like an organization team member would).

integrations are scoped to the customer

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

Assigning an integration to a customer

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

Opening the workflow builder directly

If you know the ID of an integration you want to open, you can open an integration directly using prismatic.showDesigner. You will need to query for the integration ID using the prismatic.graphqlRequest function to query the Prismatic API:

Open an embedded workflow builder 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 workflow builder

To limit the components that a customer user can use in the embedded workflow builder, specify a filters.components.filterQuery object when calling prismatic.showIntegrations or prismatic.showDesigner. You can filter using a component's key, whether it's a public component, and component category.

In this example, we list several file-related components, a private version of the Slack component, and all components in the "Logic" category (such as Branch, Loop, etc.):

Filter components in the embedded workflow builder

import prismatic, {
  BooleanOperator,
  TermOperator,
} from "@prismatic-io/embedded";

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

Requiring components in the embedded workflow builder

To require that customers use certain components within their integrations, open your organization settings page and select the Embedded tab. Add any components you want to require under the Required components section.

Embedded builder users must include components you specify before they can publish their integration.

Showing logs

The prismatic.showLogs function presents customer users with the logs listview page. This allows them to view logs from all their instances in one location. It is the same view you would see as an organization team member when opening 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 provide your customer with a comprehensive view of their integrations, instances, etc., you can display 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 displayed to customers when showDashboard() is invoked. To hide specific tabs, include the screenConfiguration.dashboard.hideTabs parameter when calling 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 beneficial when customers need to build custom components specific to their business (for example, to wrap their own API).

The development of customer-scoped custom components follows the same process as 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

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 must be able to log into Prismatic to authenticate the Prism CLI tool for publishing custom components. A customer user cannot use a signed JWT to publish custom components.

Once a customer user has logged into 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.

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