Routing Introduction
Routing in 1Gateway defines how messages move through a workflow from one plugin to another.
Routing is based on message types, which determine which plugins can receive and process a message, and how it flows through the system.
All routing is:
- Message-based – messages are passed between plugins
- Plugin-driven – routing decisions are defined within plugin configuration
Routing determines where a message goes next, based on the message type, message content, and workflow design.
How Routing Works
In 1Gateway, messages flow between plugins through defined routing mechanisms. Each plugin processes a message and decides what happens next.
Routing always happens in the context of a plugin and can be controlled by:
- Next Hop (synchronous routing)
- Queues (asynchronous routing)
- Filters (conditional routing)
Message Type and Routing
Message types ensure that messages are handled by the correct plugins and transformed correctly throughout the workflow.
- A plugin processes only messages that match its configured message type
- A Message Mapper transforms a message into a new type
- For a message to pass through a mapper, the message type must match the mappers
fromfield - Queues rely on message types to ensure messages are handled by the correct plugins
This allows workflows to be structured as type-based pipelines.
Routing Mechanisms
Next Hop (Synchronous Routing)
Next Hop defines the next plugin a message should go to immediately after processing.
- Configured in the source plugin
- No queue is used in between
- Processing is synchronous
Use case:
Simple, linear workflows where messages should be processed step-by-step without delay.
Queues (Asynchronous Routing)
Queues allow messages to be stored and processed asynchronously.
A plugin queue defines:
- Source endpoint
- Destination endpoint
- Message type
Messages are placed on a queue and processed later by another plugin.
Use case:
High-volume integrations, decoupled systems, or when retry and buffering are required.
Filters (Conditional Routing)
Filters control whether a message should continue through the workflow.
- Can evaluate any message content
- Commonly used to filter based on message fields
- Can discard messages (e.g., unchanged data)
Use case:
Reducing unnecessary processing or routing messages based on conditions.
For more information on how filters work, go to: Groovy Filters
Switch Plugin (Conditional Routing)
The Switch plugin enables routing to multiple possible paths based on rules.
- Evaluates conditions and routes messages to different plugins using Next Hop
Use case:
Branching logic (e.g., create vs update, priority-based routing).
For more information on how Switch plugins work, go to: Switch Plugin
Common Routing Patterns
1. Linear (Synchronous) Flow
Webhook → Mapper → Mapper → Sender
- Uses Next Hop
- Simple and fast processing
Use when:
The workflow is straightforward and does not require buffering or branching.
2. Conditional Routing
Webhook → Switch → Mapper A or Mapper B
- Uses Switch plugin
- Routes based on conditions
Use when:
Different processing logic is required based on message content.
3. Asynchronous Processing
Webhook → Queue → Mapper → Sender
- Uses queues
- Decouples processing
Use when:
Handling high volumes or integrating with systems that process data asynchronously. This is the most common use case to avoid message loss.
4. Filtering Pattern
Timer → Mapper → Filter → Switch → Sender
- Filters remove irrelevant messages from the current flow.
Use when:
Only changed or relevant data should be processed.
When to Use What
| Scenario | Recommended Approach |
|---|---|
| Simple step-by-step processing | Next Hop |
| Conditional branching | Switch plugin |
| High volume or decoupled systems | Queues |
| Avoid processing unchanged data | Filters |