Waiting for engine...
Skip to main content

Example: Implementing Boomi EmbedKit

This project provides examples of Boomi EmbedKit configured across multiple front-ends and a Node.js server. You can use these examples to see working integrations from end to end. For more information, refer to the Getting Started with EmbedKit.

Project contents​

  • server: A simple Node.js server
  • common-js: A vanilla JavaScript front-end
  • react: A React web front-end

Prerequisites​

Before you begin, ensure that you have the following prerequisites to install and configure the demo environments:

Access to the EmbedKit package​

EmbedKit is a private npm package. To install @boomi/embedkit, you need an authentication token and an .npmrc file in the root directory of the client that you run.

If you do not have an npm access token, contact Boomi Support or the EmbedKit team to obtain one.

Boomi account and credentials​

Ensure that your system has npm or yarn installed. You also need the following Boomi credentials as environment variables:

API_ACCOUNT_ID="YOUR PRIMARY ACCOUNT ID WITHIN BOOMI"
API_USERNAME="A SERVICE ACCOUNT WITHIN BOOMI"
API_TOKEN="THE API TOKEN FOR THE SERVICE ACCOUNT"
API_AUTH_USER="THE SUB ACCOUNT ID WITHIN BOOMI"
API_ACCOUNT_GROUP="THE ACCOUNT GROUP HOLDING YOUR IPACKS"

Add CORS configurations​

EmbedKit runs inside your application and makes client calls to the EmbedKit server. You must configure CORS for your tenant (parent account ID) for local, development, test, and production environments.

To add CORS configurations, complete the following steps:

  1. Log in to https://admin.boomi.space.
  2. In the left navigation menu, click CORS.
  3. Click + to add a configuration.
  4. Add your origin and click Save.
  5. Verify that the origin appears in your CORS configurations.
note

If you encounter CORS issues, contact Boomi Support or the EmbedKit team.

Server​

To set up the server, navigate to the /server directory from the repository root and complete the following steps.

Install the package​

npm i

Set environment variables​

Create a server/.env file with the following content:

server/.env
## .env

# Server
PORT=8080
NODE_ENV=development

# Auth
JWT_SECRET=createAJWTSecret

# CORS
CORS_ORIGINS=http://localhost:5173

# Boomi 
EMBEDKIT_SERVER_BASE="https://api.boomi.space/api/v1"
API_URL="https://api.boomi.com/partner/api/rest/v1"
API_ACCOUNT_ID="***"
API_USERNAME="***"
API_TOKEN="***"
API_AUTH_USER="***"
API_ACCOUNT_GROUP="***"

# AI (optional)
OPENAI_API_KEY="***"
OPENAI_API_MODEL="gpt-4o-2024-08-06"

Run the server​

To start the server, run the following command:

npm run dev

Client​

To set up the client, navigate to the client directory that you want to use (/common-js or /react) from the repository root and complete the following steps.

Install the client​

Create an .npmrc file in the client root directory with your authentication token:

//registry.npmjs.org/:_authToken=npm_SOME_AUTH_TOKEN

Install dependencies:

npm i

Configure environment variables​

Create a .env file in the client directory with the following content:

## .env

# Server (port must match the server configured above)
VITE_SERVER_URL="http://localhost:8080"

Run the client​

To start the client, run the following command:

npm run dev

Expected behavior​

The server and client start without errors. If you see console errors, verify that your configuration is complete and correct.

After both the server and client are running, navigate to http://localhost:5173. The following sequence occurs:

  1. The application prompts you to log in.
  2. Enter any username and password.
    note

    The demo server does not validate credentials. Do not use this authentication method in production.

  3. The client requests authentication from the server.
  4. The server reads the .env credentials and authenticates with the EmbedKit server.
  5. After successful authentication, the server returns a one-time HMAC nonce with a 2-minute time-to-live (TTL).
  6. The client initializes BoomiPlugin with the nonce, your tenantId (parentAccountId), and the boomi.config.js file.
  7. The demo renders with EmbedKit initialized.

Sample boomi.config.js files are included in the project. To adjust the configuration, refer to the Customizing your styling and themes.

important

You must create a CORS configuration in the EmbedKit administration application to enable your demo, test, or production instances. Complete the steps in the Add CORS configurations section to set up CORS.

On this Page