Workers & Components: The Building Blocks of Orchesty

In Orchesty, you don't just write code to solve a single problem; you build an Inventory of Capabilities. This inventory lives within Workers, which are standalone microservices that act as containers for your applications and logic.

Understanding the relationship between these elements is essential for building a clean, scalable integration architecture.

1. The Worker: Your Microservice Container #

A Worker is a deployable unit of your integration logic. It is a specialized microservice that hosts your code and communicates with the Orchesty platform.

• Isolation: Each worker can be scaled independently, or isolated for security reasons.
• Inventory: The worker tells the platform: "I am here, and I can handle these specific Apps and Nodes."

2. The Application: The Identity & Interface #

The Application (App) is the foundation of any external connection. It represents the "identity" of a system you are communicating with (e.g., Shopify, Jira, or a custom ERP).

The App is responsible for:

• Visual Representation: It holds the Icon and name that appears in the Orchesty UI.
• Configuration (Forms): The App is the only element that defines Forms. These forms allow users to input settings, select choices from dropdowns, and configure how the integration should behave.
• Security: It manages the authentication logic (OAuth, API Keys) and certificates.

In short: The App is who we are talking to and how the user configures that connection.

3. The Connector (Node): The Logic & Action #

A Connector is the "worker bee" of the topology. It is a Node that performs a specific action, such as "Create Invoice" or "Fetch Customer Data."

The Connector is responsible for:

• The Logic (Code): This is where the actual business logic resides. It defines how data is processed, transformed, and sent.
• The "Hook": A Connector doesn't store its own credentials or UI icons. Instead, it links to an Application. It asks the App: "Give me the current access token and the user's settings so I can execute this call."

The Relationship: A single Application can serve dozens of different Connectors. You configure the "Shopify App" once, and then you can use "Shopify Create Product," "Shopify Delete Order," and "Shopify Fetch Customer" connectors that all share that same identity and configuration.

The Custom Node: Independent Logic Units #

While Connectors are designed to bridge the gap between Orchesty and external APIs, not every step in a topology needs to talk to the outside world. Often, you need to perform internal operations: transforming data, routing a process, or applying custom business rules. This is where the Custom Node (or Custom Action) comes in.

Unlike a Connector, a Custom Node is independent of any Application.

Key Characteristics: #

• Self-Sufficient: It doesn't require an Application link because it doesn't need external credentials, OAuth tokens, or third-party settings.
• Payload-Focused: It works purely with the data payload it receives from the previous node in the pipeline.
• Internal Utility: Custom Nodes are the perfect place for Mappers, Filters, or complex calculations that are unique to your specific integration logic.

Connecting the Worker: The Handshake #

Building a worker is only half the story. To bring your logic to life, you must introduce your Worker to the Orchesty orchestration layer. This process is handled in the Orchesty UI in two short steps: register the worker, then choose how it talks to the platform.

1. The Registration Flow #

In the Orchesty Admin UI, you create a new Worker entry. The platform generates a unique set of connection credentials. You add them to your Worker's configuration and the connection is established.

There are two distinct ways this communication can happen.

2. Two Modes of Communication #

Depending on your infrastructure and security requirements, you choose between a standard HTTP connection or a secure Tunnel.

3. How the "Tunnel" Works: Opening the Door #

The Tunnel mode is built for hybrid and secure environments. It works on a "Reverse Connection" principle:

• Outbound Initiation: Instead of the platform trying to "find" your worker on the internet, the Worker opens a persistent connection toward the Orchesty platform.
• The Secure Pipe: Once this connection is established, it stays open. It acts as a private, bi-directional pipe.
• Platform Control: Even though the worker started the connection, the platform is the one that sends commands and data through the tunnel to the worker whenever a topology needs to be executed.

4. Why this Matters #

• Invisible to the Public: Your worker does not need a public IP address or a domain name. To the outside world, your server has no open ports, making it invisible to port scanners and automated attacks.
• No VPN Required: Traditionally, connecting on-prem systems to the cloud required complex VPN tunnels. Orchesty's Tunnel mode achieves the same level of security with zero network configuration.
• Zero-Config Local Dev: You can develop on your laptop, and as long as you have internet access, the platform can "reach" your local code through the tunnel as if it were running in the same data center.

5. Discovery: How the Platform Learns What Your Worker Provides #

Regardless of the connection mode, once the connection is live, the platform queries the Worker for its capabilities. The Worker responds with the list of all registered Applications, Connectors, and Custom Nodes it exposes; these immediately appear in the topology editor for users to drag onto their canvases.

Summary #

• Workers are the containers.
• Applications provide the Identity, UI, and Forms.
• Connectors provide the Code and Logic, leveraging the Apps they are linked to.
• Custom Nodes are your "internal logic" units. They don't need an App because they focus solely on the data flowing through the pipe, not on who is at the other end of the connection.

This modularity ensures that your integrations are DRY (Don't Repeat Yourself). You manage your API connection in one place (the App) and use its power across unlimited actions (the Connectors).

Building your own component #

Whenever you need a custom connector, batch, custom node or application that's not in the Marketplace, the path follows the same five steps — and it always starts by building a worker before you connect it to the platform:

1. Build a worker — pick the SDK (Node.js or PHP), scaffold the project (AI bootstrap or manual), install the SDK and verify the build. Walk-through: Build your first worker.
2. Add an Application class for the external system (or skip this step for a Custom Node — it doesn't need one).
3. Add the node — extend AConnector for a single HTTP call, ABatch for paginated/bulk fetch, or ACustomNode for in-process transforms and filters.
4. Register the components in the worker entry point so the platform discovers them on the next handshake.
5. Connect the worker to your instance in the Admin UI, then wire the node into a topology in the designer. Walk-through: Connect to an instance.

The fastest end-to-end path is the Get Started walkthrough — including the AI shortcut that scaffolds steps 1–4 from a plain-English description. For the SDK-level reference, see Connectors, Batch nodes and Custom nodes.

Where next #

• Hub overview: Five Core Principles
• What runs through these workers: Topologies
• What development on top of it looks like: Working with Orchesty
• Reference (per-language SDK details): Documentation: Workers and SDK