Using Boomi Companion to build a custom connector with Claude

Updated 19 October 2026

Use Boomi Companion to develop a custom connector using the Boomi Connector SDK. The boomi-connectordev skill sets up the connector project, checks it for errors, helps you test it, and publishes it to your Boomi account.

You describe the connector you want in plain language and review the results along the way. When you are done, the connector is ready to use in Boomi Integration.

Install the bc-connectordev plugin

• In Claude Code, run:

  /plugin marketplace add OfficialBoomi/boomi-companion
  /plugin install bc-connectordev@boomi-companion

  For more information, refer to Installing the plugin on Claude Code.

• For Claude Cowork, refer to Installing the plugin on Claude Cowork.

Prerequisites

• An AI tool that supports skills or plugins, with the boomi-connectordev skill or bc-connectordev plugin installed. Follow your tool's guidelines to install it.

• Access to the Boomi Enterprise Platform with the DEVELOPER privilege.

• A signed SDK Publisher Agreement for your account. Required to publish connectors.

• A JDK and Gradle installed locally, in a compatible pairing. Gradle is the supported build path; Maven guidance is best-effort. The project template targets Java 8 bytecode, whichever JDK runs the build.

• A local Runtime on a machine you control, if you need breakpoints, container logs, or to test a listener connector. Shared cloud runtimes can run a published connector but don't support archive swapping or remote debugging.

• A .env file in your project workspace with Boomi Platform credentials. If the bc-integration plugin is already set up, the skill reuses those values.

  Key	Description	Required
  BOOMI_USERNAME	Your Boomi Platform username (email).	Yes
  BOOMI_API_TOKEN	Platform API token. Go to Settings > My User Settings > Platform API Tokens.	Yes
  BOOMI_ACCOUNT_ID	Your account ID. Go to Settings > Account Information.	Yes
  BOOMI_API_URL	Platform API URL. Typically https://api.boomi.com.	Yes
  BOOMI_TIMEOUT	Request timeout in seconds. Default is 60.	No
  BOOMI_VERIFY_SSL	Set to false to skip TLS verification, such as behind a TLS-inspecting proxy. Remove it when you no longer need it.	No

  The skill reads only these keys, ignores all others, and never expands values. Single-quote any value that contains spaces or shell characters.

• Permissions for the skill and its scripts in your workspace's .claude/settings.json, under permissions.allow:

  "Skill(bc-connectordev:boomi-connectordev)",
  "Bash(bash */skills/boomi-connectordev/scripts/*)",
  "Bash(./gw:*)"

  The ./gw entry is the connector project's Gradle launcher, run from the project directory.

Key concepts

• Connectors API: The API the skill uses to manage connectors. Its base path is {BOOMI_API_URL}/connector/api/rest/v1/{accountId}, not the Platform API path.
• Connector group: The container for one connector. Create one group per connector. The API assigns a groupType slug in the form <accountId>-<slug>. You can't derive it, so read it from the group create or group get response.
• Classification: A tier within a group, such as dev, qa, or prod. Its classificationType is <groupType>-<classification>. Connection and Operation components carry the classificationType as their subType.
• Version: An uploaded connector archive. Uploading a version doesn't activate it.
• Version change: Sets which uploaded version is active for a classification. For private connectors, it takes effect without an approval step. For public connectors, it opens an approval request.
• Archive: A .zip of lib/** and META-INF/. The Gradle connectorArchive task builds it.

Core workflow

Step 1: Provide a prompt

Open your AI agent with the bc-connectordev plugin installed and describe the connector you want. You don't need to provide SDK documentation. The skill includes reference material on the descriptor, SDK architecture, the REST framework, testing, and common problems.

A minimal prompt is sufficient. Such as:

Create a custom Boomi connector for a REST API that supports querying and creating orders.
Use API key authentication.

Step 2: Check your build environment and scaffold the project

Ask the agent to check your toolchain and create the project:

Check my build environment and scaffold the connector project.

The agent runs a preflight check that confirms your JDK and Gradle pairing and that the JVM can reach the plugin portal and SDK repository. It then lays down a template project with a pinned Gradle wrapper and a gw launcher, and builds the archive with ./gw connectorArchive.

important

Build with ./gw, not ./gradlew. The wrapper launcher and the Gradle daemon read different JVM settings, so a truststore set for one leaves the other failing.

The agent also generates the SDK samples and reads them before writing connector code.

Step 3: Build the connector

Describe what the connector should do, and ask the agent to write the descriptor and Java classes. The agent authors connector-descriptor.xml, which defines fields, operations, visibility, and test connection, and the Connector, Browser, and Operation classes.

The agent streams every response into payloads. Reading a whole response into memory can cause the Runtime to run out of memory.

Step 4: Test locally

Ask the agent to write and run tests:

Write unit tests for every operation type in the descriptor, and run them.

The agent uses ConnectorTester to drive every operation type the descriptor declares, not only the one you're developing. A missing factory-method override appears only on that type's first execution.

Use a local Runtime for breakpoints, container logs, and listener connectors. If the connector will run on a shared cloud, execute it there before release. Cloud runtimes deny file writes outside the working directory, environment reads, process spawning, and reflection. A local Runtime doesn't enforce these restrictions.

Step 5: Validate the descriptor

The agent validates the descriptor at two points:

1. Lint: Checks the source descriptor against the SDK's XSD locally as you edit, and names the offending element and line.
2. Validate: Checks the descriptor from the built archive against the Connectors API before every upload. Run it even when lint is clean, because the XSD doesn't cover the semantic checks or the operation types vocabulary. Validation has no side effects.

Neither check can see the Connection or Operation components that use the descriptor. A clean result doesn't confirm those components are correct.

Step 6: Publish the connector

Ask the agent to publish:

Publish the connector to my account.

The agent:

1. Creates a connector group, the first time only, and records the returned groupType.
2. Uploads the archive as a new version.
3. Sets that version as active for a classification.

Before changing anything, the agent queries what already exists. If a script returns a 403 or a privilege-related 400, the agent stops and reports it rather than retrying. Repeated invalid-authentication calls risk a platform lockout. To check your access, ask the agent to run the environment check.

note

• Uploading a version doesn't activate it, including the first version. The classification's connection form is empty in the GUI until you change versions.
• A version change doesn't require redeploying processes.
• A Runtime that has already loaded the connector keeps serving the loaded version until the container restarts.
• A newly activated version's archive returns a 403 for roughly 30 minutes before a Runtime can fetch it. This is expected and isn't an authentication failure.

Step 7: Hand off to integration development

Once the connector is built, you can interact with it through the GUI or Boomi Companion's bc-integration plugin.

important

All passwords should be handled in the Boomi Platform GUI to ensure they stay out of Agent context window.

Scripts reference

The skill reaches the Connectors API only through its scripts. Each script supports --help. The first three scripts are local tools: they don't read .env or call the API.

Script	Purpose
connectordev-doctor.sh	Checks the build toolchain: JDK, Gradle pairing, and network access from the JVM. With a project directory, also warns about calls that buffer a whole stream in memory.
connectordev-init.sh	Creates the template project. Options: --name, --package, --class.
connectordev-descriptor-lint.sh	Validates a descriptor against the SDK's XSD. Option: --sdk-version.
connectordev-env-check.sh	Verifies .env and API access, and lists existing group types.
connectordev-group.sh	Manages groups and classifications: create, get, delete, query, query-more, classification-add, classification-delete. Group queries page at 20.
connectordev-version.sh	Manages versions: upload, delete, query, query-more, validate. Version queries page at 100 and require a group type.
connectordev-version-change.sh	Sets or cancels the active version: set, cancel.

group delete is a soft delete. The deleted group keeps its groupType, and group queries still list it.

Limitations

The skill doesn't cover:

• Using a published connector in a process. Use the bc-integration plugin.
• Exposing a process as MCP tools is covered by the bc-integration plugin.
• Connector Management API governance: review submission, visibility, metadata, and icon.

Results

• A Connector SDK project that builds with Gradle.
• A descriptor that passes local and API validation.
• A published connector with an active version for a classification.

Related topics

• Connector Overview
• Getting Started with Connectors
• Connector SDK
• Connector Development FAQ

Support

For feature requests or bug reports related to bc-connectordev, email developer-offerings@boomi.com with a description of the issue, steps to reproduce, and any relevant error messages.