The Lds Integration Hub — Overview

Read this before you integrate with the hub. It explains what the two systems are, which one you need, and what you have to build. building-an-arm.md is the step-by-step guide for the most common case.

Two systems, one landscape

The Integration Hub is a message bus. The DataHub is a central store. They share a database and a management UI, but they solve different problems, and most integrations touch only one of them.

   ERP ──┐                                    ┌──> CRM
         │      ┌──────────────────┐          │
   TMS ──┼─────>│   Orkestrator    │──────────┼──> Project management
         │      │    ("the Ork")   │          │
   … ────┘      └────────┬─────────┘          └──> …
                         │
                         v
                 ┌───────────────┐        ┌────────────────────┐
                 │    DataHub    │<───────│  DataHub API       │
                 │   (MongoDB)   │        │  (direct lookups)  │
                 └───────────────┘        └────────────────────┘

The Integration Hub: a message bus

Systems do not talk to each other. They talk to the Orkestrator — "the Ork" — and the Ork moves messages between them.

A participating service is called an arm. An arm sends messages in, receives messages out, or both. A message carries a topic (Erp-Debtor) and a topic type (Insert, Update, Delete, TableScan, Status, Debug) plus a JSON payload.

The Ork does not know what any message means. When a message arrives it looks up the expectations registered for that topic and type: which arms should receive it, in which order, and with which enrichment. Routing is configuration in the management UI, not code in anyone's service. A sender never names its recipients — it publishes to a topic and forgets. Adding a new consumer to an existing flow is a configuration change and touches no existing arm.

Arms pull; the Ork never pushes. An arm asks for its next message, processes it, and reports the outcome — Success, Retry, Poison, OnHold. Nothing calls into an arm's process, so arms are independently deployable, and an arm that is down queues work rather than losing it.

Order is explicit. Every recipient on an expectation has a Sequence. An arm in sequence 2 is not offered the message until every arm in sequence 1 has reported success. That is where "the debtor must exist before the invoice" lives — in configuration, not in a chain of service calls.

Core vocabulary:

The DataHub: central storage

The DataHub is a MongoDB store of business data — master and transactional. It is a replication hub, not a cache.

The difference matters. The ERP owns debtors. The DataHub subscribes to Erp-Debtor/Updated, stores the debtor, and — only if something actually changed — publishes a message saying the DataHub updated a debtor. Other systems subscribe to that. The debtor spreads across the landscape and the ERP never learns who consumes it. Nothing is coupled to the source system except the one arm that reads it.

DataHub collections are plain documents. Their shape is owned by the source systems, not by the hub.

Which one do you need?

You need an arm if your system produces data others want, or must react when something changes elsewhere. This is the normal case. The work is a console application built on the Lds.IntegrationHub.Models package — see building-an-arm.md.

You need a DataHub API client if your application just wants to look something up and does not want a local replica of the data. Read methods are authored in the management UI as queries with declared parameters and output fields, and your application calls GET /api/v1/{methodName} with an API key. There is no package to reference and no process to host — it is an HTTP call. Write methods and bulk ingest through the API are not built yet; today data enters the DataHub over the bus.

You may need both. An application that both replicates data and does occasional lookups is registered twice.

Arm and ApiClient are never the same registration

An Arm talks to the Ork and exchanges messages. An ApiClient talks to the DataHub API and reads data directly. They are separate registrations with separate, unrelated keys, and nothing links them. An application that only reads through the API needs no arm at all. Do not attempt to use one key for the other — the two systems do not share an identity by design.

What you have to do

1. Decide what you are: a producer, a consumer, both, or an API client.
2. Agree the topics and payload shapes with whoever owns the other end. A payload shape carries a version in its PayloadType (DebtorModelV1); changing the shape without changing the version breaks messages already in flight.
3. Build the arm — building-an-arm.md covers the project setup, the base classes, the statuses, and the deployment.
4. Register it in the Hub.Management UI: an ArmType with its configuration schema, an Arm with its key and configuration, and the expectations that route messages to it. Code with no expectation pointing at it receives nothing — that is the single most common reason a new arm looks dead.
5. Host it with ArmService or PolyArmService on the target machine.

Everything an arm needs at runtime — its configuration, its cursor state, its assemblies, its log destination — comes from the Ork. An arm carries no local configuration file beyond what its host needs to find the Ork.

Reference

• building-an-arm.md — the practical guide: write, register, host, deploy
• arm-cmd-interface.md — the host/arm CLI, environment and settings contract