Boomi Integration

Implementing Boomi with this Skill

This is the Boomi Process Development Framework - a reusable skill that enables AI coding agents to build Boomi integration processes programmatically. It provides CLI tools, reference documentation, and patterns for bi-directional synchronization with the Boomi platform API.

Architecture: The framework is separated from project components:

• boomi-integration skill: Reusable infrastructure, tools, documentation
• active-development/ (project root): All working files - components, sync state, feedback

**Running CLI tools — resolve ` at the beginning of each session.** All script invocations in this skill use the placeholder /scripts/...`. Reuse the result for every later call:

• [ ] Take the absolute path of this SKILL.md you just read and drop the trailing /SKILL.md. That directory is ``.
• [ ] Verify by running bash /scripts/boomi-env-check.sh. If bash reports "No such file," stop and re-locate the skill rather than guessing the path. (Doubles as your .env status check — see § First-Time User Detection.)
• [ ] Once resolved, treat ` as a fixed value for the session. Every subsequent invocation must re-emit the same path string verbatim — drift between calls (e.g. dropping skills/boomi-integration/`) produces "No such file" errors even when the first call worked.

Run scripts from the project workspace directory (so .env and active-development/ resolve correctly), but always invoke them with the full absolute /scripts/... path.

Documentation Architecture

SKILL.md is the navigation hub: This file contains file references and routing guidance. Other documentation files contain minimal cross-references by design - this prevents deep hierarchical dependencies (which causes skimming at lower levels) and keeps navigation centralized.

Complex tasks require multiple files: Most Boomi development tasks require consulting 3-5+ documentation files together. The "Use when" guidance throughout this file indicates which combinations to load for specific scenarios.

Common multi-file workflows:

• Adding any step: BOOMITHINKING.md + processcomponent.md + steps/[step].md + dependency component docs
• Creating connectors: connectioncomponent.md + operationcomponent.md + connectorstep.md + BOOMITHINKING.md
• REST API on Advanced atom: apiservicecomponent.md + webservicesserverstartshapeoperation.md + processcomponent.md + apiconversionpatterns.md
• Map transformations: mapcomponent.md + mapcomponent_functions.md + source/target profile docs
• Event Streams: eventstreamsconnection + operation + steps + platformentities/eventstreams.md
• B2B/EDI Trading Partners: tradingpartnercomponent.md + tradingpartnersteps.md + ediprofilecomponent.md + platformentities/edib2b.md
• Disk V2 (File System): diskv2connectioncomponent + diskv2connectoroperationcomponent + diskv2connector_step
• MFT (Managed File Transfer): mftconnectioncomponent + mftconnectoroperationcomponent + mftconnector_step
• Mail (IMAP) — Email send/receive/move: mailimapconnectioncomponent + mailimapconnectoroperationcomponent + mailimapconnectorstep + (documentcachecomponent for attachments)
• MCP Server (AI Tool Exposure): mcpserverconnectioncomponent + mcpserveroperationcomponent + mcpserverstartstep + platformentities/mcp_server.md
• Agent Step (AI Agent in process): agent_step.md
• Flow Services: fssoperationcomponent + fssstartstep + flowservicecomponent + platform_entities/flow.md
• Debugging: boomierrorreference.md + relevant step/component docs
• Branch & Merge (opt-in only): branchmergeguide.md + clitoolreference.md branch workflows section
• Version management: versionmanagementguide.md + clitoolreference.md version management section

First-Time User Detection

§ Running CLI tools already verifies ` and reports .env status via boomi-env-check.sh. If bash /scripts/boomi-folder-create.sh --test-connection fails, route the user through references/guides/useronboardingguide.md or /bc-integration:env-setup-guide`.

Connection Discovery & Credential Security

Connection re-use is recommended. Pulling existing connections keeps credentials out of the conversation. Offer the connection discovery workflow first, but respect the user's choice if they prefer to provide credentials directly. See references/BOOMI_THINKING.md § Connection Discovery for the full workflow.

Workspace Organization & Knowledge Base

Physical Directory Structure & Documentation Inventory

Core Mental Models:

• references/BOOMI_THINKING.md - Core mental models and development philosophy (always read first)
• references/guides/boomi_patterns.md - Step-by-step implementation recipes for common integration scenarios (read when designing a new process or refactoring significantly)
• references/guides/boomi_error_reference.md - Error patterns, silent failures, and troubleshooting (read early in any troubleshooting effort)
• references/guides/boomi_platform_reference.md - Platform services catalog (DataHub, Flow, API Gateway, B2B/EDI) with scope boundaries (read when designing a new process, evaluating designs that expand beyond integration, or refactoring significantly)
• references/guides/problem_solving_guide.md - Tiered escalation framework for handling unexpected situations, unknown components, and undocumented scenarios (read when encountering undocumented components or unexpected behavior)

Step Type References: Step documentation in references/steps/ covers all in-scope step types with working examples.

Component Type References: Component documentation in references/components/ covers all in-scope component types with working examples.

Reading Discipline

Required Reading for Boomi Work: When working on any Boomi process or component modifications:

1. Always start by reading references/BOOMI_THINKING.md - contains essential Boomi development philosophy and patterns
2. Then load specific references based on the task:

• Building/modifying a process? Load references/components/process_component.md
• Adding a specific step? Load references/steps/[step_type].md (e.g., rest_connector_step.md, map_step.md)
• Creating a component? Load references/components/[component_type].md

READ BEFORE WRITING: Always read references/steps/[step_type].md completely before generating XML. Validation errors typically mean the XML doesn't match documented structure.

Large Profiles: When attempting to read an XML profile file and encountering a "file too large" error, immediately run boomi-profile-inspect.py (Python stdlib) on it. This generates a searchable distilled_.json file alongside the source profile XML. Search that file for field keys/paths, and grep the original XML by key if comments are needed.

External Documentation Strategy: Default to the local references/ content — it is curated and verified for this skill's use cases. As a fallback, developer.boomi.com and help.boomi.com are fetchable and can supplement local docs. community.boomi.com remains inaccessible (JavaScript-heavy). If all sources fail: ask the user to paste content. Do not proceed without critical information.

Skill Repository:

 boomi-integration/                   # full skill path provided at skill load time
├── SKILL.md                     # Main skill definition and navigation hub
├── README.md                    # Installation and setup for new users
│
├── references/             # Comprehensive Boomi platform knowledge base
│   ├── BOOMI_THINKING.md        # Core mental models and development philosophy (always read first)
│   │
│   ├── guides/                  # Topical guidance and workflow docs
│   │   ├── user_onboarding_guide.md     # First-time user setup: .env creation, connection testing
│   │   ├── cli_tool_reference.md        # Read when: using CLI tools - command syntax, workflows, sync state, error recovery
│   │   ├── pulling_components.md        # Read when: user provides platform URL or component ID to work on
│   │   ├── process_testing_guide.md     # Read when: deploying and testing processes - execution workflows, log analysis
│   │   ├── api_conversion_patterns.md   # Read when: converting process to API or building WSS listeners
│   │   ├── boomi_patterns.md            # Step-by-step implementation recipes for common scenarios
│   │   ├── boomi_error_reference.md     # Error patterns, silent failures, and troubleshooting
│   │   ├── problem_solving_guide.md     # Tiered escalation framework for unknown components, unexpected behavior, undocumented scenarios
│   │   ├── boomi_platform_reference.md  # Platform services catalog (DataHub, Flow, APIM, B2B/EDI) with scope boundaries
│   │   ├── api_endpoint_guide.md        # Sample developer friendly APIs for experimentation
│   │   ├── branch_merge_guide.md        # Read when: user explicitly requests branch/merge workflows — branch lifecycle, merge requests, conflict resolution (opt-in, do not use unless directed)
│   │   ├── branch_merge_api_behavior.md # API-level branch semantics — last resort when CLI tools don't cover an edge case. Use branch_merge_guide.md if at all possible.
│   │   ├── version_management_guide.md  # Read when: viewing component version history, comparing versions, or rolling back to a prior version
│   │   ├── event_streams_rest_api.md    # REST produce API reference (auth, payloads, limits) — for direct REST integration with Event Streams topics
│   │   └── edi_sap_patterns.md          # Read when: EDI ↔ SAP IDoc integration — IDoc segment hierarchy/cardinality, qualifier-driven routing (DTM/NAD → IDoc fields), composite decomposition, cross-reference table design, Z-segment handling
│   │
│   ├── components/              # Component XML reference documentation
│   │   ├── process_component.md              # Use when: creating/editing process XML - shape positioning, dragpoint connections, canvas structure, and process options (Process Mode/workload, allowSimultaneous, updateRunDates, enableUserLog, purgeDataImmediately, processLogOnErrorOnly, stopProcessingIfZeroDocuments)
│   │   ├── process_route_component.md         # Use when: building the routing table for a Process Route step - mapping route keys to subprocess GUIDs and return paths to subprocess Return Documents shapes. Pairs with steps/process_route_step.md.
│   │   ├── json_profile_component.md         # Use when: defining JSON document schemas for validation, accessing JSON fields in Maps/Set Properties, consolidating array elements
│   │   ├── xml_profile_component.md          # Use when: defining XML document schemas with namespaces, accessing XML elements/attributes in Maps/Set Properties
│   │   ├── flat_file_profile_component.md    # Use when: defining CSV/delimited file schemas, creating placeholder profiles for Map component sources
│   │   ├── edi_profile_component.md          # Use when: defining EDI document schemas, troubleshooting EDI parsing failures, understanding Boomi-specific EDI configuration. Includes Transaction Set ID → GS-01 mapping and HIPAA GS-08 Implementation Convention codes.
│   │   ├── database_profile_component.md     # type: "profile.db". Use when: defining request/response structure for the Database (Legacy) connector - SQL statements, stored procedures, dynamic vs standard insert/update/delete, result-set columns. NOT for Database V2 (which uses JSON profiles).
│   │   ├── map_component.md                  # Use when: creating field-to-field transformations between profiles, understanding map generation rules and mapping patterns
│   │   ├── map_component_functions.md        # Use when: applying transformations within maps - string manipulation, date formatting, conditionals, math, lookups
│   │   ├── map_script_component.md           # Use when: creating a standalone reusable map-scripting component (type="script.mapping", Groovy or JavaScript) and referencing it from a Map's Scripting function instead of an inline script
│   │   ├── rest_connection_component.md      # connectorType: "officialboomi-X3979C-rest-prod". Use when: creating REST API connections - base URLs, authentication patterns, timeouts, connection pooling
│   │   ├── rest_connector_operation_component.md # Use when: defining REST operations - HTTP methods, resource paths, headers, query parameters, request/response profiles
│   │   ├── http_client_component.md          # connectorType: "http". Use when: working with existing HTTP Client assets, or when the user explicitly requests HTTP Client. Never select HTTP over REST on agent judgment alone
│   │   ├── database_connection_component.md      # subType: "database" — Database (Legacy). Use when: creating Database (Legacy) connections - host/port/dbname, driver type, connection pooling, write-SQL-to-file. NOT Database V2.
│   │   ├── databasev2_connection_component.md    # connectorType: "officialboomi-X3979C-dbv2da-prod". Use when: creating database connections - JDBC URLs, drivers, credentials, connection management
│   │   ├── database_connector_operation_component.md   # subType: "database" — Database (Legacy). Use when: defining Database (Legacy) Get/Send actions - commit options, JDBC batching, batch count/max rows, ReadProfile/WriteProfile references. SQL lives in the profile.db. NOT Database V2.
│   │   ├── databasev2_connector_operation_component.md # Use when: defining database operations - SQL queries, dynamic operations, GET/INSERT/UPDATE/DELETE, response profiles
│   │   ├── event_streams_connection_component.md # connectorType: "officialboomi-X3979C-events-prod". Use when: creating Boomi Event Streams connections - environment tokens, cloud service authentication
│   │   ├── event_streams_listen_operation_component.md # Use when: defining Listen operations for continuous event-driven or pub/sub processing (start shape subscribers); dead-letter queue behavior (Shared + transacted + maxRetries)
│   │   ├── event_streams_consume_operation_component.md # Use when: defining Consume operations for on-demand message batch retrieval (mid-process - not event triggered or pub/sub); reprocessing a dead-letter queue (consumeFromDeadLetter)
│   │   ├── event_streams_produce_operation_component.md # Use when: defining Produce operations for publishing messages to Boomi Event Streams topics (pub/sub publishers)
│   │   ├── salesforce_connection_component.md    # connectorType: "salesforce". Use when: working with Salesforce connections (GUI-created only, but able to be used by this skill) - OAuth flows, session authentication
│   │   ├── salesforce_connector_operation_component.md # Use when: working with existing Salesforce operations (GUI-imported) - filters, field selection, query options
│   │   ├── boomi_for_sap_connection_component.md # connectorType: "invixoconsultinggroupas-OZI90V-boomia-prod". Use when: creating SAP connections via Boomi for SAP Core - endpoint URLs, credentials, timeouts
│   │   ├── boomi_for_sap_connector_operation_component.md # Use when: defining SAP object queries with filters and field selection, working with Core-exposed services
│   │   ├── custom_connector_connection_component.md # Use when: creating connections for custom SDK connectors - connector type format, GenericConnectionConfig structure
│   │   ├── diskv2_connection_component.md       # connectorType: "disk-sdk". Use when: creating Disk V2 connections - local/network file system access, directory configuration, cloud runtime restrictions
│   │   ├── diskv2_connector_operation_component.md # Use when: defining Disk V2 operations - file CREATE/UPSERT/GET/QUERY/LIST/DELETE/LISTEN, filters, actionIfFileExists, directory overrides
│   │   ├── mft_connection_component.md         # connectorType: "thru-8SHH0W-thrumf-technology". Use when: creating MFT connections - Thru MFT partner c

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [OfficialBoomi](https://github.com/OfficialBoomi)
- **Source:** [OfficialBoomi/bc-integration](https://github.com/OfficialBoomi/bc-integration)
- **License:** BSD-2-Clause

Install and usage instructions live in the source repository linked above.