Orchesty Modules: Centralizing Logic and Dynamic Settings

In a standard integration, an App serves as a bridge for its own Connectors. However, real-world business logic often requires settings that span the entire integration: data that doesn't "belong" to a single API call but governs how the whole system behaves.

In Orchesty, we call this concept a Module.

1. What is a Module? #

Technically, a Module is an Orchesty App. Architecturally, however, its purpose is different. While a standard App focuses on executing actions (Connectors), a Module focuses on providing context and configuration (Settings).

• Logic over Action: A Module might not have a single Connector. Instead, it provides a centralized UI for users to map values, toggle features, or define business rules.
• Global Accessibility: Data stored within a Module's "Application Install" object is accessible to any node in the topology, including the custom nodes you write to map values or filter records.
• Architectural Cleanliness: Using a dedicated Module for settings prevents your connectors from becoming cluttered with non-technical business configurations.

2. Dynamic UI: The Power of Synchronous Actions #

The most powerful aspect of a Module is its ability to communicate with external systems in real-time while a user is configuring the integration in the UI. We call these Synchronous Actions.

Instead of a static dropdown list that might become outdated, Orchesty allows the Worker to "live-fetch" data from a remote API the moment a user opens a configuration form.

The Mechanism: customFormReplace #

When you open an App's settings in the Orchesty Admin UI, the platform triggers a synchronous call to your Worker.

1. The Request: The UI asks, "What should I show in this form?"
2. The Action: The Worker executes a synchronous API call to the target system (e.g., your ERP or E-shop).
3. The Result: The Worker populates the form fields (like Select Boxes) with fresh data (Enumerations/Codelists) via the setChoices method.

3. Practical Use Case: Mapping Shipping Carriers #

Imagine you are integrating an E-commerce platform with an ERP system. Both systems have their own list of shipping carriers, but their IDs don't match.

• The Hardcoded Risk: If you hardcode the mapping in your code, the integration breaks the moment the warehouse adds a new carrier.
• The Module Solution: You create a Module that dynamically fetches the carrier list from both the E-shop and the ERP.
• User Empowerment: In the Orchesty UI, the user sees a simple mapping table. They can select "DHL" from the E-shop dropdown and match it to "Carrier_Code_102" from the ERP dropdown.

When the integration runs, your custom mapping node simply looks at the Module's settings to determine how to translate the data.

4. Why Use Modules? #

A. Separation of Concerns #

Keep your Connectors focused on technical delivery (sending/receiving data) and your Modules focused on business rules (how the data should look). This makes the entire infrastructure easier to audit and maintain.

B. UI-Driven Flexibility #

By using synchronous actions to populate forms, you empower non-technical users to manage the integration. They can update mappings or change configurations without ever touching a line of code or redeploying a Worker.

C. Advanced Mapping #

Modules turn the Orchesty UI into a dynamic control panel. You are no longer limited by static configuration files; your integration UI becomes as reactive as the APIs it connects to.