Concepts

This page defines the words Bitween uses. The admin UI and the code sometimes name the same thing differently, so both names are given.

Information type#

An information type describes one kind of business document, such as a purchase order or a shipment update. The code calls it a Document.

The information type with id 10001 is reserved for aggregation output.

Duplicates#

With a duplicate window, a payload is compared, by its hash, with the exchanges of its type started within the window, where it first arrives: an API gateway, the older partner endpoint, a scheduled job, the bus or a customer's broker. Retries, aggregations and exchanges made from a response are never checked; they repeat a payload on purpose. The comparison is per partner, so the same document from two partners is two documents. A payload arriving with no partner, from the bus or a broker, matches its earlier copy whichever partner that was routed to.

• Drop duplicates off, the default and how every type that had a window before this behaves: a duplicate goes through like any message, with the reference duplicate-of: <exchange id>, and is counted. The type's page says how many arrived in the last 7 days, which is what to look at before turning dropping on.
• Drop duplicates on: no exchange is made. An API gateway answers with the exchange the payload repeats and the header Bitween-Duplicate-Of, as it answers a replayed Idempotency-Key; the older endpoint answers the same way; a scheduled job's item is taken from the source as if received.

Duplicates are kept for 30 days for the count, and pruned with receive attempts.

Partner#

A partner is an external party you exchange data with.

• Properties are key/value pairs that adapters reference with {{partner.KEY}}, such as a partner's API base URL or account number.
• API keys are named credentials. A caller sends one in the key header (partnerkey unless renamed), as a bearer token or as Basic auth, to call an API gateway or the legacy exchange endpoint.
• Login server identity is the value a login server's tokens carry for this partner. API gateways that take tokens instead of keys use it to know who is calling.
• The built-in SYSTEM partner, id 1, cannot be deleted and cannot own subscriptions. Its key can post documents of any type straight into the filter. See Security.

Subscription#

A subscription is a configured pipeline. It says what starts it, which adapters run and what happens to the response. The UI groups subscriptions by how they start.

A subscription holds:

• Adapters. A receiver, validator, mapper and handler, each optional depending on the type, each with its own properties. See Adapters.
• Data source. A broker or database connection that the subscription's adapters run through. See Data sources.
• Match expression. A filter over the payload, used by internal subscriptions. Bus gateway routes carry their own.
• Schedules for scheduled jobs and aggregations. See Scheduling.
• Response routing. A bus message type name to publish the handler's response under. Older subscriptions may instead feed the response straight into another subscription.
• Retry policy. Either a shared policy or an inline one. See Retries and alerts.
• Work group and category.
• State. Inactive, paused, the running flag, consecutive failures and the last exception.

New subscriptions are created inactive unless the request explicitly asks otherwise.

Exchange#

An exchange is one message travelling through one pipeline. The code calls it an Xchange. Every exchange has:

• An id, a 32-character GUID.
• Its information type, plus its subscription and partner when known.
• Up to three stored files: input is what arrived, output is what the mapper produced, and response is what the handler returned.
• References, free-text tags such as partnerkey: acme-prod.
• A correlation id shared by exchanges of one flow, such as a request and the exchange created from its response.
• Retry for, the id of the exchange it retries. Each exchange can be retried once, so retries form a chain, and later retries continue from its newest attempt.
• A snapshot of the mapper and handler ids and properties, taken when it was created.

An exchange without a subscription is a document-level exchange. Processing it fans the document out to matching subscriptions.

Result#

When processing ends, Bitween writes an exchange result with the same id.

A result also records which retry group matched, the attempt number and, when no retry was scheduled, the reason.

Work group#

A work group is a processing lane. Each work group gets one RabbitMQ queue for exchanges and another for results, with its own prefetch, priority and parallel exchanges. Subscriptions without a work group share the Ungrouped lane. Use work groups to stop a slow or busy integration from delaying the others.

Parallel exchanges is how many of the lane's exchanges run at once on each node. Empty, it is the prefetch, which caps it in any case: a node never holds more than prefetch messages of a lane. At 1 the lane runs one exchange at a time, in the order they arrive, so a partner gets one call at a time per node; above 1 the order within the lane is not kept. Prefetch is the buffer, parallel exchanges the concurrency. The results lane always runs one at a time. The Ungrouped lane takes Bitween:BusDefaultConcurrency.

The queue name is built from the work group's id and its bus message name. Changing the bus message name moves the lane to a new queue.

Global value set#

A global value set is a named dictionary shared by all adapters. Adapters reference a value with {{globals.SETID.KEY}}. The set id is chosen at creation and cannot change.

Gateways#

• An API gateway is an HTTP endpoint at /api/gateway/{urlName}/sync or /async. Each attached partner is paired with the subscription that runs when that partner calls.
• A bus gateway listens for one information type, either on Bitween's internal bus or on a queue of a customer's broker. Each of its routes has an optional match expression, an optional partner and a bus gateway subscription to run.

Other terms#