Connect Event Bus

Describes the event contract for the Connect ActiveMQ event bus.

The primary queue (connect2) is the integration point for external producers such as the Laravel backend. The Java backend consumes events from this queue, validates and filters them, then fans out to the connect2.events topic.

Each integration adapter has a pre-created durable subscriber queue on the topic (connect2.events.webhook, connect2.events.cisco). Broker-level fan-out means adapters are fully isolated — a failure in one adapter's queue does not affect another adapter's queue.

Internal delivery queues (connect2.webhook.delivery, connect2.cisco.outbox) are managed exclusively by the Java backend and are documented here for completeness only.

Terminology

There is an intentional naming boundary between user-facing APIs and system-to-system communication:

Collaboration Request — the user-facing term exposed by both the Laravel and Java backend APIs. When either API returns data to a user or client application, it translates the internal entity into a "collaboration request". This is the language consumers of either API should use.
Case Entry — the internal term used in the database and in system-to-system communication. Both the Laravel and Java backends work with "case entries" at the database level. The CloudEvent type attribute on this event bus (e.g., org.tsanet.connect.case-entry.created) uses this term because events are exchanged between backend systems, not between a system and a user.

Throughout this document: human-readable titles and summaries use Collaboration Request to match the API contract consumers are familiar with. The CloudEvent type attribute and schema identifiers use case-entry to reflect the system-to-system boundary.

Servers

Server

Host

Protocol

Description

local

localhost:61613

STOMP

Local development only. The ActiveMQ Artemis broker runs embedded inside the Java backend process. STOMP is exposed on port 61613. Credentials are set via spring.artemis.user / spring.artemis.password in your local application properties.

dev

127.0.0.1:61613

STOMP

Shared development environment (connect-dev server). Standalone ActiveMQ Artemis broker running on the same host as both the Java and Laravel backends. Connect using STOMP over TCP on port 61613. Contact the Connect team for credentials.

beta

127.0.0.1:61613

STOMP

Beta environment (connect-beta server). Standalone ActiveMQ Artemis broker running on the same host as both the Java and Laravel backends. Connect using STOMP over TCP on port 61613. Contact the Connect team for credentials.

prod

127.0.0.1:61613

STOMP

Production environment (connect-prod server). Standalone ActiveMQ Artemis broker running on the same host as both the Java and Laravel backends. Connect using STOMP over TCP on port 61613. Contact the Connect team for credentials.

Security: userPassword — ActiveMQ broker credentials. Contact the Connect team per environment.

Channels

Channel

Address

Description

connect2

External integration point. Publish CloudEvents here to notify the Java backend of collaboration request (case entry) lifecycle events. The Java backend validates the event type and fans out to its internal adapters (webhook, Cisco, etc.).

connect2Events

connect2.events

Internal only. MULTICAST fan-out topic managed by the Java backend. After validating an inbound event from connect2, the Java backend publishes it here. Each adapter (webhook, Cisco) has a pre-created durable subscriber queue on this topic for independent, isolated delivery. Do not publish to this topic directly — use connect2 instead.

connect2EventsWebhook

connect2.events.webhook

Internal only. Durable subscriber queue for the webhook adapter. Receives a copy of every event published to connect2.events. Managed exclusively by the Java backend.

connect2EventsCisco

connect2.events.cisco

Internal only. Durable subscriber queue for the Cisco adapter. Receives a copy of every event published to connect2.events. Managed exclusively by the Java backend.

webhookDelivery

connect2.webhook.delivery

Internal only. Webhook delivery queue. The Java backend enqueues a CloudEvent per subscription per event. Managed exclusively by the Java backend.

ciscoOutbox

connect2.cisco.outbox

Internal only. Cisco outbox queue. Single-consumer ordered delivery. Managed exclusively by the Java backend.

The connect2, connect2.events, connect2.events.webhook and connect2.events.cisco channels carry all five messages: CaseCreated, CaseClosed, CaseNoteCreated, CaseResponseCreated, CaseResponseUpdated.

Note on naming: Messages use the user-facing term collaboration request. The CloudEvent type attribute uses the internal term case-entry (e.g., org.tsanet.connect.case-entry.created). See Terminology for the full explanation of this discontinuity.

All messages must conform to the CloudEvents v1.0 JSON format (https://cloudevents.io).

Operations

Operation

Action

Channel

Summary

publishCollaborationEvent

receive

connect2

Receive a collaboration request (case entry) lifecycle event from an external producer. The Java backend consumes one of the supported CloudEvent types whenever a collaboration request (case entry) lifecycle event occurs in an external system. The Java backend validates the type and routes it to all registered integration adapters.

fanOutCollaborationEvent

send

connect2.events

The Java backend publishes validated events for internal fan-out

processWebhookEvent

receive

connect2.events.webhook

Webhook adapter consumes events independently from other adapters

processCiscoEvent

receive

connect2.events.cisco

Cisco adapter consumes events independently from other adapters

deliverWebhook

send

connect2.webhook.delivery

The Java backend enqueues a CloudEvent for delivery to a single subscription endpoint

deliverCisco

send

connect2.cisco.outbox

The Java backend enqueues a Cisco integration job

Messages

All messages use content type application/json.

Message

Title

CloudEvent type

data fields

CaseCreated

Collaboration Request Created

org.tsanet.connect.case-entry.created

case-entry-id

CaseClosed

Collaboration Request Closed

org.tsanet.connect.case-entry.closed

case-entry-id

CaseNoteCreated

Collaboration Request Note Created

org.tsanet.connect.case-entry.note.created

case-entry-id, note-id

CaseResponseCreated

Collaboration Request Response Created

org.tsanet.connect.case-entry.response.created

case-entry-id, response-id

CaseResponseUpdated

Collaboration Request Response Updated

org.tsanet.connect.case-entry.response.updated

case-entry-id, response-id

CaseCreated — A new collaboration request (case entry) has been created.
CaseClosed — A collaboration request (case entry) has been closed.
CaseNoteCreated — A note has been added to a collaboration request (case entry).
CaseResponseCreated — A response has been created on a collaboration request (case entry). Covers approvals, rejections, information requests, and information responses.
CaseResponseUpdated — An existing response on a collaboration request (case entry) has been updated.

CloudEvent envelope

Field

Type

Required

Description

specversion

string

yes

CloudEvents specification version. Always 1.0.

id

string (uuid)

yes

Unique event identifier. Used for idempotency and audit log correlation. Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

source

string

yes

URI identifying the event producer. The Java backend uses /connect2-api. The Laravel backend should use a consistent identifier such as /connect-web-app. Example: /connect-web-app

type

string

yes

CloudEvent type identifying the event.

datacontenttype

string

yes

Always application/json.

time

string (date-time)

yes

ISO 8601 UTC timestamp of when the event occurred. Example: 2024-01-15T10:30:00.000Z

data

object

yes

Event data — see Data fields.

Data fields

Field

Type

Description

case-entry-id

integer (int64)

The internal ID of the case entry (referred to as a "collaboration request" in the user-facing UI and external integrations). Example: 12345

note-id

integer (int64)

The database ID of the note. Example: 67890

response-id

integer (int64)

The database ID of the response record (for response.updated: the updated response record). The response type (APPROVAL, REJECTION, INFORMATION_REQUEST, INFORMATION_RESPONSE) can be determined by fetching this record from the Java backend REST API. Example: 11111

org.tsanet.connect.case-entry.note.created

{
  "specversion": "1.0",
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "source": "/connect-web-app",
  "type": "org.tsanet.connect.case-entry.note.created",
  "datacontenttype": "application/json",
  "time": "2024-01-15T10:30:00.000Z",
  "data": {
    "case-entry-id": 12345,
    "note-id": 67890
  }
}

PreviousWebhook Events