This is an automated email from the ASF dual-hosted git repository. luigidemasi pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-kit.git
commit 58b42afad7b4794bcff7f9b40e335dae21de5044 Author: Luigi De Masi <[email protected]> AuthorDate: Fri Oct 23 09:02:44 2026 +0200 docs: write the Getting started pages for camel.apache.org Replace the seven Getting started stubs of the Antora component with the rewritten content: install and first project, supported AI agents, the greenfield workflow, the migration workflow and the MuleSoft, BizTalk and Camel 2.x/3.x platform pages. The text is rewritten from the standalone website and the repository documentation into the Camel documentation register, and every command, option, version and mapping was checked against README.md, docs/commands.md, docs/user-guide.md, docs/antigravity.md, camel-kit-workflow.yaml, distribution.properties, the camel-migrate guides and the graph parsers. Hugo shortcodes are replaced by native AsciiDoc: tabs blocks for the install channels and the BizTalk pipelines, collapsible blocks for the interview examples and the troubleshooting entries, titled listings for the before/after examples, literal blocks for file trees. Links into the Camel documentation use xref:manual:: and xref:components:: targets. A new camel-kit-snapshot-version attribute in antora.yml keeps the snapshot version out of the pages. Built locally with Antora 3.2 and the Camel website UI bundle at log failure level warn: 27 pages, no warnings, no absolute camel.apache.org links in the generated HTML. --- docs/antora.yml | 1 + docs/modules/ROOT/pages/agents.adoc | 181 +++++++++++++- docs/modules/ROOT/pages/getting-started.adoc | 269 +++++++++++++++++++- docs/modules/ROOT/pages/greenfield.adoc | 249 +++++++++++++++++- docs/modules/ROOT/pages/migration-biztalk.adoc | 221 +++++++++++++++- .../ROOT/pages/migration-camel-upgrade.adoc | 237 +++++++++++++++++- docs/modules/ROOT/pages/migration-mulesoft.adoc | 277 ++++++++++++++++++++- docs/modules/ROOT/pages/migration.adoc | 228 ++++++++++++++++- 8 files changed, 1656 insertions(+), 7 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index 6e92f56d..2b349cf0 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -26,5 +26,6 @@ asciidoc: attributes: # Keep in step with distribution.properties and the README release channels camel-kit-version: 0.4.1 + camel-kit-snapshot-version: 0.4.2-SNAPSHOT camel-kit-knowledge-version: 0.0.2 camel-version: 4.22.1 diff --git a/docs/modules/ROOT/pages/agents.adoc b/docs/modules/ROOT/pages/agents.adoc index 5db2c3ea..fca1263d 100644 --- a/docs/modules/ROOT/pages/agents.adoc +++ b/docs/modules/ROOT/pages/agents.adoc @@ -1,3 +1,182 @@ = Supported AI agents -This page is written in a following documentation pull request. +`camel-kit init --ai <target>` generates the project layout for one coding agent. All targets share the same +Markdown skills; `init` adapts them with agent-specific traits and writes the agent's native configuration, so the +workflow is the same everywhere and only the way you invoke it differs. + +[cols="1,1,2"] +|=== +| Agent | Init flag | Start the workflow + +| Anthropic Claude Code | `--ai claude` | `/camel-start` +| IBM Bob 2 (default) | `--ai bob2` | `$camel-start` in Bob Shell, `/camel-start` in Bob IDE +| Google Antigravity | `--ai antigravity` | `/camel-start`, or ask for the `camel-start` skill by name +| OpenAI Codex CLI | `--ai codex` | `$camel-start` after trusting the repository +| GitHub Copilot CLI | `--ai copilot` | Ask Copilot to "Use the `/camel-start` skill" +| Pi | `--ai pi` | `/skill:camel-start` after `/trust` +| Qwen Code | `--ai qwen` | `/camel-start` +| OpenCode | `--ai opencode` | `/camel-start` +|=== + +The generated assets and the MCP configuration file of each target are listed in +xref:index.adoc#agents[the overview]. Every target gets the same three MCP servers, `camel` (catalog, route +validation, migration and security analysis), `camel-knowledge` (documentation, CVE, release and component search) +and `citrus` (test actions, endpoints and schemas), configured as local JBang processes whose versions come from the +Camel Kit distribution. See xref:mcp.adoc[]. + +The pipeline skills delegate independent implementation and review tasks to fresh subagent contexts where the agent +supports it. Where it does not, the skills run inline in the main session and record the missing isolation in their +reports. + +[[claude]] +== Anthropic Claude Code + +`init` writes `CLAUDE.md` (which imports `AGENTS.md`), the slash commands under `.claude/commands/`, the skills under +`.claude/skills/`, project settings in `.claude/settings.json` and the MCP servers in `.mcp.json`. Start with +`/camel-start`. During `/camel-execute`, independent tasks of the same wave are dispatched to parallel subagents with +isolated context windows. + +[[bob2]] +== IBM Bob 2 + +Use `--ai bob2` for both Bob Shell and Bob IDE; the generated assets are verified with Bob Shell 2.0.2 and Bob IDE +2.1.0. `init` writes `.bob/custom_modes.yaml`, rules, the shared skills under `.bob/skills/`, scoped agent presets +under `.bob/agents/`, the role personas under `.bob/personas/` and the MCP servers in `.bob/mcp.json`. + +In Bob Shell, start from the project root, open `/skills` or type `$camel-`, and select one of the nine public +skills: `camel-start`, `camel-brainstorm`, `camel-migrate`, `camel-plan`, `camel-execute`, `camel-validate`, +`camel-ship`, `camel-knowledge` and `camel-debug`. Enter the request after the skill name: + +---- +$camel-migrate MuleSoft flows in src/main/mule +---- + +Bob Shell's native skill picker uses `$camel-*`; its `/` picker holds built-in commands and MCP prompts, so a +`/camel-*` name in this documentation corresponds to a `$camel-*` skill there. Bob IDE exposes the same skills as +`/camel-*`. Legacy command stubs stay installed for compatibility. The four internal helper skills are hidden. + +If a public skill does not appear in the picker, run `camel-kit doctor`: it reports each affected `SKILL.md` as +`FAIL` with regeneration instructions. Regenerate from the project root with +`camel-kit init --here --ai bob2 --force` (after committing or backing up customized generated files) and restart Bob. + +[[antigravity]] +== Google Antigravity + +Install Antigravity following https://antigravity.google/docs/getting-started[Google's getting-started guide], then: + +[source,bash] +---- +camel-kit init my-integration --ai antigravity +---- + +`init` writes `AGENTS.md`, the skills under `.agents/skills/`, two custom agents under `.agents/agents/` +(`camel-worker` with file and sandboxed command tools, `camel-reviewer` with read and search tools plus the +inherited MCP access), the role +personas under `.agents/camel-kit-personas/` and the three MCP servers in `.agents/mcp_config.json`. Open the +project root in Antigravity and invoke `/camel-start` in the CLI, or ask it to use the `camel-start` skill by name; +`/skills` lists the native skills and `/mcp` the connections. + +The primary conversation owns questions, approvals, orchestration and report writes, and dispatches independent +tasks with the native `invoke_subagent`; the children inherit the workspace permissions and MCP servers. Tool calls +stay subject to Antigravity's permissions: Camel Kit generates no auto-approval policy. Reinitialization preserves +unrelated MCP servers, settings and comments in `mcp_config.json`, which must contain a JSON object (`{}` when empty). + +[[codex]] +== OpenAI Codex CLI + +[source,bash] +---- +camel-kit init my-integration --ai codex +cd my-integration +codex +---- + +`init` writes `AGENTS.md`, the skills under `.agents/skills/`, the custom agent roles under `.codex/agents/` +(planner, implementer, tester, validator, migrator, catalog researcher, security reviewer and a Ship worker) and the +three MCP servers in `.codex/config.toml`. It does not create `.codex/commands/`: Codex discovers the skills +directly, so you start with `$camel-start` after trusting the repository, and inspect skills with `/skills` and +servers with `/mcp`. + +Codex loads the repository `.codex/` configuration only for trusted projects. Review the repository before trusting +it; until then the custom agents and the MCP servers are not active. The setup stays repository-scoped: Camel Kit +does not edit `~/.codex/config.toml`, credentials or login state, generates no hooks, and does not loosen the +sandbox or the approval policy. Keep the sandbox enabled and grant only the narrow approval needed when a command +is blocked: repository trust lets the project configuration load, it is not a reason to approve every command. Each generated MCP server table carries an exact tool allowlist and +`default_tools_approval_mode = "prompt"`. If `.codex/config.toml` already exists with valid unrelated settings they +are preserved; invalid TOML or a conflicting server table makes `init` fail without changing the file. + +`camel-kit doctor` validates the TOML, the three server tables and their allowlists, the prompt approval defaults, +the skills, the required custom-agent fields and the read-only sandbox of the research and security agents. + +[[copilot]] +== GitHub Copilot CLI + +`init` writes `.github/copilot-instructions.md`, the skills under `.github/skills/`, the custom agents under +`.github/agents/`, the MCP servers in `.github/mcp.json` and a safety hook in `.github/hooks/camel-kit-safety.json` +that denies destructive or secret-sensitive shell commands while leaving the normal permission prompts in place. +Start by asking Copilot to "Use the `/camel-start` skill"; `/skills list` shows the project skills. + +[[pi]] +== Pi + +[source,bash] +---- +camel-kit init my-integration --ai pi +cd my-integration +pi install npm:[email protected] +---- + +`init` writes `AGENTS.md`, the skills under `.pi/skills/`, prompt templates under `.pi/prompts/`, `.mcp.json` for +`pi-mcp-adapter`, and a guard extension (`.pi/extensions/camel-kit-guard.ts` with its JSON policy). In Pi, trust the +project with `/trust`, then run `/skill:camel-start`. Headless checks must use `pi -a`. + +Pi has no native subagents: the pipeline runs in the main session and records the missing isolation. For isolated +read-only research, start a separate Pi session with constrained tools, for example `pi --tools read,grep,find,ls`, +and bring the findings back. + +[[qwen]] +== Qwen Code + +`init` writes `QWEN.md`, the commands under `.qwen/commands/`, the skills under `.qwen/skills/`, four bounded leaf +agents under `.qwen/agents/` (implementer, reviewer, tester, validator), the personas under +`.qwen/camel-kit-personas/` and the MCP servers in `.qwen/settings.json`. Start with `/camel-start`. Interviews, +approvals and phase handoffs stay in the primary session; only bounded work goes to the leaf agents. + +[[opencode]] +== OpenCode + +`init` writes `AGENTS.md`, the commands under `.opencode/commands/`, the skills under `.opencode/skills/`, the agent +definitions under `.opencode/agents/`, the personas under `.opencode/camel-kit-personas/` and the MCP servers in +`opencode.json`. Start with `/camel-start`. When a project configuration already exists (`opencode.json`, +`opencode.jsonc`, or the same files under `.opencode/`), `init` preserves unrelated settings, permissions and MCP +servers and writes its own entries to the highest-precedence file; invalid or conflicting configuration fails before +any file is changed. The generated executor can delegate to allowlisted child agents one level deep; you can also +address them directly with the `@agent-name` syntax. + +[[retired-targets]] +== Retired targets + +Camel Kit 0.4.0 replaced the `gemini` target with Google Antigravity and removed IBM Bob v1. Reinitialize an +existing project from its root with the replacement target, then check it: + +[source,bash] +---- +# Former Gemini target +camel-kit init --here --ai antigravity --force + +# Former IBM Bob v1 target +camel-kit init --here --ai bob2 --force + +camel-kit doctor +---- + +Before reinitializing, `.agents/mcp_config.json` must be valid JSON without duplicate keys (`doctor` reports +duplicates as failures), and `AGENTS.md`, `GEMINI.md` and everything under `.agents/` must be real files or +directories, so replace symbolic links first; these checks run before any project file is changed. +`--force` replaces the generated `AGENTS.md`, skills and configuration, so preserve custom additions to those files +first; custom project rules can live in `GEMINI.md`, which Antigravity also reads. Antigravity reinitialization removes +the four old Camel Kit `@.gemini/...` imports from `GEMINI.md` and keeps custom text, imports and other `.gemini/` +files. Move custom MCP servers from `.gemini/settings.json` to `.agents/mcp_config.json` using Google's MCP schema, +and custom skills from `.gemini/skills/<name>/` to `.agents/skills/<name>/`. Bob 2 reinitialization replaces the +generated gate skills and modes with the shared pipeline and native subagents, removing only the known obsolete Bob +v1 mode-rule files. diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index 8ed5fc35..bc6f150a 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -1,3 +1,270 @@ = Install and first project -This page is written in a following documentation pull request. +Camel Kit runs as a standalone command-line tool installed with JBang, or as a plugin of +xref:manual::camel-jbang.adoc[Camel JBang]. Both forms provide the same commands (`init`, `doctor`, `doc`, `graph`, +`plan`, `nextId`, `ship`) and the same eight AI targets. The examples on this page use the standalone form, +`camel-kit`; replace it with `camel kit` when you use the plugin. + +== Prerequisites + +[cols="1,2,2"] +|=== +| Requirement | Purpose | Install + +| Java 17 or later +| Runtime for Camel Kit, Camel JBang and the generated projects +| SDKMAN, Adoptium or your package manager + +| https://www.jbang.dev/[JBang] +| Launcher for Camel Kit and for the MCP servers it configures +| See the installation commands below + +| xref:manual::camel-jbang.adoc[Camel JBang] +| `camel run` and `camel run --check` for route execution and validation +| `jbang app install camel@apache/camel` + +| Camel JBang test plugin +| `camel test run` for the Citrus integration tests in the verification loop +| `camel plugin add test` + +| Docker (conditional) +| Environment probes for external services and full Citrus/Testcontainers verification +| Docker Engine or Docker Desktop +|=== + +Camel JBang and its test plugin are needed for the complete execution and verification loops. When Docker is not +available, the checks that need containers are reported as skipped; design, planning and the container-free checks +still work. `camel-kit init` checks Java, JBang, Camel JBang and the test plugin and reports missing tools as +warnings without stopping. + +== Release channels + +This documentation describes Camel Kit {camel-kit-version}, which pairs with Knowledge MCP +{camel-kit-knowledge-version}. Pin the release when you need a reproducible installation. + +[cols="1,2,1"] +|=== +| Channel | Install source | Version + +| Release +| Tagged JBang catalog, or the Camel JBang plugin from Maven Central +| `{camel-kit-version}` + +| Development +| Unqualified JBang catalog alias, or a source build +| `{camel-kit-snapshot-version}` +|=== + +The unqualified catalog alias follows the latest deployed snapshot, which may lag the `main` branch. Build from source +for an exact revision. + +[[install]] +== Install + +[tabs] +==== +Standalone (JBang):: ++ +-- +[source,bash,subs="attributes+"] +---- +# Install JBang (if not already installed) +curl -Ls https://sh.jbang.dev | bash -s - app setup # Linux/macOS +iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" # Windows PowerShell + +# Install the release globally +jbang app install camel-kit@luigidemasi/camel-kit/camel-kit-{camel-kit-version} + +# Verify: prints {camel-kit-version} +camel-kit --version +---- + +To run the release once without installing it: + +[source,bash,subs="attributes+"] +---- +jbang run camel-kit@luigidemasi/camel-kit/camel-kit-{camel-kit-version} \ + init my-integration --ai claude +---- +-- + +Camel JBang plugin:: ++ +-- +[source,bash,subs="attributes+"] +---- +camel plugin add kit \ + --gav io.github.luigidemasi:camel-jbang-plugin-kit:{camel-kit-version} \ + --description "Design Apache Camel Integrations with AI" + +camel kit init my-integration --ai claude +---- +-- + +Development snapshot:: ++ +-- +[source,bash,subs="attributes+"] +---- +# Latest deployed {camel-kit-snapshot-version} +jbang app install --force camel-kit@luigidemasi/camel-kit +---- +-- + +Build from source:: ++ +-- +[source,bash,subs="attributes+"] +---- +git clone https://github.com/apache/camel-kit.git +cd camel-kit +./mvnw clean install -DskipTests + +# Install the development version globally via JBang +jbang app install --name camel-kit --force \ + camel-kit-main/src/main/jbang/main/CamelKit.java + +# Or install the matching Camel JBang plugin from the local Maven repository +camel plugin add kit \ + --gav org.apache.camel:camel-jbang-plugin-kit:{camel-kit-snapshot-version} \ + --description "Design Apache Camel Integrations with AI" + +camel-kit --help +---- + +The Knowledge MCP server (documentation search, CVE tracking, component catalog) is built from its own repository: + +[source,bash] +---- +git clone https://github.com/luigidemasi/camel-kit-knowledge.git +cd camel-kit-knowledge +./mvnw clean install -DskipTests +---- +-- +==== + +NOTE: The released {camel-kit-version} artifacts are published under the JBang catalog `luigidemasi/camel-kit` and +the Maven coordinate `io.github.luigidemasi:camel-jbang-plugin-kit`. Development snapshots built from +`apache/camel-kit` use the `org.apache.camel` group. The first release from the Apache repository will change the +release coordinates; this page is updated with it. + +[[upgrading]] +== Upgrading + +Reinstall the standalone CLI with `jbang app install --force` and the release alias above, or run the plugin +installation again. To apply updated generated assets to an existing project, commit or back up customized generated +files, then run `camel-kit init --here --ai <your-agent> --force` from the project root. This rewrites the generated +assets. + +From 0.4.0:: +Camel Main, Camel Spring Boot and Camel MCP default to Camel {camel-version}; the supported older LTS patch is +4.18.4. Spring Boot uses 4.1.1. Camel {camel-version} maps to Forage 1.6.1. Version {camel-kit-version} also updates +the shared generation and review guidance to prefer verified declarative bean construction after Forage and component +configuration (see xref:forage.adoc[]), and Knowledge MCP {camel-kit-knowledge-version} validates endpoints against +the Camel {camel-version} catalog. + +From 0.3.1:: +The `gemini` and `bob` targets were removed in 0.4.0 and replaced by `antigravity` and `bob2` (the default). +Reinitialize with the replacement target; see xref:agents.adoc#retired-targets[Retired targets]. + +[[init]] +== Create a project + +[source,bash] +---- +camel-kit init my-integration --ai claude +cd my-integration +---- + +`init` creates the directory, runs the prerequisite check, and generates the shared project files plus the +agent-native assets selected by `--ai` (see xref:agents.adoc[] for the eight targets; `bob2` is the default). To add +Camel Kit to an existing directory, for example a project to migrate, run it with `--here`: + +[source,bash] +---- +camel-kit init --here --ai claude --source-platform mulesoft +---- + +If the directory already contains `AGENTS.md` or `.camel-kit/`, `init` warns and exits; pass `--force` to overwrite +the generated files. + +What every target gets:: +* `AGENTS.md`, or the agent's equivalent entry file, with the routing table for the skills. +* The agent-native skills and entry points, for example `.claude/commands/` and `.claude/skills/` for Claude Code, + or `.agents/skills/` for Codex. +* `docs/constitution.md`, the architecture rules every generated route must follow (see xref:constitution.adoc[]). +* `docs/flows/`, `test/data/` and `schemas/`, empty scaffolds; pipeline artifacts use the selected runtime's paths. +* `.camel-kit/` with the project configuration, cached catalogs and templates, and later the pipeline state. +* The MCP configuration for the target: JSON for most agents, `.codex/config.toml` for Codex, `.mcp.json` read + through `pi-mcp-adapter` for Pi. +* `mvnw`, `mvnw.cmd` and `.mvn/wrapper/maven-wrapper.properties`. + +=== Configuration + +All defaults (Camel version, BOM versions, MCP server versions) come from the `distribution.properties` file bundled +in Camel Kit. Three layers override them, the later winning: + +. the built-in defaults; +. `~/.camel-kit/config.properties`, or the file given with `-c`; +. `-p key=value` flags, repeatable. + +[source,bash] +---- +camel-kit init my-integration --ai claude -p "camel.main.version=4.18.4" +camel-kit init my-integration --ai claude -c /path/to/my-config.properties +---- + +The most common keys are `camel.main.version`, `camel.springboot.version`, `camel.quarkus.version`, +`quarkus.platform.version`, `knowledge.mcp.version` and `citrus.version`. See xref:commands.adoc[] for the full +option list, including `--no-fetch` and `--silent`. + +=== Check the workspace + +[source,bash] +---- +camel-kit doctor +camel-kit doctor --json # for automation +---- + +`doctor` checks the generated configuration, command stubs where the target uses them, skill files, MCP filtering and +permission fields, the project graph, the command prefix, the prerequisites and common stale generated references. It +prints `PASS`, `WARN` and `FAIL` findings with remediation text. Missing external tools such as JBang are warnings; +broken generated workspace files are failures. + +[[first-command]] +== Run the first command + +Open your coding agent in the project directory and start the router: + +---- +/camel-start +---- + +`/camel-start` reads the project state and routes to the right stage: migration for an existing MuleSoft, BizTalk, +Fuse or Camel 2.x/3.x source, planning for an approved design, execution for a plan, validation for generated routes, +debugging for a broken project outside a pipeline, and the design interview for everything else. You can also describe +the work in plain words, for example "I want to build an integration that reads from Kafka and writes to a +database"; the agent reads the routing table and invokes the skill. + +The invocation form depends on the agent: `/camel-start` in Claude Code, Bob IDE, Antigravity, Qwen and OpenCode; +`$camel-start` in Bob Shell and Codex; "Use the `/camel-start` skill" in GitHub Copilot CLI; `/skill:camel-start` +in Pi. See xref:agents.adoc[]. + +The first pipeline run needs an active pipeline ID. `init` does not create one, so the agent asks you to create it +before the interview continues: + +[source,bash] +---- +camel-kit nextId kafka-to-database +# Output: 001-kafka-to-database +---- + +The ID names the directory under `docs/camel-kit/` where the pipeline artifacts are written, so you can close the +session and resume later. + +== Where to go next + +* xref:greenfield.adoc[] builds a new integration from requirements to verified routes. +* xref:migration.adoc[] converts an existing MuleSoft, BizTalk, Fuse or Camel 2.x/3.x project. +* xref:pipeline.adoc[] explains the stages, the single approval gate and the Iron Laws. +* xref:commands.adoc[] lists every CLI and slash command option. diff --git a/docs/modules/ROOT/pages/greenfield.adoc b/docs/modules/ROOT/pages/greenfield.adoc index e7ea3f3f..ed5217b8 100644 --- a/docs/modules/ROOT/pages/greenfield.adoc +++ b/docs/modules/ROOT/pages/greenfield.adoc @@ -1,3 +1,250 @@ = Greenfield workflow -This page is written in a following documentation pull request. +The greenfield workflow takes a new integration from requirements to generated routes, tests and runtime +verification evidence. The agent runs a structured interview, writes a design specification that you approve, +decomposes it into tasks, generates the implementation and reports which runtime checks passed, failed or could not +run. The design approval is the only human gate: planning, execution and the final static validation proceed under +it. + +This page follows one example, an order processing integration, through the four stages. See +xref:pipeline.adoc[] for the stage contracts and xref:commands.adoc[] for every option. + +[[init]] +== Initialize the project + +[source,bash] +---- +camel-kit init order-processing --ai claude +cd order-processing +---- + +The agent now has the Camel Kit skills and the three MCP servers. The first pipeline run needs an active pipeline +ID, which `init` does not create; `/camel-brainstorm` asks you to create it when none exists: + +[source,bash] +---- +camel-kit nextId order-processing +# Output: 001-order-processing +---- + +[[design]] +== Design interview (`/camel-brainstorm`) + +Start the interview with `/camel-start` (which routes new work to brainstorm) or directly with `/camel-brainstorm`. +The agent first analyzes any requirements, examples or other project material you provide and does not ask again +for facts that are already resolved; complete material can need no clarification at all. Open questions are asked +one at a time, in three groups: + +* *Project questions* establish the name, the business purpose, the systems landscape and the integration goals or + flow names. +* *Per-flow questions* cover each flow's intent and data, source, transformations, sink and error handling, with + field-mapping, routing and resilience follow-ups only when needed. +* *Cross-cutting questions* cover performance, security, monitoring, remaining constraints and deliberate scope + exclusions; a category that does not apply is recorded with a rationale. + +.Example exchanges from the interview +[%collapsible] +==== +---- +Agent: What business problem does this integration solve? +You: Process incoming orders from an HTTP API, validate them, enrich them with + customer data and send them to the fulfillment system. + +Agent: Where does the data come from and where does it go? +You: Orders arrive as JSON on POST /api/orders. Customer data is in PostgreSQL. + Validated orders go to the Kafka topic "fulfillment.orders". + +Agent: How should the integration handle errors? +You: Invalid orders go to the Kafka topic "orders.invalid" with the validation + error. Database failures retry 3 times with exponential backoff. + +Agent: Which related capabilities should this iteration not implement, and why? +You: No order-status API; it needs a separate security design. +---- +==== + +If no deliberate exclusions remain, the design records *None identified* instead of inventing scope boundaries. +Before assembling the design, the agent verifies every source and sink component against the catalog through the +`camel` MCP server; in the example it confirms that `kafka` exists for the selected Camel version and runtime. + +[[spec]] +== Review and approve the design specification + +The interview produces `docs/camel-kit/001-order-processing/design-spec.md` with six numbered sections: + +[cols="1,3"] +|=== +| Section | Content + +| 1. Executive summary | Business purpose, business value and stakeholders +| 2. Systems landscape | Systems, protocols and source/target roles +| 3. Flow designs | Per flow: source, sink, processing, data, configuration, error handling and the verified + technical choices +| 4. Cross-cutting concerns | Applicable performance, security, monitoring and constraints +| 5. Constitution compliance | How every flow satisfies the eight rules, plus the catalog verification evidence: + matched runtime, platform BOM, returned Camel version, and each artifact's `VERIFIED` result and tool provenance +| 6. Project structure | Planned routes, configuration, tests and supporting artifacts +|=== + +An unnumbered *Not Doing (and Why)* section at the top records each deliberately excluded capability and its +rationale, so implementation and review treat it as a scope boundary. Review the specification carefully: your +approval ("Looks good, let's proceed") authorizes everything downstream. There is no second approval for the plan. + +[[plan]] +== Plan (`/camel-plan`) + +After approval the pipeline invokes `/camel-plan`. It applies the *Not Doing* boundaries and decomposes the design +into route, configuration, dependency, test and conditional infrastructure tasks, each with acceptance criteria, +the catalog-verified components and patterns to use, the files to create and the verification steps. The plan is a +recipe, not the implementation: it contains no generated code. + +[cols="2,3,2,1"] +|=== +| Task | Acceptance criteria | Components and patterns | Wave + +| 1. REST endpoint | Listen at `/api/orders`, POST, return 202 | `platform-http`, `jackson` | 1 +| 2. Validation | Check amount > 0 and customer ID present | `bean`, `choice` | 2 +| 3. Enrichment | Query PostgreSQL, add email and address | `sql`, `jackson` | 2 +| 4. Tax calculation | Compute tax, set total = amount + tax | `bean` | 3 +| 5. Kafka publisher | Publish to `fulfillment.orders` with the order ID as key | `kafka` | 4 +|=== + +Retry and dead-letter behaviour belongs to the affected route tasks unless error delivery is itself a business flow. +A structured metadata block lists each task's files, the logical resources it provides and consumes and its explicit +dependencies; `/camel-execute` derives the waves from it. Tasks in the same wave can run in parallel on agents that +support concurrent dispatch; later waves wait for their dependencies. + +[[execute]] +== Execute (`/camel-execute`) + +`/camel-plan` then invokes `/camel-execute`, which runs all tasks without pausing between them. It first analyzes +the dependency waves, probes the target environment, and batch-verifies the catalog artifacts needed by each wave. +For every task it dispatches the persona and guides declared by the plan: route and configuration tasks use the +internal `camel-implement` skill, test tasks use `camel-test`. Each task then goes through three reviews: + +. *Adversarial review.* A fresh-context moderator and parallel critics inspect the task diff where the agent + supports subagents; single-conversation agents run the critic lenses sequentially and record the missing + isolation. Verified failures go back to implementation. +. *Spec compliance review.* The route matches the task's acceptance criteria without adding capabilities excluded + by *Not Doing (and Why)*. +. *Code quality review.* Constitution compliance: single responsibility, observability, external configuration and + the other rules. + +---- +Wave 1/4: Task 1 (REST endpoint) + - Implementing route... + - Adversarial review: PASS + - Spec compliance: PASS + - Code quality: PASS + - Task 1 complete + +Wave 2/4: running 2 independent tasks concurrently where supported... + Task 2 (Validation) ... PASS + Task 3 (Enrichment) ... PASS +---- + +After all tasks, execute performs a cross-cutting review, dispatches the internal `camel-verify` skill once, and +writes `execution-report.md`. + +[[verify]] +== Runtime verification + +`camel-verify` runs three phases after the environment probe and embeds its evidence in the execution report: + +[cols="1,3,1"] +|=== +| Phase | What happens | Outcome + +| Build or startup smoke +| Spring Boot and Quarkus projects compile with `./mvnw` (or the system `mvn` when there is no wrapper); Camel Main + projects run a startup smoke test instead +| PASS, SKIPPED or FAILED with the reason + +| Test +| Discovers `*.it.yaml` files recursively and runs `camel test run` when the Camel test plugin is available. Tests + that declare Testcontainers also need Docker; container-free and mock-only tests run without it +| Passed-test count, or an explicit skip or failure + +| Report +| Summarizes checks, fixes, failures and skipped phases +| Verification status in the execution report: PASS, PARTIAL, FAIL or NOT_RUN +|=== + +Build and test failures enter bounded classify, fix and retry loops of up to 15 attempts; the Camel Main startup +smoke test allows up to 6. Missing tools skip their dependent checks with a recorded reason. Verification is +informational: it does not block `/camel-execute` from finishing, so read the report and resolve failed or skipped +checks before deployment. See xref:verification.adoc[]. + +[[validate]] +== Validate (`/camel-validate`) + +The pipeline ends with `/camel-validate`, a static quality gate over the generated routes: schemas, endpoint URIs, +project-relative quality thresholds, security, anti-patterns and all constitution rules. It reports findings in +`validation-report.md` without modifying the routes. + +[[artifacts]] +== Pipeline files + +Every stage persists its artifact under `docs/camel-kit/<pipeline-id>/`, so a session can be closed and resumed; +`.camel-kit/pipeline.json` records the active pipeline ID. + +.... +docs/camel-kit/001-order-processing/ + design-spec.md <- brainstorm + implementation-plan.md <- plan + execution-report.md <- execute, including the verification evidence + validation-report.md <- validate +.... + +With Camel Main selected during design, the routes and properties are generated at the project root and no +`pom.xml` is needed: + +.... +order-processing/ + order-reception.camel.yaml + order-validation.camel.yaml + customer-enrichment.camel.yaml + tax-calculation.camel.yaml + kafka-publisher.camel.yaml + application.properties + run.sh + src/test/resources/ + order-reception.camel.it.yaml + ... one .camel.it.yaml file per flow + application-test.properties + jbang.properties + docker-compose.yaml (only when external services require it) +.... + +Spring Boot and Quarkus projects use the Maven source layout instead, with routes under +`src/main/resources/camel/`. + +[[standalone]] +== Standalone stages and amendments + +Every stage can be invoked on its own with a pipeline ID. Plan, execute and validate then read their input from +the artifacts on disk instead of the conversation, and do not invoke the next stage. This supports resuming a +session, triggering single stages from automation, and re-running only what changed: + +---- +/camel-plan 001-order-processing +/camel-execute 001-order-processing +---- + +To change an approved design, run `/camel-brainstorm 001-order-processing`. When `design-spec.md` already exists +the skill enters amend mode: it loads the specification, applies your changes after approval, and marks each +existing direct child stale with `camel-kit doc stale`. Regenerate the stale stages standalone, plan first and then +execute. `camel-kit doc check <artifact>` shows the staleness state of any artifact; see xref:commands.adoc[]. + +== Variations and troubleshooting + +* *Asynchronous processing.* Say so during the interview ("process orders asynchronously with 10 concurrent + threads") and the requirement is recorded in the flow design. +* *Data mapping.* For JSON-to-JSON mapping, DataMapper uses inline Groovy when both schemas are absent or the + mapping has fewer than 20 leaf fields, and XSLT only when the mapping has at least 20 leaf fields and at least one + schema. +* *Several environments.* Ask for dev, staging and production configurations and the agent generates one + `application-<env>.properties` per environment. +* *A route breaks later.* Run `/camel-debug` for a structured diagnosis outside the pipeline; failures during + `/camel-execute` are handled by its own verification loop. +* *Rules too strict.* Edit `docs/constitution.md` before running the pipeline; the eight rules are per project. diff --git a/docs/modules/ROOT/pages/migration-biztalk.adoc b/docs/modules/ROOT/pages/migration-biztalk.adoc index 0c3634c0..6aa80b04 100644 --- a/docs/modules/ROOT/pages/migration-biztalk.adoc +++ b/docs/modules/ROOT/pages/migration-biztalk.adoc @@ -1,3 +1,222 @@ = BizTalk migration -This page is written in a following documentation pull request. +Camel Kit migrates Microsoft BizTalk Server applications (2004 through 2020) to Camel 4 with YAML DSL routes. It +parses orchestrations, maps, pipelines, schemas and port bindings into migration candidates; unsupported or ambiguous +constructs are kept explicit for manual review. The shared steps, the migration package, the approval scope and the +evidence rules are described in xref:migration.adoc[]; this page covers what is specific to BizTalk. + +[[parsed]] +== What is parsed + +[cols="1,1,3"] +|=== +| Artifact | Extension | Content + +| Orchestrations | `.odx` | Business process shapes; 38 shape element names are recognized, and the mapping guide + gives each one a Camel equivalent, marks Suspend as not supported and Group and RoleLinkDeclaration as having no + runtime impact +| Maps | `.btm` | Transformations with functoids; 45 functoid identifiers are recognized and classified into seven + categories (string, math, date, logical, looping, scripting, advanced) +| Pipelines | `.btp` | Receive and send processing stages and their component chains +| Schemas | `.xsd` | Message formats +| Bindings | `.xml` | Port configurations and adapter types, including UTF-16 exports from the BizTalk + Administration Console +|=== + +BizTalk artifacts are detected by the `schemas.microsoft.com/BizTalk` namespace. When the project graph is built +(see xref:graph.adoc[]), the BizTalk parsers record the adapters used per orchestration, the map functoid complexity, +the pipeline component chains and the port bindings, which lets the migration spot proprietary patterns such as +scripting functoids, custom pipeline components and WCF-specific configuration early. + +[[evidence]] +== Evidence and retirement + +`migration-analysis.md` records each BizTalk behavioral assumption and evidence gap with a stable ID, the affected +orchestration or interface, the source evidence, a `Confirmed`, `Inferred` or `Unknown` status, the impact if the +assumption is false, and the validation still required. Adapter similarity or a plausible receive-port mapping is +not treated as proof of compatibility. + +The source-retirement audit corroborates entry roots from Receive Locations and activating receives in the +deployment bindings, then follows constant orchestration calls and supported artifact references. Missing bindings +or assemblies, Direct Binding or subscription behaviour not proven by bindings, dynamic .NET calls, parse failures +and callers outside the selected boundary stay *Unknown*. An `Incremental candidate` strategy requires current +evidence, or explicit operator confirmation, of operator-controlled external routing or of a mutually exclusive +Receive Location or subscription filter that assigns traffic before consumption; bindings can corroborate what is +deployed, but are at most *Inferred* evidence that a control is operative today. + +[[adapters]] +== Adapter mapping + +For each adapter the agent proposes a catalog-verified Camel component when a direct mapping exists; otherwise it +records the gap and asks for a decision. + +[cols="1,1,2"] +|=== +| BizTalk adapter | Camel component | Notes + +| FILE | `file` | +| FTP, FTPS, SFTP | `ftp`, `ftps`, `sftp` (`camel-ftp`) | +| HTTP, HTTPS | Receive: `platform-http`; send: `http` / `https` | The direction determines the component +| SOAP, WCF-BasicHttp, WCF-WSHttp | Receive: `platform-http` with `cxf`; send: `cxf` | WSDL-first services; + WS-Security through CXF interceptors +| WCF-NetTcp | `netty` | Binary TCP, needs a custom codec +| SQL Server, Oracle, IBM Db2 | `sql` (`camel-sql`) | `jdbc` for batch operations +| MSMQ | Decision required | See below +| MQ Series | `jms` with the IBM MQ client | +| SMTP, POP3, IMAP | `smtp`, `pop3`, `imap` (`camel-mail`) | `mail` is the artifact name, not a scheme +| Azure Service Bus, Event Hubs, Blob Storage | `azure-servicebus`, `azure-eventhubs`, `azure-storage-blob` | + BizTalk 2016 or later +|=== + +MSMQ has no Camel equivalent. When it is found, the agent asks you to choose ActiveMQ Artemis through `jms`, +RabbitMQ through `spring-rabbitmq`, Azure Service Bus, or to drop that processing step from the design, and records +the decision. Infrastructure beans such as data sources and connection factories are configured through the Forage +configuration ladder (see xref:forage.adoc[]). + +[[shapes]] +== Orchestration shapes + +[cols="1,2"] +|=== +| BizTalk shape | Camel equivalent + +| Receive (activating) | `from` consumer, the route entry point +| Send, Invoke | `to` producer +| Construct Message, Message Assignment | `setBody`, `setHeader` +| Transform | DataMapper mapping, inline Groovy or XSLT as selected (see <<maps>>) +| Decide, Switch | `choice` EIP +| Loop, While, Until | `loop` EIP +| ForEach | `split` EIP +| Parallel Actions | `multicast` with `parallelProcessing` +| Listen | `choice` with a timeout +| Call Orchestration | `to("direct:...")` +| Start Orchestration | `wireTap` or `to("seda:...")` +| Scope, Catch, Throw, Terminate | `doTry`, `doCatch`, `throwException`, `stop` +| AtomicTransaction | `transacted` +| LongRunningTransaction, CompensationScope, Compensate | Saga EIP and its compensation +| Delay | `delay` EIP +| Expression | `process` or a Groovy script +| Variable and correlation declarations | `setVariable`, `setHeader`, `correlationExpression` +| CallRules, CallPolicy | `bean` or a rules engine integration +| Suspend | Not supported: BizTalk dehydration has no Camel equivalent; the agent flags it for a redesign, for + example a Dead Letter Channel or a manual hold pattern +| Group, RoleLinkDeclaration | No runtime impact +|=== + +[[pipelines]] +== Pipelines + +[tabs] +==== +Receive pipeline:: ++ +-- +[cols="1,2"] +|=== +| Component | Camel pattern + +| XML Disassembler | Candidate: `split` plus the Jackson XML data format with a POJO or list model; otherwise a + generated or custom processor +| Flat File Disassembler | Candidate: Flatpack with a definition or Bindy with an annotated model; otherwise a custom + processor +| JSON Decoder | Jackson JSON data format +| XML Validator | `validator:schema.xsd` +| MIME Decoder | MIME multipart data format (`camel-mail`) +| S/MIME Decoder | Manual, catalog-verified crypto or mail implementation after certificate and keystore review +| Party Resolution, custom components | `bean` or `process`, re-implemented in Groovy or Java +|=== +-- + +Send pipeline:: ++ +-- +[cols="1,2"] +|=== +| Component | Camel pattern + +| XML Assembler | Candidate: Jackson XML data format with a POJO model, aggregating first for batches; envelope + assembly may need a generated or custom processor +| Flat File Assembler | Candidate: Bindy with an annotated model, or a generated or custom serializer +| JSON Encoder | Jackson JSON data format +| MIME Encoder | MIME multipart data format (`camel-mail`) +| S/MIME Encoder | Manual, catalog-verified crypto or mail implementation after certificate and keystore review +| Custom components | `bean` or `process`, re-implemented in Groovy or Java +|=== +-- +==== + +[[maps]] +== Maps and functoids + +A map is first extracted as a complete semantic mapping, then DataMapper selects the engine from the mapping, not +from the functoid names: inline Groovy when both schemas are absent or the mapping has fewer than 20 leaf fields, +XSLT only with at least 20 leaf fields and at least one schema. + +* Direct links contribute a source-to-target field mapping. +* String concatenation, upper and lower case, value mapping, mass copy, record count and nil value functoids are + recorded as typed mappings and rendered by the selected engine (for example `concat()` in XSLT). +* Logical functoids become conditional mappings; a route-level business decision stays a `choice` EIP. +* Looping functoids become collection mappings, or the `split` EIP when they drive the route itself. +* Database lookup functoids map to the `enrich` EIP with `sql`. +* Scripting functoids (C#, VB.NET) are preserved with their input and output semantics and flagged for manual + review; the design may suggest a compatible Groovy replacement, otherwise it records a custom-processor action, + which requires Spring Boot or Quarkus. + +[[example]] +== Example + +The `OrderToInvoiceMap` in this orchestration has at least 20 leaf fields and a schema, so DataMapper selected XSLT. + +.BizTalk orchestration +[source,xml] +---- +<ServiceBody> + <ReceiveShape Name="ReceiveOrder" PortName="OrderPort" Operation="SubmitOrder"/> + <TransformShape Name="MapOrder" Map="OrderToInvoiceMap"/> + <DecisionShape Name="CheckAmount"> + <Branch Expression="OrderAmount > 1000"> + <SendShape Name="SendHighValue" PortName="HighValuePort"/> + </Branch> + <DefaultBranch> + <SendShape Name="SendStandard" PortName="StandardPort"/> + </DefaultBranch> + </DecisionShape> +</ServiceBody> +---- + +.Camel YAML +[source,yaml] +---- +- route: + id: process-order + from: + uri: "platform-http:/api/orders" + parameters: + httpMethodRestrict: POST + steps: + - step: + id: kaoto-datamapper-a1b2c3d4 + steps: + - to: + id: kaoto-datamapper-xslt-a1b2 + uri: "xslt-saxon:kaoto-datamapper-a1b2c3d4.xsl" + - choice: + when: + - simple: "${body.amount} > 1000" + steps: + - to: "direct:high-value-processing" + otherwise: + steps: + - to: "direct:standard-processing" +---- + +[[manual-review]] +== Flagged for manual review + +* Scripting functoids with C# or VB.NET code. +* Custom .NET pipeline components, which need a custom Camel processor. +* The MSMQ adapter, which needs a replacement decision. +* The Suspend shape, which needs a redesign. +* EDI disassemblers and assemblers: no Camel 4 catalog component is assumed; verify the available EDI support in + the catalog, otherwise use a third-party EDI library or a custom processor, then review the mapping. +* External assembly calls in expressions, which need a Java or Groovy reimplementation. diff --git a/docs/modules/ROOT/pages/migration-camel-upgrade.adoc b/docs/modules/ROOT/pages/migration-camel-upgrade.adoc index 379726d0..47aff4ed 100644 --- a/docs/modules/ROOT/pages/migration-camel-upgrade.adoc +++ b/docs/modules/ROOT/pages/migration-camel-upgrade.adoc @@ -1,3 +1,238 @@ = Camel 2.x and 3.x upgrade -This page is written in a following documentation pull request. +Camel Kit modernizes Camel 2.x and 3.x projects, including JBoss Fuse 6.x and 7.x projects, to Camel 4 with YAML DSL +routes. The agent analyzes the existing routes, configuration and deployment artifacts, then generates the updated +project for the runtime you choose: Camel Main, Spring Boot or Quarkus. The shared steps, the migration package, the +approval scope and the evidence rules are described in xref:migration.adoc[]; this page covers what is specific to +a Camel upgrade. The Camel project's own xref:manual::camel-4-migration-guide.adoc[Camel 4 migration guide] lists +every breaking change. + +[[parsed]] +== What is parsed + +[cols="1,2"] +|=== +| Artifact | Content + +| Spring XML and Blueprint XML | Route definitions, endpoints, error handlers, beans, OSGi service wiring +| Java DSL `RouteBuilder` classes | Programmatic routes +| Properties files | Configuration, endpoint URIs, authentication requirements and secret references +| Karaf features | Dependency bundles and feature declarations +| fabric8 descriptors | Container metadata and deployment configuration +|=== + +The platform is detected from `pom.xml` and the sources: `camel-blueprint`, `karaf-maven-plugin`, +`maven-bundle-plugin` or `<blueprint>` XML for ServiceMix/Karaf, `camel-spring-boot-starter` for Spring Boot, +`camel-spring` or `<camelContext>` for Spring XML, and `RouteBuilder` classes without those dependencies for plain +Java DSL. Fuse projects are recognized by `redhat-` or `fuse-` version qualifiers in the Maven dependencies, for +example `camel-core-2.23.2.fuse-7_11_1-00015`; initialize them with `--source-platform camel` (or let `auto` detect +them) and the migration records Red Hat-specific notes. + +[[evidence]] +== Evidence and retirement + +`migration-analysis.md` records each behavioral assumption and evidence gap with a stable ID, the affected route or +interface, the source evidence, a `Confirmed`, `Inferred` or `Unknown` status, the impact if the assumption is +false, and the validation still required. A component rename or a matching endpoint shape is not treated as proof +of compatibility. + +The source-retirement audit corroborates entry roots from structurally parsed external and scheduled consumers, +then follows constant `direct:` and `seda:` references. Dynamic endpoints, reflective or custom dispatch, unresolved +beans or services, parse failures and callers outside the selected boundary stay *Unknown*. An `Incremental +candidate` strategy requires current evidence, or explicit operator confirmation, of an existing external control +such as an operator-controlled gateway or load balancer, a deterministic JMS selector or Kafka partition, a mutually +exclusive source directory or a pre-consumption routing predicate; a consumer endpoint or a route predicate after +consumption is at most *Inferred* evidence that a control is operative today. + +[[components]] +== Component renames + +The mappings below are starting points; every target and its options are verified in the catalog for the selected +Camel version and runtime, and a component that is not listed is checked there too. + +[cols="1,1,2"] +|=== +| Camel 2.x or 3.x | Camel 4.x | Notes + +| `http4`, `https4` | `http`, `https` | Renamed in 3.0 +| `netty4`, `netty4-http` | `netty`, `netty-http` | +| `mina2`, `quartz2`, `mongodb3`, `hdfs2`, `rxjava2` | `mina`, `quartz`, `mongodb`, `hdfs`, `rxjava` | +| `swagger-java` | `openapi-java` | +| `ibatis`, `mqtt` | `mybatis`, `paho` | +| `direct-vm`, `vm` | `direct`, `seda` | Cross-context variants removed in 4.0 +| `aws-*` | `aws2-*` | AWS SDK v2; `aws-swf` was removed, use `aws2-step-functions` +| `dozer` | Removed | Extract the mapping and use DataMapper +| `boon`, `jibx`, `linkedin`, `ironmq`, `etcd`, `ganglia`, `spark-rest`, `chronicle-engine`, `rx-netty` | + Removed | The agent stops and asks; suggested alternatives include `jackson`, `jaxb`, `aws2-sqs`, `consul`, + `micrometer` and `platform-http` +|=== + +HTTP consumers are a special case: `jetty`, `netty-http`, `undertow`, `servlet`, `restlet` and `spark-rest` used in +a `from` URI migrate to `platform-http`, which the runtime serves; `cxf` SOAP consumers stay on `cxf` to keep the +WSDL contract, WS-Security and MTOM; `cxfrs` consumers become REST DSL endpoints with a generated OpenAPI 3 +specification. The same components used as producers keep their original name or move to `http` / `https`. + +Data formats, EIPs and languages have their own rename tables in the skill (for example the `dozer` and `boon` +removals, the EIP attribute renames of 4.0 and the Simple language changes), applied in the same way. + +[[platforms]] +== Platform paths + +Karaf and Blueprint:: +Blueprint XML is not supported in Camel 4. Routes become `.camel.yaml` files; `<cm:property-placeholder>` values +move to `application.properties`; `<bean>` and `<reference>` definitions become named registry or +dependency-injection entries of the target runtime, with infrastructure beans following the Forage configuration +ladder (see xref:forage.adoc[]); OSGi `<service>` exports are removed, and any contract still needed outside OSGi +is recorded for implementation; Karaf features become Maven dependencies in `pom.xml` for Spring Boot and Quarkus, +or `camel.jbang.dependencies` entries in the module-root `application.properties` for Camel Main. The +`maven-bundle-plugin`, OSGi manifest headers and Karaf JAAS configuration are removed or replaced by the runtime's +security. + +Spring XML:: +`<camelContext>` and `<route>` elements become `.camel.yaml` files, `<endpoint>` declarations become inline URIs, +and `<bean>` definitions use the target runtime's bean support, keeping the same IDs. `<routeContext>` fragments +are inlined, since the element is gone in 4.x. + +Java DSL:: +`RouteBuilder` classes are expressed in the YAML design. Required Java API changes in custom processors, such as +`getIn()` and `getOut()` to `getMessage()` and the `javax` to `jakarta` package move, are recorded as +implementation actions for `/camel-execute`; the migration does not auto-edit Java source. Camel Main is offered +only when every Java processor, bean and Blueprint construct can be translated to supported YAML DSL or inline +Groovy. If Java source must remain, choose Spring Boot or Quarkus so it is compiled and packaged by Maven. + +The agent asks which runtime you prefer and generates the matching configuration. + +[[examples]] +== Examples + +=== Spring XML to YAML + +.Spring XML +[source,xml] +---- +<camelContext xmlns="http://camel.apache.org/schema/spring";> + <route id="file-processor"> + <from uri="file:input"/> + <log message="Processing ${header.CamelFileName}"/> + <to uri="file:output"/> + </route> +</camelContext> +---- + +.Camel YAML +[source,yaml] +---- +- route: + id: file-processor + from: + uri: "file:input" + steps: + - log: + message: "Processing ${header.CamelFileName}" + - to: "file:output" +---- + +=== Blueprint bean to Forage configuration + +.Blueprint XML +[source,xml] +---- +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0";> + <bean id="myDataSource" class="org.apache.commons.dbcp2.BasicDataSource"> + <property name="url" value="jdbc:postgresql://localhost/orders"/> + <property name="username" value="dbuser"/> + </bean> + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + <route> + <from uri="timer:tick?period=5000"/> + <to uri="sql:SELECT * FROM orders?dataSource=#myDataSource"/> + </route> + </camelContext> +</blueprint> +---- + +.application.properties (Camel Main) +[source,properties] +---- +forage.myDataSource.jdbc.db.kind=postgresql +forage.myDataSource.jdbc.url=jdbc:postgresql://{{db.host}}:{{db.port}}/{{db.name}} +forage.myDataSource.jdbc.username={{db.username}} +forage.myDataSource.jdbc.password={{db.password}} +---- + +.order-poll.camel.yaml +[source,yaml] +---- +- route: + id: order-poll + from: + uri: "timer:tick?period=5000" + steps: + - to: "sql:SELECT * FROM orders?dataSource=#myDataSource" +---- + +The data source becomes a Forage-backed named bean with external connection values. Camel Main uses the +double-brace property placeholder syntax inside `application.properties`; Spring Boot and Quarkus use the +dollar-brace syntax. Camel Kit verifies Forage availability and the keys in its cached catalog first; without +Forage it continues down the configuration ladder to catalog-verified component properties and uses `camel.beans.*` +only as a documented last resort. + +=== Deprecated component swap + +.Camel 2.x or 3.x +[source,xml] +---- +<route> + <from uri="jetty:http://0.0.0.0:8080/api"/> + <to uri="activemq:queue:orders"/> +</route> +---- + +.Camel 4.x +[source,yaml] +---- +- route: + id: api-to-queue + from: + uri: "platform-http:/api" + steps: + - to: "activemq:queue:orders" +---- + +The `jetty` consumer becomes `platform-http`, with the listener port in the runtime's server property. The +`activemq` producer is in none of the rename tables, so it is kept and verified in the catalog for the selected +Camel version and runtime. + +=== Karaf features to runtime dependencies + +.Karaf features +[source,xml] +---- +<features xmlns="http://karaf.apache.org/xmlns/features/v1.4.0";> + <feature name="my-camel-routes" version="1.0"> + <feature>camel-core</feature> + <feature>camel-http4</feature> + <feature>camel-jackson</feature> + <bundle>mvn:com.example/my-routes/1.0</bundle> + </feature> +</features> +---- + +.Catalog-resolved dependencies +---- +Spring Boot: org.apache.camel.springboot:camel-<component>-starter +Quarkus: org.apache.camel.quarkus:camel-quarkus-<component> +Camel Main: camel.jbang.dependencies in the module-root application.properties +---- + +The exact artifacts and versions are verified against the selected runtime catalog before `/camel-execute` writes +them. + +[[next]] +== After the migration + +. Review the generated YAML routes and configuration. +. Update retained Java source from `javax.*` to `jakarta.*`: Camel 4 requires Jakarta EE 10. +. Run the routes locally with `camel run` or the target runtime's development mode. +. Check the xref:manual::camel-4-migration-guide.adoc[Camel 4 migration guide] for breaking changes outside the + migrated routes. diff --git a/docs/modules/ROOT/pages/migration-mulesoft.adoc b/docs/modules/ROOT/pages/migration-mulesoft.adoc index c91608de..7d41e0f2 100644 --- a/docs/modules/ROOT/pages/migration-mulesoft.adoc +++ b/docs/modules/ROOT/pages/migration-mulesoft.adoc @@ -1,3 +1,278 @@ = MuleSoft migration -This page is written in a following documentation pull request. +Camel Kit migrates MuleSoft Mule 3.x and 4.x applications to Camel 4 with YAML DSL routes. It understands Mule XML +flows and sub-flows, DataWeave 1.0 and 2.0 scripts, connectors, error handlers, choice routers, scatter-gather and +flow references. The shared steps, the migration package, the approval scope and the evidence rules are described +in xref:migration.adoc[]; this page covers what is specific to Mule. + +[[parsed]] +== What is parsed + +[cols="1,2"] +|=== +| Artifact | Location + +| Flow and sub-flow XML, global configuration | Mule XML files in the selected source boundary, typically + `src/main/mule/` +| DataWeave scripts | `.dwl` files and `<ee:transform>` or `<dw:transform-message>` elements +| Connector configurations | XML configuration elements +| Dependencies | `pom.xml` (`org.mule` and `com.mulesoft` groups identify the platform and version) +|=== + +Mule XML files are detected by the `mulesoft.org/schema/mule` namespace. When the project graph is built (see +xref:graph.adoc[]), the Mule and DataWeave parsers record every flow, sub-flow, connector, endpoint, transform and +error handler as graph nodes, so the migration gets the flow topology, the connectors used per flow, the sub-flow +call chains and the DataWeave complexity without walking the XML by hand. DataWeave scripts are analyzed for version +declarations, input and output content types, function definitions and field access patterns to identify +transformations that need manual attention. + +[[evidence]] +== Evidence and retirement + +`migration-analysis.md` records each Mule behavioral assumption and evidence gap with a stable ID, the affected flow +or interface, the source evidence, a `Confirmed`, `Inferred` or `Unknown` status, the impact if the assumption is +false, and the validation still required. API compatibility is not assumed just because a listener path or a +connector has a plausible Camel mapping. + +The source-retirement audit corroborates entry roots from the parsed message sources and follows constant +`flow-ref` targets to flows and sub-flows. Dynamic flow names, custom modules, parse failures, missing domain or +shared configuration, and callers outside the selected boundary stay *Unknown*. An `Incremental candidate` strategy +requires current evidence, or explicit operator confirmation, of an existing external control such as an +operator-controlled gateway, a deterministic broker partition, a mutually exclusive source directory or a +pre-consumption routing predicate; a listener declaration or an in-flow predicate after consumption is not a traffic +seam. + +[[components]] +== Component mapping + +The agent maps every Mule component to a Camel equivalent from the mapping guide shipped with the skill and +verifies each target and its options in the catalog for the selected Camel version and runtime. + +[cols="1,1,2"] +|=== +| Mule component | Camel component | Notes + +| HTTP Listener | `platform-http` (`camel-platform-http`) | The listener port moves to the runtime's server property + (`camel.server.port` with `camel.server.enabled=true` on Camel Main, `server.port` on Spring Boot, + `quarkus.http.port` on Quarkus); `platform-http` has no host or port option +| HTTP Request | `http` / `https` (`camel-http`) | Outbound calls +| Database select, insert, update, delete | `sql` (`camel-sql`) | `jdbc` for batch operations +| File, FTP, SFTP | `file`, `ftp`, `sftp` | Direct equivalents +| JMS, ActiveMQ, AMQP | `jms`, `activemq`, `amqp` | Queues and topics +| VM queue | `seda` | In-memory, not persistent across restarts +| Scheduler | `timer` or `quartz` | `quartz` for cron expressions +| Kafka | `kafka` | Direct equivalent +| Email (Mule 4 Email connector, Mule 3 transports) | `smtp`, `smtps`, `imap`, `imaps`, `pop3`, `pop3s` (all + from `camel-mail`) | The scheme follows the Mule connection type; `mail` is the artifact name, not a scheme +| Salesforce connector | `salesforce` | +| SOAP web service | `cxf` | +| REST consumer (RAML) | `rest` DSL with `openapi-java` | Import the OpenAPI specification +| Choice router, `when`, `otherwise` | `choice` EIP | +| Scatter-Gather | `multicast` EIP | Parallel dispatch with an aggregation strategy +| For Each, Splitter | `split` EIP | +| Until Successful | error handler with `redeliveryPolicy` | +| Async | `threads` EIP | +| Sub Flow, Flow Reference | `direct:` route | +| Set Payload, Set Variable, Set Property | `setBody`, `setHeader`, `setProperty` | Mule variables become + exchange headers +| Enrich, Poll Enrich | `enrich`, `pollEnrich` | +| Aggregator, Filter, Idempotent Filter, Wire Tap | `aggregate`, `filter`, `idempotentConsumer`, `wireTap` | +| Object to JSON / XML | `marshal` with `jackson` or `jaxb` | +| DataWeave Transform | DataMapper: inline Groovy or XSLT (`xslt-saxon`) | See <<dataweave>> +| Error handler, dead letter queue, retry | `doTry`/`doCatch`, Dead Letter Channel, `redeliveryPolicy` | +|=== + +Infrastructure beans such as data sources and connection factories are configured through the Forage configuration +ladder (see xref:forage.adoc[]) before `camel.beans.*` is considered. + +Proprietary connectors have no direct equivalent. The agent stops and asks you to choose a replacement, one +connector at a time, and verifies the choice in the catalog: + +[cols="1,2"] +|=== +| Mule connector | Suggested alternatives + +| Anypoint MQ | Amazon SQS, Azure Service Bus, RabbitMQ (`spring-rabbitmq`), ActiveMQ +| Object Store | Infinispan, Redis, Caffeine cache, JPA +| SAP connector | `camel-sap` if SAP JCo is licensed, otherwise SAP REST or SOAP APIs +| Workday, NetSuite, Zuora, Marketo, Veeva, Anaplan, Siebel | The vendor's REST or SOAP API through `http` or `cxf` +| ServiceNow | `servicenow`, after checking the API coverage +| Microsoft Dynamics 365 | `http` with the REST API, or `olingo4` +|=== + +[[dataweave]] +== DataWeave + +DataWeave scripts are not translated line by line. The agent first extracts the semantic field mapping, presents it +for confirmation, and records it in the design specification. DataMapper then selects the engine from the mapping, +not from the script: inline Groovy when both schemas are absent or the mapping has fewer than 20 leaf fields, XSLT +only when the mapping has at least 20 leaf fields and at least one schema. DataWeave constructs without a simple +equivalent are recorded as custom mapping or processor actions. Mule 3 uses DataWeave 1.0 (`%dw 1.0`, `flowVars`, +`message.inboundProperties`); Mule 4 uses DataWeave 2.0 (`%dw 2.0`, `vars`, `attributes`), and the guide covers +both syntaxes. + +[[examples]] +== Examples + +=== HTTP listener to database + +.Mule XML +[source,xml] +---- +<flow name="get-customer"> + <http:listener path="/customer/{id}"/> + <db:select config-ref="dbConfig"> + <db:sql>SELECT * FROM customers WHERE id = :id</db:sql> + <db:input-parameters> + #[{'id': attributes.uriParams.id}] + </db:input-parameters> + </db:select> +</flow> +---- + +.Camel YAML +[source,yaml] +---- +- route: + id: get-customer + from: + uri: "platform-http:/customer/{id}" + parameters: + httpMethodRestrict: GET + steps: + - to: "sql:SELECT * FROM customers WHERE id = :#${header.id}" +---- + +=== Scatter-gather + +.Mule XML +[source,xml] +---- +<scatter-gather> + <route> + <http:request url="http://inventory-service/check"/> + </route> + <route> + <http:request url="http://pricing-service/price"/> + </route> +</scatter-gather> +---- + +.Camel YAML +[source,yaml] +---- +- multicast: + parallelProcessing: true + aggregationStrategy: "#class:org.apache.camel.processor.aggregate.GroupedBodyAggregationStrategy" + steps: + - to: http://inventory-service/check + - to: http://pricing-service/price +---- + +=== Sub-flow and flow reference + +.Mule XML +[source,xml] +---- +<flow name="main-flow"> + <http:listener path="/api"/> + <flow-ref name="validate-order"/> +</flow> +<sub-flow name="validate-order"> + <validation:is-not-null value="#[payload.orderId]"/> +</sub-flow> +---- + +.Camel YAML +[source,yaml] +---- +- route: + id: main-flow + from: + uri: "platform-http:/api" + parameters: + httpMethodRestrict: POST + steps: + - to: "direct:validate-order" +- route: + id: validate-order + from: + uri: "direct:validate-order" + steps: + - validate: + simple: "${body.orderId} != null" +---- + +=== Choice router + +.Mule XML +[source,xml] +---- +<choice> + <when expression="#[payload.amount > 1000]"> + <flow-ref name="high-value-processing"/> + </when> + <otherwise> + <flow-ref name="standard-processing"/> + </otherwise> +</choice> +---- + +.Camel YAML +[source,yaml] +---- +- choice: + when: + - simple: ${body.amount} > 1000 + steps: + - to: direct:high-value-processing + otherwise: + steps: + - to: direct:standard-processing +---- + +=== DataWeave to XSLT + +This mapping has at least 20 leaf fields and both schemas, so DataMapper selected XSLT; the excerpt shows a few +fields. + +.DataWeave +[source,dataweave] +---- +%dw 2.0 +output application/xml +--- +{ + Order: { + ID: payload.orderId, + Customer: payload.customer.name, + Items: payload.items map { + Item: { + SKU: $.sku, + Qty: $.quantity + } + } + } +} +---- + +.XSLT +[source,xml] +---- +<xsl:stylesheet version="2.0"> + <xsl:template match="/"> + <Order> + <ID><xsl:value-of select="/order/orderId"/></ID> + <Customer><xsl:value-of select="/order/customer/name"/></Customer> + <Items> + <xsl:for-each select="/order/items/item"> + <Item> + <SKU><xsl:value-of select="sku"/></SKU> + <Qty><xsl:value-of select="quantity"/></Qty> + </Item> + </xsl:for-each> + </Items> + </Order> + </xsl:template> +</xsl:stylesheet> +---- diff --git a/docs/modules/ROOT/pages/migration.adoc b/docs/modules/ROOT/pages/migration.adoc index 97b0ef10..ad476465 100644 --- a/docs/modules/ROOT/pages/migration.adoc +++ b/docs/modules/ROOT/pages/migration.adoc @@ -1,3 +1,229 @@ = Migration workflow -This page is written in a following documentation pull request. +The migration workflow converts an existing integration to Camel 4 with YAML DSL routes. Instead of rewriting flows +by hand, the agent performs bounded discovery across the existing artifacts, uses the project graph as corroborating +evidence when one is available, and assembles one evidence-qualified migration package with a section per flow. +After you approve that package once, Camel Kit creates one implementation plan, executes it in dependency waves, +runs one project-wide runtime verification pass and finishes with report-only static validation. Failures, skipped +checks and unavailable tools are recorded rather than hidden. + +[cols="1,1,3"] +|=== +| Platform | Versions | Detection + +| MuleSoft Mule | 3.x, 4.x | XML namespace `mulesoft.org`; `pom.xml` groupId `org.mule` or `com.mulesoft` +| Microsoft BizTalk Server | 2004 to 2020 | XML namespace `schemas.microsoft.com/BizTalk`; `.odx`, `.btm`, `.btp` files +| Apache Camel | 2.x, 3.x | `pom.xml` with older `org.apache.camel` dependencies +| JBoss Fuse | 6.x, 7.x | `pom.xml` with the `org.jboss.redhat-fuse` BOM or `redhat-`/`fuse-` version qualifiers +|=== + +The platform pages describe the artifact formats, the mappings and the known limitations: +xref:migration-mulesoft.adoc[], xref:migration-biztalk.adoc[] and xref:migration-camel-upgrade.adoc[] (which also +covers Fuse). + +[[init]] +== Initialize the project for migration + +Run `init` inside the existing project with `--here`; the existing source and build files are not modified. + +[source,bash] +---- +cd my-existing-project +camel-kit init --here --ai claude --source-platform mulesoft +---- + +`--source-platform` accepts `mulesoft`, `biztalk`, `camel` (which also covers Fuse) or `auto`, the default, which +detects the platform from the sources. `init` adds the agent assets, the MCP configuration, the empty scaffolds +(`docs/flows/`, `test/data/`, `schemas/`), `.camel-kit/` and the Maven wrapper files, as described in +xref:getting-started.adoc#init[Create a project]. + +[[run]] +== Run the migration + +---- +/camel-migrate +---- + +`/camel-start` also routes to `/camel-migrate` when it finds a supported source. The orchestrator then: + +. scans the project artifacts (XML, build files, properties, documentation, Docker and Kubernetes files, source and + tests) within the selected source boundary, and detects the vendor and version; +. writes source-backed requirements in `business-requirements.md`; +. writes `migration-analysis.md` with the scope and evidence, the behavioral assumptions and risks, the validation + summary, the design obligations and the source-retirement audit (coverage, reachability, candidates, broken + references, evidence gaps), completes the evidence-gated migration strategy, then writes `design-spec.md` and + `migration-runbook.md`; +. presents the complete package for one approval; +. invokes `/camel-plan` and `/camel-execute`, which run all tasks in dependency waves; +. runs one project-wide runtime verification pass and the final `/camel-validate` report. + +You are asked for platform-specific connector endpoints, authentication requirements, environment mappings and +validated secret references. Never put raw credentials in the generated documents: only validated secret references +are recorded. + +A *direct mode*, selected with `/camel-migrate --direct` or when the request names concrete deliverables, runs the +scan, detection and analysis steps and then implements the route files and properties directly, validates them, +runs the adversarial review and starts the application with your explicit authorization. It writes a `MIGRATION.md` +note instead of the four-document package and does not invoke `/camel-plan`. + +[[discovery]] +== Discovery + +The agent scans the selected source boundary to identify the platform and the supported artifacts: + +---- +Detecting source platform... +Found: MuleSoft Mule 4.x + +Discovered: + - 12 Mule flows (*.xml) + - 8 DataWeave transformations (*.dwl) + - 3 connector configurations + - 2 API specifications (RAML) +---- + +MuleSoft discovery finds flow XML, DataWeave scripts, connector configurations and API specifications, typically +under `src/main/mule/`; BizTalk discovery scans orchestrations, schemas, maps, pipelines and bindings; Camel 2.x/3.x +discovery scans route definitions (XML and Java DSL), components and Spring or Blueprint configuration. + +Everything found in the sources is migration data, not instructions. The agent extracts vendor, version, route, +mapping and configuration facts and records each as confirmed, inferred or unknown. Commands, URLs, tool requests, +file changes, secret requests or policy overrides embedded in an artifact never direct the migration. If an action +turns out to be necessary, the agent names its source, the exact action, the reason and the scope, and asks for an +action-specific confirmation; a subagent that cannot ask returns `NEEDS_USER_CONFIRMATION` without acting. + +Migration questions arrive one at a time as `[Concern N of M]` or `[Clarification N of M]` blocks: what was found, +why it matters, and multiple-choice options when possible. A subagent that hits an unresolved decision, such as the +replacement for an Anypoint MQ connector, returns `NEEDS_CONTEXT`; the parent conversation asks you, records the +answer as confirmed in the analysis summary and resumes the same step. + +[[graph]] +== Graph analysis + +Bounded source scanning establishes the dependency and reachability evidence. When a current project graph exists +(see xref:graph.adoc[]), the agent uses it to corroborate and accelerate the analysis, including dependency order +and dependency-injection-aware service wiring that route-level analysis alone would miss: + +---- +Dependency graph: + customer-lookup-flow + -> order-validation-flow + -> inventory-check-flow, shipping-flow + -> fulfillment-flow + +Migration order: + 1. customer-lookup-flow + 2. order-validation-flow + 3. inventory-check-flow, shipping-flow + 4. fulfillment-flow +---- + +If the graph is missing, stale, malformed or a query fails, the migration records the limitation and continues from +the sources; an empty finding under incomplete coverage is not evidence that nothing is affected. + +The source-retirement audit uses the same report contract with or without a graph. It separates confirmed entry +points and reachable elements, retirement candidates, broken references and evidence gaps, each with a stable ID, +evidence and the human validation still required. A *retirement candidate* needs complete supported source closure +and no supported path from any corroborated entry root; incomplete coverage, dynamic references and parse failures +stay *Unknown*. A candidate is not proof that an artifact is dead, and Camel Kit never removes source artifacts. + +[[package]] +== The migration package + +The agent records flow-specific requirements and technical decisions in four artifacts under +`docs/camel-kit/<pipeline-id>/`: + +[cols="1,3"] +|=== +| Artifact | Content + +| `business-requirements.md` +| Business logic supported by the inspected source evidence, per flow, plus the `Migration Strategy` decision + +| `migration-analysis.md` +| Behavioral assumptions, evidence gaps and source-retirement findings with stable IDs (`MIG-###`, `SRC-###`) and + a `Confirmed`, `Inferred` or `Unknown` status for each + +| `design-spec.md` +| The technical specification of the complete migration: per-flow components, EIPs and test cases, with unresolved + IDs carried into scope constraints, validation obligations or unresolved decisions + +| `migration-runbook.md` +| The operator-owned handoff: scope, prerequisites, configuration and data readiness, deployment sequence, cutover + criteria, operational validation, rollback, reconciliation, escalation, soak and the source-retirement decision +|=== + +The `Migration Strategy` classifies each independently switchable ingress scope as `Incremental candidate`, +`Single cutover required` or `Undetermined - evidence needed`. An incremental candidate requires current evidence, +or explicit operator confirmation, of an existing external traffic control and its operator, a deterministic routing +unit, exclusive old/new ownership, aligned state and correlation boundaries, known delivery and ordering effects, +an idempotency control, comparable telemetry, and a rollback signal with a reversible control. Static source, +configuration or graph evidence can show that a mechanism is declared, but is at most *Inferred* evidence that it is +operative today. Neither classification proves deployment, cutover or rollback readiness. + +The runbook is generated from the validated final design. It never invents commands, endpoints, environment values, +thresholds, durations, contacts, owners or decisions: every missing operational fact is written as +`Unknown — operator decision required: <missing fact>`, listed under unresolved operator decisions, and blocks the +dependent deployment, cutover, rollback, reconciliation, soak or retirement action. + +Artifact provenance runs `business-requirements.md` → `migration-analysis.md` → `design-spec.md`, then branches: +`migration-runbook.md` and `implementation-plan.md` are independent children of the design, and the plan never +consumes the runbook. An upstream amendment marks the dependent artifacts stale; a stale runbook must be regenerated +by `/camel-migrate` before operational use. + +The agent presents the complete package and waits for one explicit approval. That approval authorizes the plan, +execution, verification and validation sequence. It does not authorize infrastructure provisioning, deployment, +production traffic switching, rollback, reconciliation or source retirement; each of those remains a separate, +named operator decision. + +[[execute]] +== Plan, execute, verify and validate + +After the approval, `/camel-plan` creates one implementation plan from `design-spec.md` and `/camel-execute` groups +its tasks into dependency waves. Each wave generates the Camel YAML routes and the Citrus integration tests; +independent tasks run concurrently where the agent supports it. Spring Boot and Quarkus targets use the Maven +source layout: + +---- + -> Generated: src/main/resources/camel/customer-lookup.camel.yaml + -> Generated: src/test/resources/customer-lookup.camel.it.yaml +---- + +Camel Main generates the routes and `application.properties` at the module root; tests remain under +`src/test/resources`. + +After all tasks finish, `camel-verify` runs once for the complete migrated application: build or startup smoke, +the applicable Citrus suite, and a report with the runtime, the Maven selection, phase outcomes, applied fixes and +skipped checks, embedded in `execution-report.md`. Tests that declare Testcontainers need Docker. The pipeline then +invokes `/camel-validate` once for the final static report. There is no flow-by-flow approval and no automated +deployment: operators keep control of the runbook's deployment and traffic actions. + +== Troubleshooting + +.A transformation is flagged as complex +[%collapsible] +==== +DataWeave scripts and BizTalk maps can use platform functions with no direct equivalent in the supported mapping +paths. Check the selected engine (inline Groovy when both schemas are absent or the mapping has fewer than 20 leaf +fields, XSLT only with at least 20 leaf fields and at least one schema), compare input and output examples from +the original, record unsupported constructs as custom mapping or processor actions, and add behavioral tests. +==== + +.A connector has no Camel equivalent +[%collapsible] +==== +The agent stops and asks before proceeding, suggesting alternatives (for example Amazon SQS, Azure Service Bus, +RabbitMQ or ActiveMQ for Anypoint MQ; `camel-salesforce` for the Salesforce connector). If no component exists, +implement a custom processor or use a catalog-verified HTTP component against a documented API, then update the +design specification and regenerate its stale children. See xref:components::index.adoc[the component list]. +==== + +.Verification fails +[%collapsible] +==== +A migrated route may carry a wrong endpoint, authentication, secret reference, transformation or dependency. Read +the failure details, compare the route with the original flow, verify the endpoint and the validated secret +reference, and run the generated Citrus test in isolation with `camel test run <path>.camel.it.yaml`. Use +`/camel-debug` in the agent for a structured diagnosis. If the cause is environmental, for example a missing +database, record it in the verification section of `execution-report.md` before deciding how to proceed. +====
