Interface Components in Iguana: A Technical Breakdown
If you have worked with other integration engines, you might be used to large, all in one interfaces where every part of the workflow lives inside a single script or connection. Iguana takes a different approach. Instead of placing everything in one place, Iguana uses components. Each component performs a specific job, and together they form a complete data flow.
This design is not just for visual clarity. It has real technical benefits that affect performance, debugging, reuse, and long term scalability. Here is a more detailed look at how components work and why they matter.
What exactly is a component?
A component is a self contained unit inside an Iguana interface. Each one handles a single responsibility, such as:
Source component
Listens for incoming data through a protocol such as LLP, HTTP, RESTful API, file directory polling, SFTP, or database queries.
Filter or translator component
Processes data using Lua. This is where parsing, validation, transformation, normalization, or routing happens.
Destination component
Sends processed data to the next system, whether that is an EHR, an API endpoint, another Iguana instance, or a database.
If you picture an HL7 message arriving, being transformed, and then delivered to an EMR, each step is a separate component.
A simple example: an HL7 to JSON workflow
Imagine a clinic sending HL7 ADT messages to you. You want to convert those messages to JSON and push them to an internal API.
A typical Iguana workflow might look like this:
1. Source component
[LLP Listener]
-
Receives the HL7 message through a TCP port
-
No code required
-
Configuration fields: IP, port, acknowledgment mode, queue size
2. Filter component
[HL7 Mapper]
-
Parses the HL7
-
Maps fields into a JSON structure
-
Applies validation rules
Example snippet inside the translator:
local h = hl7.parse{v = RawHL7}
local out = {}
out.PatientID = h.PID[3][1]:S()
out.LastName = h.PID[5][1][1]:S()
out.FirstName = h.PID[5][1][2]:S()
out.DOB = h.PID[7]:S()
return json.serialize{data = out}
3. Destination component
[HTTP Client]
-
Sends the JSON to an API endpoint
-
Configurable headers, URL, credentials, and timeouts
Splitting this into three components gives you strong control over each stage.
Why separation of concerns matters technically
Component boundaries are not just for neatness. They improve reliability and maintainability in real world scenarios.
1. Failures are isolated
If an HL7 feed suddenly sends malformed data, the filter component shows the error without affecting the destination. This makes it easy to identify where the issue occurred.
2. Logs are cleaner
Each component produces its own logs. If a message fails in the mapping stage, you see the failure exactly where it happened. Troubleshooting becomes faster because you start at the right layer.
3. Changes are safer
If you update a mapping rule, you only update the translator component. Source and destination components remain untouched. This reduces risk and keeps deployments predictable.
Reuse in practice: building your own component library
Over time, developers often create a library of reusable components. For example:
-
A component that polls a file directory every 30 seconds
-
A component that parses a specific vendor's HL7 structure
-
A component that sends FHIR resources to a particular endpoint
-
A component that normalizes patient identifiers across clinic systems
-
A component that handles a standard set of validation checks
Because Iguana connects with Git, these components can be shared across environments and projects. If a team member builds a solid ADT mapping component today, someone else can import it into a different interface tomorrow.
This reduces development time and keeps integrations consistent.
More complex workflows are easier to build
Here is a more advanced use case showing how components scale.
Example: one source, multiple destinations
A clinic sends ADT messages. You need to:
-
Store every message in a database
-
Forward the message to the main EHR
-
Convert the message to JSON and send it to a reporting system
In Iguana, you attach three destination components to the same source:
-
Destination A: Database Writer
-
Destination B: LLP Client to the EHR
-
Destination C: Translator for JSON mapping, followed by HTTP Client
Visually and technically, it is simple. Each destination runs independently. Each has its own error handling, logs, and retry queue.
Trying to achieve the same in a single script would be cumbersome and harder to maintain.
Components make scaling easier as requirements change
Real integrations evolve. New clinics come online. New workflows appear. Systems get replaced. Components help with this because you only extend or modify the pieces that need to change.
Examples:
-
Add a new destination without touching the existing flow.
-
Swap a file based source for an API based source, while keeping your mapping logic identical.
-
Insert a validation component before routing data to downstream systems.
All of this becomes practical because components keep your workflow modular and adaptable.
Why components are worth caring about
In short:
-
They keep data flows clean and understandable
-
They make debugging faster
-
They support safe, incremental changes
-
They allow reuse across projects
-
They scale well as environments grow
-
They match how real world healthcare data moves through systems
Once you start building integrations in Iguana, components become one of the most important tools you use every day. They form the backbone of every workflow, from the simplest HL7 feed to the most complex multi system architecture.
