Waiting for engine...
Skip to main content

Configuring the Integrations Component and plugin

This topic provides an overview of configuring the integrations component and plugin setup.

Configuring the Integrations Component​

The Integrations Component is a complete drop-in UI that simplifies connecting, mapping, and orchestrating Integration Packs configured within Boomi. This full-featured component is intended for consumers or citizen integrators to use within custom SaaS applications. The following images highlight the different capabilities of this component.

The Integrations home page displays different integration cards

Boomi EmbedKit

Adding integration to your UI portal

Add Integrations

Configure connection details for the source and target systems

Configure connections

Mapping data fields between the source and target systems

Mapping data fields between systems

Set your integration to run immediately or schedule it for later

Set Schedule

This components user interface is completely customizable. For more information, refer to the Customizing your styling and themes topic.

Install and configure the plugin​

This section provides step-by-step instructions for installing and configuring the Boomi EmbedKit plugin.

Application Developer workflow

Prerequisites for the plugin​

The following applications, resources, and accesses are required for configuring the EmbedKit plugin:

  • npm
  • React, CommonJS, or JavaScript UI Framework
  • For authentication, your SaaS application's user records must include the Boomi sub-account IDs and account group. These values are required to be passed to the plugin for authentication
  • Get your API Token from the Boomi Platform. For more information, refer to the Platform API Tokens overview
  • Set your IP/URL CORS policy inside the parent account within Boomi. For more information, refer to the Account security for CORS topic

Install the plugin​

To install the package, enter a command in the following form:

npm i @boomi/embedkit

Set up the plugin​

The Boomi plugin must be initialized within your application to render the UI components. To enable the plugin, follow these steps:

  1. Create an HTML div element on the page where you want to render the Boomi EmbedKit components. You must provide an ID equal to boomi.

      <body>
        <div id="boomi"></div>
      </body>

  2. Initialize the plugin within your application. As shown, you can use a script tag or a separate .js file to do this.

    index.html 
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Boomi EmbedKit</title>
      </head>
      <body>
        <div id="boomi"></div>
        <script type="module" src="./index.js"></script>
      </body>
    </html>

  3. Create the BoomiPlugin, passing the required credentials; these should not be inserted via environment variables in production use cases.

    warning

    Failure to store the following parameter values from a secure location, such as a database, could expose your keys in plain text, which is highly risky and not recommended.

    BoomiPlugin 
      import BoomiPlugin from '@boomi/embedkit';
      import uiConfig from './boomi.config';    // import the local config data

      // set a variable to ensure the plugin is initialized prior to attempting to call RenderComponent
      let boomiReady = null;                    

      // implement a server side call within your application to retrieve the boomi credentials
      async function initBoomiFromServer() {
        const cfg = await fetchPluginConfig();  
        if (!cfg) throw new Error('Not authenticated or failed to fetch config');

        // load from cfg not from .env or uiConfig
        BoomiPlugin({
          baseUrl: cfg.baseUrl,
          accountId: cfg.accountId,
          userName: cfg.userName,
          token: cfg.token',
          authUser: cfg.authUser,
          accountGroup: cfg.accountGroup,
          ai: {
            enabled: true,                        // optional: enable AI features in supported components 
            model: 'gpt-4o-2024-08-06',
            apiKey: cfg.openAiApiKey,
          },
          ...uiConfig,                            // optional build-time merged UI config
        });

        boomiReady = new Promise((resolve) => requestAnimationFrame(resolve));
        return boomiReady;
      }

Authentication and Authorization​

EmbedKit does not store any passwords on disk or within the Boomi Platform. As mentioned, the plugin is initialized with the parent accountId and authToken. However, the authUser = Boomi Sub AccountID must be provided to the plugin upon initialization, along with what accountGroup the plugin should render for the authUser. Refer to the Account Group settings topic for an overview of the Account Hierarchy within the Boomi Platform.

EmbedKit assumes that your application authenticates and authorizes your users before initializing the EmbedKit plugin. We recommend that you store the BoomiAccountId and AccountGroup on your internal user's profile, and provide that information after your application successfully authenticates and authorizes your users.

Rendering the Integrations Component​

Each EmbedKit component has a number of predefined configuration options that can be passed when the component is rendered. These options are passed in via Properties. It is important to refer to the EmbedKit SDK section to understand the available options for each component.

note

The properties available for each component vary, and you should refer to the EmbedKit SDK. However, each component supports the following:

@property {boolean} showTitle - Whether the component title should be displayed.
@property {string} [title] - Optional text for the component title.
@property {boolean} showDescription - Whether the component description should be displayed.
@property {string} [description] - Optional text for the component description.

Use the following to render the component. Note that the component will render within the div mentioned earlier:

<div id='boomi'>{component will render here with full context}</div>

Use the following JavaScript to render the component:

Integrations 
import { RenderComponent } from '@boomi/embedkit';
  RenderComponent({ 
    targetId: 'boomi',                  // optional: override to target a different div than id="boomi" 
    component: 'Integrations',          // required: the name of the component to render
    props: { 
      componentKey: 'integrationsMain', // optional: configure more than one component of the same type
      } 
  });

Building your own component using hooks​

The EmbedKit exposes several hooks. You can use these hooks to build your own components within your React application. These hooks require the EmbedKit PluginContextProvider.

note

The current hooks implementation requires React and your application to wrap the hook usage in the EmbedKit PluginContextProvider. To view a list of hooks, refer to the EmbedKit SDK Hooks topic.

Wrapping your app (or a subtree) with the provider​

To leverage one of the provided hooks within your React application, wrap your app with the PluginContextProvider as shown:

PluginContextProvider
  import React from 'react';
  import ReactDOM from 'react-dom/client';
  import { EmbedKitProvider } from '@boomi/embedkit';
  import App from './App';

  ReactDOM.createRoot(document.getElementById('root')!).render(
    <EmbedKitProvider
      accountId="<PARENT_ACCOUNT_ID>"
      userName="<CHILD_ACCOUNT_ID_OR_USERNAME>"
      token="<BOOMI_API_TOKEN>"
      authUser="<CHILD_ACCOUNT_ID_OR_USERNAME>"
      accountGroup="<OPTIONAL_GROUP>"
    >
      <App />
    </EmbedKitProvider>
  );

Using the hook inside your components​

In this example, the hook returns { fetchEnvironments, environments, isLoading, error }. Call fetchEnvironments with either a classification ('PROD' | 'TEST' | 'ALL') or a specific environmentId:

App.tsx (consumer app) 
  // App.tsx (consumer app)
  import { useEmbedKit } from '@boomi/embedkit';
  import { useFetchEnvironments } from '@boomi/embedkit';

  export default function App() {
    const { isReady } = useEmbedKit();
    const { fetchEnvironments, environments, isLoading, error } = useFetchEnvironments();

    React.useEffect(() => {
      if (isReady) void fetchEnvironments('ALL');
    }, [isReady, fetchEnvironments]);

    if (!isReady) return <p>Booting…</p>;
    if (isLoading) return <p>Loading environments…</p>;
    if (error) return <p style={{ color: 'crimson' }}>{error}</p>;

    return (
      <ul>
        {environments.map((e: any) => (
          <li key={e.id}>
            {e.name} – {e.classification} – {e.isActive ? 'ONLINE' : 'OFFLINE/MIXED'}
          </li>
        ))}
      </ul>
    );
  }
On this Page