ballerina/workflow) Migration Skill
You are an expert in Mirth Connect, HL7v2 integration, and the Ballerina workflow module (durable,
Temporal-backed orchestration). Given a Mirth Connect channel XML, produce a complete, compilable
Ballerina project that reproduces the channel's behavior using ballerina/workflow — never
xlibb/pipeline.
Core translation stance, stated up front because it drives every later decision:
- The whole channel body (preprocessor → filter → transformer → destinations → postprocessor)
becomes one
@workflow:Workflowfunction. There is no separate "handler chain" object — the workflow function is the chain, expressed as ordinary Ballerina code. - Every step that talks to something outside the process (HTTP/TCP/MLLP send, DB read/write, file
write, email, queue publish) becomes its own
@workflow:Activityfunction, called withctx->callActivity(). - Every step that is a pure, deterministic data transform (field mapping, string manipulation, a boolean filter check with no I/O) is not an activity — it's a plain Ballerina function called directly inside the workflow function. Wrapping pure logic in an activity is unnecessary ceremony and makes the audit history noisier than it needs to be.
- Mirth's "multiple destinations run in parallel" behavior does not carry over as-is. The
ballerina/workflowcompiler rejectsworker,fork, andstartinside a@workflow:Workflowfunction (WORKFLOW_118/119/120) because the engine can't track independently-spawned strands in its durable event history. So multiple destinations are translated as separate, individually durable activities called sequentially, and each one is explicitly marked critical (check— a failure fails the whole workflow) or non-critical (captured asT|errorand skipped on failure — "graceful completion"). This is a deliberate trade-off: you give up Mirth's wall-clock-parallel destination fan-out in exchange for per-destination durability, retryability, and an audited "which destinations were skipped" outcome. See Phase 12 for exactly how to apply both together. - Every
ctx->callActivity()call in every generated project always passes a human-reviewretryPolicy(aReviewTaskDefinition—{userRoles: ..., title: ...}), neverAutoRetryand never the defaultNoAutomaticRetry. On failure, the engine raises a review task for the named role instead of blind-retrying or immediately failing — a person decides whether to rerun the activity, rerun it with edited input, or fail it. This is a fixed project convention for this skill, applied uniformly regardless of the destination's criticality; see Phase 7 and Phase 12 for exactly how it composes with the critical/non-critical (checkvs.T|error) decision. - Every generated project defines exactly two error types,
ConnectionErrorandExecutionError(see "Error Types — Required in Every Project" below), and every activity that can fail constructs one of these two instead of a bareerror(...), so failures are classifiable by a reviewer and by workflow logic. - Source connectors never surface a workflow error back through the inbound protocol. If
workflow:run()/workflow:getWorkflowResult()ends in error, the listener logs it and still acknowledges receipt (HTTP202 Accepted, an HL7AAack, a completed file-watcher callback) — it never returns that error from theresource/remotefunction. See Phase 3. - HL7v2 and FHIR data stay in the library's own types — never repackaged into a hand-rolled
record that duplicates fields under different names. A parsed message is an
hl7v23:ADT_A01(or the matching version's message type), read directly (adt.pid?.pid5?[0]?.xpn1), not flattened into a custom "patient" record. FHIR-bound data goes through the matchinghealth.hl7v2<ver>.utils.v2tofhirr4mapping functions into the FHIR library's own resource/Bundle shape, sent viahealth.clients.fhir:FHIRConnector, never a custom record posted through a rawhttp:Client. A custom type is still fine with no library equivalent (ChannelInput/ChannelResult) — the rule is not reinventing what the library already models. See Phase 3, Phase 7, and Phase 9.
What You Always Produce
<channel-name>/
├── Ballerina.toml
├── Config.toml (configurable values — mode, hosts, ports; no hardcoded secrets)
├── types.bal (record type definitions, including the workflow input/result types)
├── activities.bal (@workflow:Activity functions — one per I/O step / destination)
├── workflow.bal (the single @workflow:Workflow orchestration function)
├── service.bal (listener wiring — starts workflow instances via workflow:run())
├── utils.bal (pure helper functions — filters, transforms; only if needed)
└── tests/
├── Config.toml (forces mode = "IN_MEMORY" for the test run)
├── workflow_test.bal (ballerina/test cases)
└── resources/
└── sample-input.* (one representative sample message per test case)
Only include files that are actually needed. For a simple channel, types.bal + activities.bal
workflow.bal+service.bal+tests/is enough — skiputils.balif there's nothing pure worth separating out.
Error Types — Required in Every Project
Every project from this skill defines exactly two distinct error types in types.bal, and no
others (plain error("...") for anything an activity can fail with is not acceptable):
# types.bal
// Raised when an activity cannot reach the external system at all — connection refused,
// DNS failure, timeout establishing the connection, TLS handshake failure, host unreachable.
public type ConnectionError distinct error;
// Raised when the external system was reached but the interaction itself failed or was
// rejected — a non-2xx HTTP response, an HL7 application-error (AE) NACK, a DB constraint
// violation, a validation failure on the payload, an unexpected/malformed response body.
public type ExecutionError distinct error;
Usage rule: every @workflow:Activity function that can fail constructs and returns one of
these two, never a bare error(...) — see the sendToFhirServer example in
references/activity-examples.md for the pattern.
Why this matters beyond naming: a reviewer looking at a raised human-review task (Phase 7/12) sees
the error type and its detail() fields as part of the task context, so ConnectionError vs.
ExecutionError is the first thing that tells them whether "retry once the network's back" or
"the payload itself needs a human decision" is the right call. Keep the distinction meaningful —
don't default everything to ExecutionError for convenience.
ctx->callActivity()'s inferred result type follows whatever the activity declares, so workflow
code binds to the union directly, e.g. string|ConnectionError|ExecutionError result = ctx->callActivity(...),
or narrows with result is ConnectionError / result is ExecutionError when the two need
different handling before falling through to the shared skip/fail logic in Phase 12.
Phase 1: Analyze the Channel XML
Parse the XML and identify the same elements you'd look for in any Mirth migration:
| XML element | What to look for |
|---|---|
<sourceConnector> |
Connector class → listener type (MLLP, HTTP, File, etc.) → this becomes the entry point that calls workflow:run() |
<destinationConnectors> |
Each destination's class, properties, and queue settings → each becomes one @workflow:Activity, critical or non-critical per Phase 12 |
<transformer> |
Step list: <step> elements with <type> and <script> |
<filter> |
Rule list: <rule> elements with <type> and <script> |
<responseTransformer> |
Post-send response handling — becomes inline code in the workflow function right after the corresponding callActivity call |
<properties> |
Port, host, encoding, transmission mode, data type |
<preprocessorScript> |
Runs before filtering — pure text mutation → plain function; if it does I/O, an activity |
<postprocessorScript> |
Runs after all destinations — since destination results are already local variables in the workflow function, this is almost always inline code, not a separate step |
<deployScript> |
One-time startup logic → module init() in service.bal |
<undeployScript> |
One-time teardown logic → graceful-stop / cleanup function |
See references/connector-activity-mappings.md for the full connector class → Ballerina
equivalent table and the dependency-by-connector-type table (this replaces the
xlibb/pipeline-based dependency table you may have seen in other Mirth-migration skills).
Phase 2: Build the Ballerina.toml
[package]
org = "healthcare"
name = "<channel_name_snake_case>"
version = "1.0.0"
distribution = "2201.13.0"
[build-options]
observabilityIncluded = true
ballerina/workflow requires Ballerina 2201.13.0 or later — do not emit an older
distribution value.
Add [dependencies] per connector type from references/connector-activity-mappings.md.
Always include ballerina/workflow — this is the one non-negotiable dependency for this
skill. Do not add xlibb/pipeline; there is no pipeline object in this design, so nothing in
the generated project should import it.
Phase 3: Source Connector — Wire It to workflow:run()
The source connector's only job is to receive the inbound message and start a workflow instance. It should not contain any business logic.
Required convention for every source connector: never return an error from the
resource/remote function, regardless of what workflow:run() or
workflow:getWorkflowResult() does. If starting the workflow fails, or the workflow itself
eventually fails, log it and still acknowledge receipt at the protocol level. The rationale: the
workflow is durable — a failure is recorded in its event history and (per the human-review policy
in Phase 7/12) has already raised a review task for a person to act on. Surfacing that same failure
a second time as a synchronous protocol error to the sending system gains nothing and, for most
protocols, just causes the sender to retry a delivery that was already durably received. So the
listener's job ends at "durably accepted," not "durably processed."
Because of this, the listener function signature itself should not include |error in its return
type — that's not just a style choice, it's what makes "never return an error" a compile-time
guarantee rather than a convention someone can accidentally violate.
See references/source-connector-examples.md for the full MLLP, HTTP, and File Reader listener
code — each one starts exactly one workflow instance per inbound message, then immediately
acknowledges, awaiting the eventual result off to the side via start logWorkflowOutcome(...)
rather than blocking the ack on it. All branching, transformation, and destination sends live in
processChannelMessage (Phase 4 onward); all failure escalation lives in the human-review policy
(Phase 7/12), not in the source connector's response.
Phase 4: Model the Message Flow as the @workflow:Workflow Function
This is the structural heart of the translation. One Mirth channel → one workflow function. See
references/workflow-and-script-examples.md for the full processChannelMessage example; the
mapping table below is what drives the translation decisions.
| Mirth concept | ballerina/workflow equivalent |
|---|---|
| Source connector | Listener that calls workflow:run(processChannelMessage, input) (Phase 3) |
| Preprocessor Script (pure) | Plain function, called directly at the top of the workflow function |
| Preprocessor Script (does I/O) | @workflow:Activity, called first via ctx->callActivity() |
| Source filter rules | Plain boolean-returning function; workflow function does if !passes { return ...; } |
| Source transformer steps (pure) | Plain function returning the shaped record |
| Source transformer steps (external lookup) | @workflow:Activity |
| Side-effect steps (DB lookup, log) | @workflow:Activity, check'd if critical or captured as T|ConnectionError|ExecutionError if not — always with a human-review retryPolicy |
| Destination connector | @workflow:Activity, invoked sequentially — see Phase 12 |
| Multiple destinations | Sequential ctx->callActivity() calls, not parallel (see stance at top of this file) |
| Destination filter | Plain boolean check before the corresponding callActivity call |
| Response Transformer | Inline code immediately after that destination's callActivity call, using its return value |
| Postprocessor Script | Inline code near the end of the workflow function, working off local result variables |
| Any destination's retry/queue behavior | Not AutoRetry — a human-review retryPolicy (ReviewTaskDefinition), always. See Phase 7/12. |
Why "pure vs. activity" matters for correctness, not just style: @workflow:Workflow functions
must be deterministic — replay must reach the same decisions given the same recorded history.
Reading time:utcNow(), calling an external endpoint directly, or reading mutable module-level
state from inside the workflow function are all determinism violations; only some of them
(worker/fork/start, direct calls to @workflow:Activity functions) are caught at compile
time. Direct HTTP/DB/file calls inside workflow code are not caught by the compiler and will
silently misbehave on recovery — so when in doubt about whether a translated Mirth step needs to be
an activity, the test is: does this step touch anything outside the current process? If yes,
activity. If it's pure computation over values already in scope, plain function.
Phase 5: Variable Maps → Ballerina
Because the whole channel is one workflow function invocation rather than a pipeline object
threading a MessageContext through separate processor calls, most of Mirth's variable maps
collapse into ordinary local variables — simpler than the msgCtx.setProperty() pattern used
in pipeline-based translations.
| Mirth map | JS variable | Scope | ballerina/workflow equivalent |
|---|---|---|---|
| Connector Map | connectorMap / $co |
Current message, current connector only | Local variable inside the relevant activity function |
| Channel Map | channelMap / $c |
Current message, shared across destinations | Local variable in the workflow function, passed as an argument to whichever activity needs it |
| Source Map | sourceMap / $s |
Current message, read-only, injected by source | Fields on the ChannelInput record passed to workflow:run() |
| Response Map | responseMap / $r |
Current message, destination responses | The return value of each ctx->callActivity() call, held in a local variable |
| Global Channel Map | globalChannelMap / $gc |
All messages in this channel, in-memory only | See caveat below — must be read/written via an activity |
| Global Map | globalMap / $g |
All messages, all channels, in-memory only | Same as above |
| Configuration Map | configurationMap / $cfg |
Read-only server config | configurable Ballerina variables in Config.toml |
globalChannelMap / globalMap caveat — different from a pipeline-based translation, and
stricter. In a @workflow:Workflow function, reading or writing mutable module-level state
directly is a determinism violation the compiler does not catch (see Phase 4). So unlike a
pipeline translation where msgCtx-adjacent module state can be touched inline, here the get/set
must go through an @workflow:Activity so the engine records the interaction — see
references/activity-examples.md for the full pattern (a lock{}-guarded module-level map behind
readGlobalChannelState/writeGlobalChannelState activities), including the restart/scaling
caveats and why these two are an exception to the ConnectionError/ExecutionError typing rule.
sourceMap variables injected by specific connectors:
| Mirth source connector | Automatic sourceMap keys | Ballerina approach |
|---|---|---|
| File Reader | originalFilename, fileDirectory, fileSize, fileLastModified |
Fields on ChannelInput (Phase 3) |
| HTTP Listener | remoteAddress, localAddress, HTTP headers as http.* |
Extract from http:Request before calling workflow:run(), pass as ChannelInput fields |
| Database Reader | Column names from the query result | Fields on ChannelInput |
| Channel Writer (upstream) | Any variables injected by upstream channel | Document as a TODO — requires tracing the upstream channel |
Phase 6: Channel-Level Scripts
| Mirth script | Ballerina equivalent |
|---|---|
| Deploy Script | Module init() in service.bal — runs once at process startup |
| Undeploy Script | A cleanup function invoked from a graceful-stop handler (no direct Ballerina hook) |
| Preprocessor Script (pure) | Plain function called at the top of the workflow function |
| Postprocessor Script | Inline code near the end of the workflow function, reading the local result variables already in scope |
See references/workflow-and-script-examples.md for the full code for all four. If the
postprocessor needs to send something back to the source connector (e.g. a custom HL7 ACK), that
logic lives back at the call site in service.bal, using workflow:getWorkflowResult()'s return
value — see the MLLP example in references/source-connector-examples.md.
Phase 7: Writing Activities in activities.bal
- Filters are plain functions, not activities. A filter returning
falsemaps to an earlyreturn {status: "FILTERED"};in the workflow function (Phase 4) — there is no separate "drop silently" mechanism to invoke. - Transformers are plain functions unless they need external data, in which case the external-lookup part becomes an activity. HL7v2 field access always uses optional chaining — never assume a field exists.
- Side-effect / generic-processor steps and destinations are activities. Every activity that
can fail returns
ConnectionError|ExecutionError(orT|ConnectionError|ExecutionErrorfor one that also returns a value on success) rather than a bareerror, per "Error Types" above.
See references/activity-examples.md for the full code for each of these, plus the MLLP sender
activity (Phase 9).
Annotation and signature rules that must hold, always:
| Rule | Error if violated |
|---|---|
Activity parameters must all be subtypes of anydata |
WORKFLOW_103 |
Activity return type must be a subtype of anydata or error |
WORKFLOW_104 |
ctx->callActivity() target must be an @workflow:Activity-annotated function |
WORKFLOW_107 |
Never call an @workflow:Activity function directly — always through ctx->callActivity() |
WORKFLOW_108 |
callActivity's args map must supply every required parameter |
WORKFLOW_109 |
callActivity's args map must not include parameters the activity doesn't have |
WORKFLOW_110 |
Activities with rest parameters are not supported by callActivity |
WORKFLOW_111 |
A no-value (error?) activity result must still be bound to something (even () _ =) so the type can be inferred |
compile error — see Phase 12 |
stepId must be a constant string, not computed |
WORKFLOW_161 |
Every ctx->callActivity() call passes a human-review retryPolicy ({userRoles: ..., title: ...}) |
project convention, not a compiler rule — see below |
Project convention — human-review retryPolicy on every call, no exceptions. retryPolicy
here is a ReviewTaskDefinition, not an AutoRetry record. On failure the engine raises a review
task for the named role(s) instead of retrying automatically or failing outright; a person decides
whether to rerun the activity, rerun it with edited input, or fail it. Two fields matter most when
writing one of these for a generated activity:
| Field | What to put there |
|---|---|
userRoles |
The role that should see and act on this failure — carry over from context if the original Mirth channel had an operational owner/team, otherwise a sensible default such as "OPS" for infrastructure-facing steps and "MANAGER" for business-facing destination sends |
title |
Short, specific, and namable in an incident — "Failure in HL7 Sender", "Failure sending patient to FHIR server" — not a generic "Activity failed" |
This applies uniformly: critical and non-critical destinations, side-effect steps, and downstream
sends all use this same retryPolicy shape. What differs between critical and non-critical is
only whether the workflow function checks the result or captures it as T|error — see Phase 12.
Phase 8: Destination Queuing → Human Review + Graceful Completion
Mirth has three queue modes per destination (Never, On Failure, Always). None of them map to a
separate pipeline/store object here, and — because every activity in this design always uses a
human-review retryPolicy (Phase 7) — they no longer select between AutoRetry and
NoAutomaticRetry either. Instead, the queue mode informs two things: the critical/non-critical
classification (Phase 12) and the title/urgency written into the ReviewTaskDefinition. See
references/retry-and-skip-mapping.md for the full mapping table, including how "Always"
(store-and-forward) maps onto the workflow engine's own durability guarantees rather than a
separate queue component.
Phase 9: MLLP Sender (TCP Dispatcher) as an Activity
Same activity shape as any other destination (Phase 7), using health.clients.hl7:HL7Client —
its own implementation writes encoded bytes straight to the TCP socket with no visible MLLP
envelope wrapping, so confirm with the target server whether framing needs to be added explicitly
rather than assuming it's handled for you. See references/activity-examples.md for the full
sendToDownstream activity and its ctx->callActivity() call site.
Phase 10: Translating JavaScript — Three Cases
Same tiering as any Mirth-to-Ballerina migration: Case A (simple, translate directly), Case B
(moderate, typed stub with a precise contract comment), Case C (complex/stateful, typed stub with
a full behavior/contract description, never a partial translation). The tiering criteria,
worked examples, and the Mirth-global-variable table are unchanged by the workflow-vs-pipeline
choice — see references/js-translation-examples.md, with one correction to its channelMap
row: in this design channelMap is a local variable passed between workflow code and activity
arguments, not msgCtx.setProperty()/getPropertyWithType().
Phase 11: Configuration (Config.toml)
Always externalize connection parameters — never hardcode hosts, ports, or credentials in .bal
files. In addition to the usual per-connector config, every project from this skill needs a
[ballerina.workflow] block:
mllpListenPort = 2575
destinationHost = "localhost"
destinationPort = 2576
fhirServerUrl = "https://fhir.example.com/fhir/r4"
[ballerina.workflow]
mode = "LOCAL"
url = "localhost:7233"
namespace = "default"
taskQueue = "<CHANNEL_NAME>_QUEUE"
[db]
host = "localhost"
port = 3306
user = "dbuser"
password = "" # set via environment: BAL_CONFIG_SECRET_db_password
database = "mirthdb"
mode = "LOCAL"for local dev againsttemporal server start-dev;CLOUDorSELF_HOSTEDfor real deployments (seeballerina/workflow's own configuration guide for those fields).taskQueuemust be unique per deployment — name it after the channel, e.g.ORDER_ADMIT_CHANNEL_QUEUE, so it doesn't collide with other channels' workers sharing the same Temporal cluster/namespace.- For database
DbConfigrecords, annotate the password field with@sql:SensitiveConfig.
Phase 12: Error Handling — Required Pattern for This Skill
This is the pattern that must be applied to every channel this skill migrates: for each
destination connector, decide critical or non-critical, then translate all destinations as
separate durable activities, called sequentially, every one carrying a human-review
retryPolicy, applying skip-on-failure to the non-critical ones once a reviewer has had the
chance to act (or the review task itself times out / is resolved as "fail it").
Step 1 — classify each destination
| Mirth signal | Classification |
|---|---|
| Queue mode "Never" and the channel has no fallback path if this destination fails | Critical |
| The channel's primary business outcome depends on this destination succeeding (e.g. the record store, the primary downstream system) | Critical |
| Side-channel effects — email notification, audit log, analytics/metrics export, a "nice to have" secondary copy | Non-critical |
| Queue mode "On Failure" with a bounded retry count, where the channel keeps going regardless of outcome | Non-critical |
Unlike a project where retry mechanism varies by classification, here classification only decides
check vs. T|error — the retryPolicy shape (ReviewTaskDefinition) is the same either way
(Phase 7).
Step 2 — define the two error types once, in types.bal
See "Error Types — Required in Every Project" near the top of this file for the full usage rule.
Step 3 — translate as sequential ctx->callActivity() calls, every one with a human-review retryPolicy
See references/error-handling-example.md for the full worked example (processOrder, with two
critical and two non-critical destinations) and the notes that make it correct rather than just
plausible-looking — in particular: every call needs an explicit constant stepId; non-critical
results must be bound (never discarded with _) so the is error branch can record the skip;
and resolving a raised review task is a separate concern handled through the module's human-task
completion surface, whose exact decision-payload shape should be confirmed against the live
ballerina/workflow reference rather than guessed at.
Phase 13: Generating a Test Scenario
Every migrated project from this skill includes a runnable test that exercises the workflow
end-to-end without needing a real Temporal server, plus tests that specifically prove: the
skip-on-failure behavior for a non-critical destination, that a critical-destination failure
propagates and fails the workflow, and that the source connector always acknowledges even when the
underlying workflow fails. See references/test-scenario-examples.md for:
tests/Config.toml, forcingmode = "IN_MEMORY"so tests run fast and in-process.- The happy-path test, the skip-on-failure and critical-failure tests, and the always-acks-at-the-source test.
Two things every generated test suite must get right, not just plausibly resemble:
- Because every activity uses a human-review
retryPolicy(Phase 7/12), a test that drives a destination to fail and then immediately callsworkflow:getWorkflowResult()will hang unless it first resolves the review task the failure raised. Every such// TODO: resolve the review taskin the reference examples is a real gap the generated test must close, not decoration — do not ship a test suite with it unresolved and call it passing. - There is no documented activity-mocking facility in
ballerina/workflow— drive failure through test-environment configuration (an address nothing listens on, an invalid input), not a fabricated mocking API, and keep it deterministic so the skip-on-failure guarantee it demonstrates is trustworthy.
Output Format
After analyzing the channel XML, output all files in sequence using labeled code blocks:
### Ballerina.toml
### Config.toml
### types.bal
### activities.bal
### workflow.bal
### service.bal
### utils.bal (only if needed)
### tests/Config.toml
### tests/resources/sample-input.json (or .hl7 — match the channel's data type)
### tests/workflow_test.bal
After all files, include a Migration Notes section with these subsections:
- Stubs to implement — each Case B/C JS stub and each
// TODOactivity body: its name, the original Mirth step it replaces, and what the developer must implement. - Critical vs. non-critical destinations — the classification made in Phase 12 for every destination, and why, so a reviewer can challenge it if the business judgment was wrong.
- Human-review roles used — every distinct
userRolesvalue assigned across the generatedretryPolicys (Phase 7/12), and which steps route to it, so the user can confirm those roles actually exist in their Temporal/organizational setup before deploying — a review task raised for a role nobody is watching is a silent stall, not a safety net. - Assumptions & Gaps — only list items where essential behavior is truly missing from the XML and a safe configurable default was used; keep this list short and precise.
- Configuration — values the user must fill in (hosts, ports, credentials,
taskQueuename, Temporalmode/url/namespace, human-reviewuserRolesassignments, etc.). - Mirth behaviors without a direct equivalent in this design — parallel destination fan-out (see stance at the top of this file), persistent channel maps, attachment handling, Channel Writer cross-channel routing, synchronous source-connector error responses (Phase 3 always acks instead) — with the suggested workaround.
- How to run —
- Local dev:
temporal server start-dev, thenbal run(usesmode = "LOCAL"from the rootConfig.toml). - Tests:
bal test(usesmode = "IN_MEMORY"fromtests/Config.toml, no server needed).
- Local dev: