ConvergeERP.Shared.Alerts 0.0.1-beta

ConvergeERP.Shared.Alerts

This package contains the integration events and canonical message contracts required for backend services to trigger notifications via the Alert Service.

Publishing Domain Events

The AlertDomainEvent record is the single, canonical message contract. Services do not need to publish different event types; instead, they publish an AlertDomainEvent and specify the notification type using the EventCode property.

1. Configuration

Ensure MassTransit is configured in your publishing service to route to RabbitMQ:

services.AddMassTransit(cfg =>
{
    cfg.UsingRabbitMq((context, rabbitCfg) =>
    {
        rabbitCfg.Host(new Uri("rabbitmq://your-rabbitmq-host"), h =>
        {
            h.Username("username");
            h.Password("password");
        });
    });
});

2. Triggering a Notification

Inject IBus (or IPublishEndpoint) and send the AlertDomainEvent directly to the alerts.domain-events queue.

private readonly IBus _bus;

public async Task PublishNotificationAsync()
{
    var alertEvent = new AlertDomainEvent
    {
        Id = Guid.CreateVersion7(),
        EventCode = "invoice.awaiting_approval",     // Must match a registered event code
        TenantId = currentTenantId,                  // Required for tenant-scoped events
        CompanyId = currentCompanyId,                // Required for tenant-scoped events
        RecipientIdentityId = approverIdentityId,    // Who should receive the notification
        ReferenceEntity = "Invoice",
        ReferenceEntityId = invoice.Id,
        Payload = new Dictionary<string, JsonElement>
        {
            ["invoiceNumber"] = JsonSerializer.SerializeToElement(invoice.Number)
        },
        CorrelationId = Guid.CreateVersion7(),
        OccurredAt = DateTime.UtcNow
    };

    var endpoint = await _bus.GetSendEndpoint(new Uri("queue:alerts.domain-events"));
    await endpoint.Send(alertEvent);
}

3. Message Fields Breakdown

To ensure your notification is routed and rendered correctly, ensure the fields are populated as follows:

4. Registered Event Codes & Payloads

Each EventCode maps to a specific template. The Payload dictionary must contain the variables the template expects, otherwise they will render as empty strings.

Tenant-Scoped Events (Requires TenantId and CompanyId)

Platform-Scoped Events (Must have TenantId=null and CompanyId=null)