Skip to main content

Queue API

Erik Wihlborg
Updated

The TraX Queue API enables event-driven integration for time-critical workflows. It is designed for scenarios where low latency and reliable event delivery are required. Access to the message queues is established during the technical onboarding phase.

For real-time events — such as when a device is commission / decommissioned,  we strongly recommend consuming notifications through the Queue API. While events can also be retrieved via the Web API, message queues provide lower latency, improved scalability, and better support for asynchronous processing.

Broker endpoints and queue names are documented in the Integration Environments article.

APIs and Protocols

TraX uses Apache ActiveMQ as its message broker.

ActiveMQ supports a wide range of client libraries and programming environments, including:

  • Java Message Service (JMS) 1.1
  • .NET Message Service (NMS)
  • Node.js, Go, Python, Ruby, C++, and others

Supported wire-level protocols include AMQP, STOMP, OpenWire, WebSocket, and MQTT. Clients may use any compatible library that supports these protocols.

Connecting to the ActiveMQ Broker

You may connect using any supported ActiveMQ client implementation .

The ActiveMQ service supports TLS versions 1.0 through 1.3.

Security requirement: Clients must use TLS 1.2 or higher. TLS 1.3 is recommended where supported. TLS 1.0 and TLS 1.1 must not be used, as they are considered insecure.

Example: Connecting Using .NET Message Service (NMS)

The example below demonstrates how to connect to ActiveMQ using:

Setup Steps

  1. Install the C# extension for Visual Studio Code and a NuGet package manager extension.
  2. Install the Apache.NMS.ActiveMQ package.
  3. Insert the following code into your project and replace Username, Password, and queue/broker values with your assigned credentials and endpoints.
// Example: How to connect using .NET Message Service (NMS)

using System;
using Apache.NMS;
using Apache.NMS.Util;
using System.Threading;

namespace Apache.NMS.ActiveMQ.Test
{
    class Program
    {
        protected static AutoResetEvent semaphore = new AutoResetEvent(false);
        protected static ITextMessage message = null;
        protected static TimeSpan receiveTimeout = TimeSpan.FromSeconds(10);

        // Queue and authentication details
        private const string Queue = "queue://queue.to.connect";
        private const string Username = "";
        private const string Password = "";

        // ActiveMQ environment
        private const string Url1 = "ssl://b-f3bf4075-a59b-48ed-a758-7cdf2d2d3dce-1.mq.eu-west-1.amazonaws.com:61617";
        private const string Url2 = "ssl://b-f3bf4075-a59b-48ed-a758-7cdf2d2d3dce-2.mq.eu-west-1.amazonaws.com:61617";
        private const string TransportProtocol = "failover";

        static void Main(string[] args)
        {
            // Create connection URI
            string uri = string.Format("{0}:({1},{2})", TransportProtocol, Url1, Url2);
            Uri connecturi = new Uri(uri);
            Console.WriteLine("Connecting to " + connecturi);

            // Create connection factory
            IConnectionFactory factory = new ConnectionFactory(connecturi);

            // Using connection and session
            using (IConnection connection = factory.CreateConnection(Username, Password))
            using (ISession session = connection.CreateSession())
            {
                IDestination destination = SessionUtil.GetDestination(session, Queue);
                Console.WriteLine("Using destination: " + destination);

                // Create a consumer and producer
                using (IMessageConsumer consumer = session.CreateConsumer(destination))
                using (IMessageProducer producer = session.CreateProducer(destination))
                {
                    // Start the connection to process messages
                    connection.Start();

                    producer.DeliveryMode = MsgDeliveryMode.Persistent;
                    producer.RequestTimeout = receiveTimeout;
                    consumer.Listener += new MessageListener(OnMessage);

                    // Send a message
                    ITextMessage request = session.CreateTextMessage("Hello World!");
                    request.NMSCorrelationID = "abc";
                    request.Properties["NMSXGroupID"] = "cheese";
                    request.Properties["myHeader"] = "Cheddar";

                    producer.Send(request);

                    // Wait for the message
                    semaphore.WaitOne((int)receiveTimeout.TotalMilliseconds, true);

                    if (message == null)
                    {
                        Console.WriteLine("No message received!");
                    }
                    else
                    {
                        Console.WriteLine("Received message with ID: " + message.NMSMessageId);
                        Console.WriteLine("Received message with text: " + message.Text);
                    }
                }
            }
        }

        // Message listener
        protected static void OnMessage(IMessage receivedMsg)
        {
            message = receivedMsg as ITextMessage;
            semaphore.Set();
        }
    }
}
  1. In the Visual Studio Code terminal, change the current directory to the directory where your code is located, and type "dotnet run”

Complementary guidance is available in C# programming with Visual Studio Code