Link3 to Link3 communication

Recommended approach: Built-in HTTP integration (push)

To exchange documents between two Link3 systems, we recommend using the built-in HTTP components. The setup is divided into sender and receiver responsibilities:

On the Receiver System

Configure HttpHandler
- Enable Built-in security on the HttpHandler.
Create a service account
- Assign exactly this permission:
  - API_GenericHttpHandler
- Do not grant any additional permissions.
Issue a Personal Access Token (PAT)
- Generate a PAT for the service account.
- This PAT will later be used by the sender system to authenticate.

On the Sender System

Configure HttpSend
- Use the built-in HttpSend component to send documents to the receiver’s HttpHandler.
Set up Basic Authentication
- Username: fill with a dummy value (ignored by the receiver).
- Password: use the PAT issued by the receiver system’s service account.

This push-based setup is straightforward, secure, and requires only minimal configuration. It works well for standard, synchronous delivery patterns where the sender initiates the transfer and the receiver simply accepts documents. You can also add an init-config to the HttpHandler if any additional configuration of the flow is required.

Alternative: LinkConnect (supports poll and push, with status events)

For more complex flows—especially when the sender must receive an explicit status event (success/failure) from the receiver—use LinkConnect components (available for both Link2 and Link3):

Transport.Send (send)
Transport.Retrieve (receive from outbox; polling)
Status event handlers

How LinkConnect works

Poll (pull) flow

The receiver polls the sender using Transport.Retrieve and fetches documents from the sender’s outbox.
During polling, an ID from the sender is promoted to context properties.
The status event handler reads this ID and notifies the sender whether processing completed or failed.

Push flow

The sender uses Transport.Send to deliver to the receiver’s inbox.
Context properties (including IDs) are attached by the sender.
The status event handler uses these to acknowledge success/failure back to the sender.
Just like with HttpSend, the push flow requires Basic Authentication where the receiver issues a PAT that the sender uses as password (username is a dummy value).

Current limitation

Polling does not yet support batched documents, because status handlers operate on document IDs, not interchange-out IDs.
Batching is supported with Transport.Send (push), which includes all document IDs in batch scenarios.

Poll (pull) vs Push — what’s the difference?

Aspect	Poll (Receiver pulls)	Push (Sender pushes)
Initiation	Receiver controls retrieval schedule.	Sender initiates delivery immediately.
Credentials & trust	Credentials are issued by the sending system; polling endpoint can be tightly scoped.	Requires PAT issued by the receiver. Used as password in Basic Auth with dummy username.
Flow control	Fine-grained control on receiver side (e.g., InitConfig on the polling location) to throttle/sequence.	Receiver has less control over timing; pacing is driven by the sender.
Status feedback	Built-in via status event handler using promoted document ID.	Built-in via status event handler using sender-supplied context properties.
Batching	Not supported (yet) in polling; operates on document IDs only.	Supported; sends all document IDs in batch scenarios.
Operational model	Good when receiver wants to own throughput and windows (e.g., maintenance, load management).	Good for simple, immediate deliveries initiated by the sender.

Installing LinkConnect Components

The LinkConnect components are not part of the standard Link3 system components. Instead, they are distributed as NuGet packages and must be installed separately. They can then be integrated directly into Link2 or Link3 solutions. To access them, add the following feed to your NuGet configuration:

CODE

https://bizbrains-productteam.pkgs.visualstudio.com/Link3Public/_packaging/LinkConnect/nuget/v3/index.json

When to choose what?

Use built-in HttpSend + HttpHandler (push)
When you want the simplest, native Link3-to-Link3 delivery with minimal moving parts, secured with a service account + PAT and Basic Auth.
Use LinkConnect (poll or push)
When you need status events and/or receiver-side flow control. Prefer poll if you want the receiver to control pacing and credentials issuance; choose push (Transport.Send) if you need batching today or you want sender-driven immediacy.