Overview

This guide outlines how to subscribe to Newline MQ topics, including setup, registration, durable subscription configuration, and best practices. MQ subscriptions allow clients to consume real-time event notifications using protocols like STOMP, AMQP, MQTT, and WSS.

Newline publishes event messages to durable MQ topics. Clients can subscribe at:

Topic-level: Receive all events under a topic (e.g., all transfer events).
Event-level: Subscribe to specific event types (e.g., only RTP Settlement).
Combination: Mix topic and event-level subscriptions for granular control.

Topic Naming Convention

MQ topics follow this format:

/topic/<client>.<environment>.<topic_name>

Example:\ /topic/neal.abc-enterprises.sandbox.transaction

Newline provides topic names during onboarding. Clients must use the /topic/ prefix when subscribing.

Registration Process

To subscribe to MQ topics:

Contact Newline Onboarding Support (NOS)\ Provide:
- Protocol details (e.g., STOMP)
- Desired Subscription ID
- List of topics
📧 Email: [email protected] or submit via ServiceNow.
Receive Credentials\ Newline will provide:
- Username and password
- Host and port details
- Topic prefixes
Establish Durable Subscription\ Use:
- client-id in the CONNECT header
- subscriptionName in the SUBSCRIBE header

Example (Ruby STOMP)

hash = {
  :host =&gt; [
    {:login =&gt; login(), :passcode =&gt; passcode(), :host =&gt; host(), :port =&gt; port(), :ssl =&gt; true}
  ],
  :reliable =&gt; true,
  :connect_headers =&gt; {
    :host =&gt; "localhost",
    :"accept-version" =&gt; "1.2",
    :"client-id" =&gt; "dursubcli01"
  }
}

topic = "/topic/topicName"
cli = Stomp::Client.open(hash)
sh = {"activemq.subscriptionName" =&gt; "subname01"}
cli.subscribe(topic, sh) { |msg| puts "msg: #{msg}" }
cli.unsubscribe(topic)

Subscription Behavior

MQ delivers one copy of a message to each subscription with a unique Subscription ID.
Multiple listeners using the same Subscription ID will share message delivery.
Durable subscriptions ensure messages are retained even if the client disconnects.

Managing Subscriptions

To unsubscribe or update your MQ subscriptions:

Contact NOS and specify the topics or events to remove.
Subscriptions will be updated or terminated accordingly.

Best Practices

Use durable subscriptions for fault tolerance.
Implement idempotency using event_id.
Monitor connection health and retry logic.
Test thoroughly in sandbox before going live.