Using Norce [Storm] Event

Norce [Storm] Event is a Publish subscribe solution and enables client solution's needs to listen for specific things that happen within the Norce [Storm] platform.

The events are of two types:

• Notifications are events that require rules and settings (maintained in the Admin UI) in Norce. This could be a change of a product status or when an item has come into stock in the warehouse.
• Events are events that happen by themselves in the platform. This could be when a customer has been registered, or when a payment is reserved.

Requirements

Norce [Storm] Event uses Azure Service Bus topics to implement the event structure. The different event types in Norce is represented as a topics in Azure.

Norce [Storm] uses its own Azure Service Bus artifacts. You don't need any Azure resources on your integration layer.

To use Norce [Storm] Event API, you need to be able to listen to an Azure Service Bus from your solution. Microsoft supports several client platforms, like .net, python, java, node.js and many more.

Read about it here: Azure Messaging documentation

Event types

In the Admin UI you can see the list of built-in event types that can be listened to. They are grouped into:

Event configurations

For every event type you want to listen to, you need to activate them in the Admin UI here.

When you activate (and save) an event you get the authorization information which you need to connect to the service bus. See the configuration fig. below.

Configurations in the Admin UI

• Description This is your own name or description on the event.
• Max delivery count Indicates the maximum number of times a message can be delivered. Once this count has exceeded, message will either be removed from the queue or dead-lettered. Read about poison and dead letters below.
• Lock duration indicates the duration of time during which a message will be locked by a receiver after it is received, ensuring that no other receiver can receive that message. It essentially gives the receiver time to process the message. Once this duration elapses, the message will be available to be received by another receiver. The maximum value for lock duration is 5 minutes (expressed as 00:05:00).
• Time to live Indicates a time-span for which a message will live inside a the topic. If the message is not processed by that time, it will either be removed or dead-lettered.

Listening to events

When listening to events you need several fields, they are:

Code examples

Here is an example program in .net on how to connect to the Azure Service bus and listening after events.

// Install nuget Azure.Messaging.ServiceBus
using Azure.Messaging.ServiceBus;

public class Program
{
    private static bool listening = true;

    // Service bus connection configuration
    private static string ServiceBusNamespace = "sb://stormevent-stage.servicebus.windows.net/"; // LAB - Different per environment
    // string ServiceBusNamespace = "sb://stormevent-stage.servicebus.windows.net/"; // PROD
    // string ServiceBusNamespace = "sb://stormevent-stage.servicebus.windows.net/"; // AZURE PROD
    private static string AccessSignatureName = ""; // 'Shared access name' from admin
    private static string AccessSignatureKey = ""; // 'Shared access key' from admin
    private static string EventName = ""; // 'The event/notification type name'
    private static string SubscriptionName = ""; // 'Subscription name' from admin

    // Create a connectionString from the configuration found in admin
    private static string connectionString = $"Endpoint={ServiceBusNamespace};SharedAccessKeyName={AccessSignatureName};SharedAccessKey={AccessSignatureKey}";

    public static async Task Main(string[] args)
    {
        var spinner = StartSpinner();

        ServiceBusClient client = new ServiceBusClient(connectionString);
        ServiceBusProcessor processor = client.CreateProcessor(EventName, SubscriptionName, new ServiceBusProcessorOptions());

        processor.ProcessMessageAsync += async args =>
        {
            string body = args.Message.Body.ToString();
            Console.WriteLine($"Received message: {body}");
            await args.CompleteMessageAsync(args.Message); // complete the message. messages left uncompleted will be redelivered.
        };

        processor.ProcessErrorAsync += args =>
        {
            Console.WriteLine(args.Exception.ToString());
            return Task.CompletedTask;
        };

        spinner.Start();
        Console.WriteLine($"\nListening for {EventName}. Press enter to stop.");
        await processor.StartProcessingAsync();
        Console.ReadLine(); // Press Enter to stop listening
        listening = false; // Stop the spinner
        await processor.StopProcessingAsync(); // This ensures that the function stops after the current call finishes processing
        Console.WriteLine("\nStopped");
    }

    // Just a spinner
    private static Thread StartSpinner()
    {
        Thread spinner = new Thread(() =>
        {
            var spinnerGraphics = @"-\|/";
            int currentPosition = 0;
            Console.CursorVisible = false;
            while (listening)
            {
                Console.Write(spinnerGraphics[currentPosition]);
                if (++currentPosition == spinnerGraphics.Length)
                {
                    currentPosition = 0;
                }
                Console.SetCursorPosition(Console.CursorLeft - 1, Console.CursorTop);
                Thread.Sleep(130);
            }
            Console.CursorVisible = true;
        });
        return spinner;
    }
}

Monitoring queues

In the Admin UI you can see how many messages that is queued and dead for every event type (topic). You can click on the icon and peek on the first one. From there you can requeue or delete the message (or leave as-is).

Under Settings/Usage you can see message statistics as well.

Dead letter queue (DLQ)

If your client don't fetch your messages (for any reason) they will be moved to the dead letter queue. You can see and manage the dead messages in the Admin UI on the event page.

The purpose of the DLQ is to hold messages that cannot be delivered to your client, or messages that could not be processed. Use the DLQ to monitor and manage the failed messages from your monitoring systems (or from the Admin UI).

Read more about dead letters here: Overview of Service Bus dead-letter queues

Code example .net java (Github)

Common practice

Refine the event settings for Notifications

Make sure to minimize the risk of noise in the event process, by defining only the rules you need on the event setting. If your target system only care about some few product fields, make sure not to listen om other things in the event setting. Read more about Event Settings and the EntityChanged property.

Monitor and manage the Dead letter queues

Set up a monitoring solution that takes responsibility for the dead letters in Norce [Storm] Event. A sudden peak of dead messages can be a symptom of other problems.

Suggested further reading

• System integration patterns
• Calling Norce Commerce Query
• Calling Norce Commerce Connect