Iguana to Integration Soup migration

 Migration brochures have a soothing habit of turning a working interface estate into three boxes and an arrow.

Export. Convert. Go live.

Anyone who has supported real HL7 channels knows there is usually rather more hiding inside the arrow. There are Lua modules shared by six channels, a VMD last edited by somebody who has left, environment variables with misleading names, certificates, special ACK rules and sample messages that explain more than the documentation.

The good news is that an Iguana migration does not have to begin from a blank page. Iguana's code-led structure gives us useful source material, and Integration Soup now has a practical process for turning that material into testable workflows.

What do you actually export from Iguana?

The short answer is: the channel exports are the start, not the whole package.

I would collect:

• Git channel exports or Translator project archives. These provide the channel structure and project files.
• All Lua code. Include local modules, shared modules, and any common libraries used across channels.
• VMD files. These often contain message definitions and mapping knowledge that is not obvious from the Lua alone.
• Channel and instance configuration. Source, filter and destination settings, environment variables, queue behavior, web settings and notification rules all matter.
• External dependencies. Record databases, APIs, file locations, certificates, custom executables, plugins and scheduled jobs.
• The channel topology. Document From Channel and To Channel relationships, fan-out, shared queues and any processing split across several channels.
• Representative test data. Include de-identified successful messages, known failures, unusual variants, ACKs and boundary cases. Do not put patient information into a migration repository.

If that sounds like more than a single export button, it is. The point is not merely to preserve the Lua. The point is to preserve the behavior.

How the Iguana pieces map into Integration Soup

An Iguana channel normally has a recognizable flow: receive something, filter or transform it, and deliver it somewhere. Integration Soup expresses the same intent as a workflow.

• The Iguana source becomes an Integration Soup receiver: LLP, HTTPS, file, database or the appropriate input.
• Filters and Translator logic become visual transformers, filters and code activities in the same processing order.
• The destination becomes a sender or workflow activity with its endpoint, payload, retries and response behavior.
• Lua functions and modules are translated into C# and Integration Soup APIs, keeping function boundaries and names recognizable where that helps maintenance.
• VMD mappings become message templates, mappings or code transformers, whichever leaves the intent clearest.
• Environment values become deployment configuration rather than values buried inside a workflow.
• Channel-to-channel routing becomes explicit workflow output and connected activity flow.

I like this approach because it does not pretend the two engines are identical. Iguana runtime calls have to change, and some designs should be simplified rather than copied line for line. The aim is to retain the business rules while producing a workflow that looks native in its new home.

The migration is proven offline

This is the important part.

A converted channel should not be accepted because the diagram looks right or because one cheerful ADT message reached the destination. It should be tested as a regression exercise against what the Iguana channel already does.

Start with the exported samples and de-identified log cases. Feed the same inputs through the reference behavior and the new Integration Soup workflow, then compare:

• the parsed source values and validation results;
• the generated outbound payloads and encodings;
• which routes and destinations were selected;
• ACK content, timing and negative-ACK behavior;
• database writes and queries;
• file names, API requests and other external effects;
• ignored-message and error paths;
• retry, alert, queue and recovery behavior;
• throughput and resource use at representative volumes.

External systems can be stubbed or redirected in the offline environment, so the workflow can be exercised without sending test patients into a production EHR or emailing a thousand imaginary lab results to somebody.

Sometimes the output can be compared byte for byte. Sometimes fields such as timestamps, message control IDs or generated file names are expected to differ. In those cases the comparison should normalize only the agreed dynamic values and remain strict about everything else.

That is what “100% accurate” should mean in a migration: every agreed behavior and test case passes. It should not mean that someone looked at two messages and felt optimistic.

Prove one difficult channel first

I would begin with a representative channel that contains real transformation logic and at least one dependency. This is much more valuable than converting ten relays to make the progress chart look impressive.

The pilot tells you how your organization uses Lua, shared modules, VMDs, environment settings and error handling. Once those patterns are understood, the rest of the estate becomes easier to estimate and convert consistently.

It also gives the support team a chance to use the Integration Soup dashboard, inspect messages, search logs, follow the workflow and decide whether the new system makes operational sense. A migration succeeds when the people on call can support it at 2 a.m., not when the project team completes a spreadsheet.

Cut over in controlled groups

After offline acceptance, I would move a small group of interfaces at a time:

1. Freeze or carefully track changes to the Iguana channel during final testing.
2. Apply production endpoints, credentials, and certificates through controlled environment configuration.
3. Run in parallel or shadow mode where the surrounding systems allow it.
4. Agree the cutover step, monitoring window and rollback trigger before touching production.
5. Switch the listener, route, port or upstream destination during the planned window.
6. Compare live inputs, outputs, ACKs, queues and alerts closely.
7. Keep the old path available for the agreed rollback period, without letting both systems create duplicate downstream effects.

For many channels, the final switch is genuinely simple. The work that makes it simple is the inventory, conversion, and offline proof completed beforehand.

Why I think this is a sensible direction

Integration Soup gives me the things I want from a serious interface engine: visible workflows, queues, logging, monitoring, alerts, scheduling, environment configuration, code when needed, and support for the mix of HL7, FHIR, files, databases, APIs, cloud services and DICOM that turns up in real integration work.

It is also simple enough that the migration does not finish with all the old Lua hidden inside a generic coding window. The workflow remains understandable and operationally useful in the browser, while the translated C# is there for the logic that deserves code.

Most importantly, the Iguana migration service is built around evidence. Export the channels and their dependencies, rebuild the intent, replay the test pack, compare the behavior, then cut over in controlled groups. Approved migrations can also qualify for price-matched licensing and included conversion assistance, subject to the published terms.

There is no magic migration button, and I would be suspicious of one. There is something better: a repeatable path that lets you prove the new interface before the old one stops carrying the messages.