> For the complete documentation index, see [llms.txt](https://tsanet.gitbook.io/connect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tsanet.gitbook.io/connect/api-reference/connect-event-bus.md). # Connect Event Bus Describes the event contract for the Connect ActiveMQ 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` | `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`. {% hint style="info" %} **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](#terminology) for the full explanation of this discontinuity. All messages must conform to the CloudEvents v1.0 JSON format (). {% endhint %} ## 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). | ## 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` | {% code title="org.tsanet.connect.case-entry.note.created" %} ```json { "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 } } ``` {% endcode %}