Messaging Patterns

Drex supports two functional ways to move data between adapters:

  • Direct – the message is addressed to one specific adapter.

  • Broadcast – the message is fanned-out to every adapter that subscribed to a topic.

An optional Feedback channel can accompany any Direct pattern so the sender learns if delivery fails.

The header x.abs.scope is not required for routing, but supplying it makes intent explicit and improves traceability.

Its allowed values come from the Scope enum (excerpt below).

BROADCAST, LINEAR, REQUEST, RESPONSE, IN_STREAM, OUT_STREAM, OTHER, UNKNOWN

OTHER and UNKNOWN are edge-cases; use them only after consulting the Common Core team.

Direct Patterns

Direct patterns deliver a message to one, and only one, adapter.

Routing succeeds as long as four key headers are present; the other fields simply add clarity or enable extra behaviour such as feedback and correlation.

# Minimal Headers

Purpose | IHeader Property | What to Supply

Identify the sender site | SourceSite (type + id) | e.g. SiteType.VESSEL / 9304249

Identify the target site | TargetSite (type + id) | e.g. SiteType.CENTRAL / null

Identify the sender app | SourceApp.Name | your adapter name

Identify the target app | TargetApp.Name | destination adapter name

These four values are mapped by the Service-Bus library to the wire-level headers

x.abs.site.src.*, x.abs.site.trg.*, x.abs.app.src.name, x.abs.app.trg.name.

x.abs.scope is optional for delivery, but setting it makes log traces and diagnostics far more readable.

Use one of: LINEAR, REQUEST, RESPONSE, IN_STREAM, OUT_STREAM.

# Pattern Variants

Pattern | Optional IHeader fields to set | Typical Use-Case

LINEAR | Scope = Scope.LINEAR | One-way notification; no reply expected

REQUEST / RESPONSE | Scope = Scope.REQUEST (response sets Scope = Scope.RESPONSE) CorrelationId (strongly recommended) | Ask for a single reply

INSTREAM / OUTSTREAM | Scope = Scope.INSTREAM (responses set Scope = Scope.OUTSTREAM) CorrelationId (for grouping) | Bi-directional streaming conversation

# Enabling Feedback (Optional)

Feedback functionality supported only for Direct Pattern.

To learn why a Direct message failed (expired, bad app, etc.):

  • Set FeedbackRequest in the header object.

• The library converts this into x.abs.feedback.request = TRUE.

  • DREX-M returns a feedback message with FeedbackResponse populated.

  • Consume it from q.cc.drex.inbox.feedback.adapter.<your-adapter>.

Possible FeedbackResponse.Cause values include EXPIRED, REJECTED, BAD_APP, BAD_SITE, BAD_TENANT, OVERFLOW, OTHER, and UNKNOWN.

# Setting Headers with the Library (Conceptual)

  • Create a message or use the builder class provided by the library.

  • Populate the four routing fields (SourceSite, TargetSite, SourceApp, TargetApp).

  • (Optional) set Scope, CorrelationId, and FeedbackRequest.

  • Publish; the library serialises all supplied properties to their correct x.abs.* header names.

No additional work is needed—once those properties are set, Drex will route the message to the queue q.cc.drex.inbox.direct.adapter.<TargetApp.Name> and, if requested, any feedback will return to your adapter’s feedback queue.

Broadcast Pattern

Broadcast delivers a single publish to every adapter that

a) subscribed to the topic in its registration file, and

b) lies within the broadcast range you specify in the message header.

The actual fan-out is handled inside Drex; you still publish to the same exchange e.cc.drex.portal.

Important: For a Broadcast message to be routable, the header

x.abs.scope must be present and set to BROADCAST.

# Site Ranges in the Library

The Service-Bus library represents broadcast reach with the helper types:

  • SiteRangeArea – NONE, LOCAL, WIDE (plus UNKNOWN)

  • SiteRange – a (SiteType, SiteRangeArea) pair

  • SiteRanges – a collection of SiteRange objects, one per tier you want to mention

new SiteRanges(

new SiteRange(SiteType.VESSEL , SiteRangeArea.LOCAL),

new SiteRange(SiteType.CENTRAL, SiteRangeArea.NONE),

new SiteRange(SiteType.CLOUD , SiteRangeArea.NONE)

)

The library serialises each SiteRange entry to the corresponding header:

SiteType | Wire Header

VESSEL | x.abs.bcast.area.vessel

CENTRAL | x.abs.bcast.area.central

CLOUD | x.abs.bcast.area.abs_cloud

# Minimal Headers

Purpose | IHeader Property | Wire-level Header | Notes

State the topic | Topic | x.abs.topic | Follows a.b.c dot-notation; wildcards * / # allowed in subscription, not in sender.

Identify the sender site | SourceSite | x.abs.site.src.* | Required for traceability.

Define the broadcast range | BroadcastRange | x.abs.bcast.area.* | Controls which tiers receive the message.

(optional) label intent | Scope = Scope.BROADCAST | x.abs.scope | Helpful for observability but not required.

Because every client has exactly one Central and one Cloud tier, LOCAL and WIDE are treated the same for those tiers; on the Vessel tier they differ (LOCAL ⇢ this vessel only, WIDE ⇢ all vessels).

# Required Headers

Purpose | IHeader Property | Serialized Wire Header

Declare the pattern | Scope = Scope.BROADCAST | x.abs.scope = BROADCAST (mandatory)

State the topic | Topic | x.abs.topic

Identify the sender | SourceSite | x.abs.site.src.type / src.id

Define the site ranges | BroadcastRange (type: SiteRanges) | x.abs.bcast.area.vessel x.abs.bcast.area.central x.abs.bcast.area.abs_cloud

If any of these headers are missing or x.abs.scope ≠ BROADCAST, the message is treated as unroutable and dropped.

No feedback is generated for Broadcast messages.

# Example Range Combinations

Desired Reach | SiteRanges Builder Example | Serialized Broadcast Headers

Only this vessel | new SiteRange(VESSEL, LOCAL) | x.abs.bcast.area.vessel = LOCAL

All vessels + Central | new SiteRanges( &nbsp;&nbsp;new SiteRange(VESSEL, WIDE), &nbsp;&nbsp;new SiteRange(CENTRAL, LOCAL), &nbsp;&nbsp;new SiteRange(CLOUD, NONE)) | x.abs.bcast.area.vessel = WIDE x.abs.bcast.area.central = LOCAL x.abs.bcast.area.abs_cloud = NONE

Central + Cloud (no vessels) | new SiteRanges( &nbsp;&nbsp;new SiteRange(VESSEL, NONE), &nbsp;&nbsp;new SiteRange(CENTRAL, LOCAL), &nbsp;&nbsp;new SiteRange(CLOUD , LOCAL)) | x.abs.bcast.area.vessel = NONE x.abs.bcast.area.central = LOCAL x.abs.bcast.area.abs_cloud = LOCAL

For Central and Cloud tiers (single instance per client), LOCAL and WIDE are effectively the same; choose either for delivery, or NONE to exclude.

# Broadcast Checklist

  • Set Scope to BROADCAST. (required)

  • Assign a Topic. Example: fleet.status.

  • Build BroadcastRange via a SiteRanges object to include or exclude each tier as needed.

  • Populate SourceSite for observability.

  • Publish to e.cc.drex.portal.

The Service-Bus library converts your IHeader properties to the correct x.abs.* headers automatically.

Adapters that subscribed to the topic and reside inside the specified ranges will receive the message in their broadcast inbox q.cc.drex.inbox.broadcast.adapter.<name>

Broadcast messages do not support feedback.