Event Hub Notification Configuration Guide

Overview

ILAP Analytics can publish notifications to Azure Event Hub when the following operations complete:

• Report Schedule Import — Triggered after a schedule file is successfully imported

• Report Schedule Revert — Triggered after a schedule revision is reverted

These notifications allow external systems to react to changes in report schedules, enabling integration scenarios such as:

• Triggering downstream data pipelines

• Updating external dashboards or reports

• Synchronizing data with other systems

---

Prerequisites

Before enabling Event Hub notifications, ensure the following:

1. Azure Event Hub Namespace and Event Hub

Create an Azure Event Hub namespace and an Event Hub instance where notifications will be sent.

2. Managed Identity Permissions

The ILAP Analytics Background Job application is responsible for sending notifications to Event Hub. It uses Managed Identity (DefaultAzureCredential) to authenticate. You must assign the following RBAC role to the Background Job app's managed identity (not the API):

Role	Scope	Description
Azure Event Hubs Data Sender	Event Hub Namespace or specific Event Hub	Allows the Background Job application to send events

To assign this role:

1. Navigate to your Event Hub Namespace in the Azure Portal

2. Go to Access control (IAM) → Add role assignment

3. Select Azure Event Hubs Data Sender role

4. Assign it to the managed identity of your ILAP Analytics Background Job App Service

Note: The Analytics API does not send messages to Event Hub directly. It only schedules the notification job, which is then executed by the Background Job application.

---

Notification Types

ILAP Analytics supports three notification types, each providing different levels of detail about the completed operation.

Type 1: Report Schedule ID Only

NotificationType: 1

Sends a minimal notification containing only the Report Schedule ID. Use this when you only need to know which schedule was modified.

JSON Message Format:

{

  "id": 123

}

Field	Type	Description
id	integer	The Report Schedule ID that was imported or reverted

---

Type 2: Report Schedule ID with Activity IDs

NotificationType: 2 (Default)

Sends the Report Schedule ID along with the IDs of all activities that were changed during the operation. This is useful when you need to know which specific activities were affected.

JSON Message Format:

{

  "id": 123,

  "activities": [

    { "id": 456 },

    { "id": 789 },

    { "id": 1011 }

  ]

}

Field	Type	Description
id	integer	The Report Schedule ID
activities	array	List of changed activities
activities[].id	integer	The Activity ID

Note: If the number of changed activities exceeds the configured BatchSize, multiple messages will be sent (see Batching Behavior).

---

Type 3: Report Schedule with Activity FQDNs

NotificationType: 3

Sends fully qualified URLs for the Report Schedule and each changed activity. This is useful for systems that need direct API endpoints to fetch updated data.

JSON Message Format:

{

  "url": "https://your-api-base-url/api/reportschedule/123",

  "activities": [

    { "url": "https://your-api-base-url/api/reportschedule/123/activity/456" },

    { "url": "https://your-api-base-url/api/reportschedule/123/activity/789" }

  ]

}

Field	Type	Description
url	string	Full URL to the Report Schedule endpoint
activities	array	List of changed activities with URLs
activities[].url	string	Full URL to the Activity endpoint

Important: When using Type 3, you must configure CallbackHostUrl to your API base URL. If not configured, the notification will fail with an error.

---

Configuration

Configuration is done through the Bicep parameters file (main.bicepparam). Two parameter blocks control Event Hub notifications.

Important: The Background Job application is responsible for sending messages to Event Hub. The API only needs to know whether notifications are enabled so it can schedule the notification job.

Configuration Requirements by Application

Application	Required Settings	Purpose
Analytics API	OperationCompletionNotificationConfig.IsEnabled only	Determines whether to schedule notification jobs after import/revert
Background Job	All operationCompletionNotificationConfig properties + eventhubConfig	Executes the actual message sending to Event Hub

Operation Completion Notification Settings

param operationCompletionNotificationConfig = {

  IsEnabled: true

  NotificationType: 2

  CallbackHostUrl: 'https://your-api-base-url/api'

  BatchSize: 2000

}

Property	Type	Required	Description
IsEnabled	boolean	Yes	Set to true to enable notifications, false to disable
NotificationType	integer	Yes	Notification format: 1, 2, or 3 (see Notification Types)
CallbackHostUrl	string	Only for Type 3	Base URL for constructing FQDN URLs. Must be set when NotificationType is 3
BatchSize	integer	Yes	Maximum number of activities per message (see Batching Behavior)

Event Hub Connection Settings

param eventhubConfig = {

  NamespaceUrl: 'your-namespace.servicebus.windows.net'

  EventhubName: 'your-eventhub-name'

}

Property	Type	Required	Description
NamespaceUrl	string	Yes	Fully qualified Event Hub namespace host (without https:// prefix)
EventhubName	string	Yes	Name of the Event Hub to send messages to

Complete Configuration Example

// Enable notifications with Activity IDs

param operationCompletionNotificationConfig = {

  IsEnabled: true

  NotificationType: 2

  CallbackHostUrl: 'https://analytics.contoso.com/api'

  BatchSize: 6000

}

  

// Event Hub connection

param eventhubConfig = {

  NamespaceUrl: 'contoso-analytics.servicebus.windows.net'

  EventhubName: 'schedule-notifications'

}

---

Batching Behavior

When a report schedule operation affects many activities (common for large schedules), notifications are automatically split into multiple messages based on the BatchSize setting.

How Batching Works

1. The system identifies all activities changed during the import/revert operation

2. Activities are grouped into batches of size BatchSize

3. Each batch is sent as a separate Event Hub message

4. All messages for a single operation contain the same Report Schedule ID/URL

Example

If an import changes 5,000 activities and BatchSize is set to 2000:

• Message 1: Report Schedule ID + Activities 1-2000

• Message 2: Report Schedule ID + Activities 2001-4000

• Message 3: Report Schedule ID + Activities 4001-5000

Recommended Batch Sizes by Event Hub Tier

Choose your BatchSize based on your Event Hub pricing tier to optimize throughput and avoid message size limits:

Event Hub Pricing Tier	Recommended BatchSize
Basic	~2,000
Standard	~6,000
Premium	~6,000
Dedicated	~150,000

Note: For Type 1 notifications (Report Schedule ID Only), batching does not apply since no activity details are included.

---

Troubleshooting

Notifications Not Being Sent

Symptom	Possible Cause	Resolution
No notifications sent	IsEnabled is false	Set IsEnabled: true in configuration
No notifications sent	Invalid NotificationType	Ensure NotificationType is 1, 2, or 3
No notifications sent	Missing Event Hub configuration	Configure both NamespaceUrl and EventhubName

Error: "Callback host URL is not configured for FQDN notification"

Cause: NotificationType is set to 3 but CallbackHostUrl is not configured.

Resolution: Add a valid CallbackHostUrl pointing to your Analytics API base URL:

param operationCompletionNotificationConfig = {

  IsEnabled: true

  NotificationType: 3

  CallbackHostUrl: 'https://your-analytics-api.com/api'  // Required for Type 3

  BatchSize: 2000

}

Error: "The event is too large to fit in the batch"

Cause: A single message exceeds Event Hub's maximum message size (256 KB for Basic/Standard, 1 MB for Premium).

Resolution: Reduce the BatchSize to include fewer activities per message.

Authentication/Permission Errors

Cause: The Background Job app's managed identity lacks permission to send events.

Resolution:

1. Verify the managed identity is enabled on the Background Job App Service

2. Assign the Azure Event Hubs Data Sender role at the Event Hub namespace or Event Hub level

3. Wait a few minutes for role assignment propagation

---