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-Level Subscription Example

Transfer Topic

Receive all transfer events, including:

• Transfer Initiated
• Transfer Status Changed
• RTP Transfer Queued
• RTP Settlement

Event-Level Subscription Example

Transfer Topic

Receive only:

• RTP Settlement

Combined Subscription Example

Transfer Topic

• All Transfer Events

Transaction Topic

• Transaction Status Updated only

RTP Queue Subscription Example

Clients that wish to receive queue-processing notifications should subscribe to the Transfer topic and monitor the following events:

• transfer_queued
• status_change
• rtp_settlement

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:

1. Contact Newline to request a Sandbox Program and begin Message Queue onboarding.

   • Protocol details (e.g., STOMP)
   • Desired Subscription ID
   • List of topics

   Submit your request through our Contact Us page.

2. Receive credentials. Newline will provide:

   • Username and password
   • Host and port details
   • Topic prefixes

3. Establish a durable subscription. Use:

   • client-id in the CONNECT header
   • subscriptionName in the SUBSCRIBE header

Topic Selection Guidance

During onboarding, clients should identify:

• Topics they wish to receive
• Specific event types if event-level filtering is desired
• Sandbox topics needed for testing
• Production topics required for live processing

Topic and event subscriptions can be modified after onboarding by submitting an update request through NOS.

Example (Ruby STOMP)

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

topic = "/topic/topicName"
cli = Stomp::Client.open(hash)
subscription_headers = { "activemq.subscriptionName" => "subname01" }
cli.subscribe(topic, subscription_headers) { |message| puts "msg: #{message}" }
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.

Queue Processing Considerations

• When a transfer enters queue processing, a transfer_queued event is published.
• Receipt of a transfer_queued event does not indicate that transfer processing has completed.
• Consumers should continue monitoring transfer events until a final outcome is received.
• Possible outcomes include:
  • RTP Settlement
  • Transfer Status Changed (Failed)

Queue Lifecycle Diagram

flowchart TD
    A[Created] --> B[Queued]
    B --> C[Settled]
    B --> D[Failed]

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.

Optional: RTP Queue Testing

Before enabling queue-related processing in production, clients should validate handling of:

• transfer_queued
• RTP Settlement
• Failed transfer outcomes

Use the MQ Behavior in Sandbox & Production sandbox testing scenarios.

Related Pages

• Message Queue Authentication
• Message Queue Topics
• Message Queue Topic Definitions
• Message Queue Topic Publication
• Message Queue Subscriptions
• MQ Behavior in Sandbox & Production