Broadcast Receptors

In this scenario, an external alert service (or internal application) generates alert notifications (for example, system warnings, status updates, or critical business notifications). These alerts are sent through the Connectifi broadcast Receptor and then pushed to different subscribed applications. Each application, which is integrated via the Connectifi Agent SDK, listens for these alert contexts and then displays or processes the notification accordingly. This approach decouples alert generation from alert consumption, enabling a centralized, flexible alerting platform across your ecosystem.

Sequence Diagram

In this diagram, the Alert Service sends alerts to the Receptor. The Receptor then enqueues the alert data onto a broadcast channel (such as “connectifiAlerts”) using Connectifi’s internal routing. Target applications that have registered listeners for alert contexts (e.g., context type “connect.notification”) receive and process the incoming alerts.

Implementation Patterns & Code

Below are two code examples: one for pushing alerts from the Receptor side and another for receiving these alerts in a target application.

1. Receptor Implementation to Broadcast Alerts

This TypeScript code snippet demonstrates how you can use the Connectifi Receptor to broadcast an alert:

import { createReceptorAgent } from '@connectifi/sdk';
import { Context } from '@finos/fdc3';
 
interface AlertParams {
    subject: string;
    body: string;
    alertType: 'info' | 'warning' | 'error';
    priority: number;
    context: Context; 
}
 
const sendAlert = async ({ subject, body, alertType, priority, context }: AlertParams) => {
    // Define your host configuration and authentication credentials
    const interopHost = '<YOUR_INTEROP_HOST>';
    const token = '<YOUR_API_JWT>';
    const from = '<YOUR_USER_IDENTIFIER>';
    
    // Create a receptor agent using the Connectifi SDK
    const receptorAgent = createReceptorAgent({ interopHost });
 
    // Structure the alert data with a specific channel (e.g., "connectifiAlerts")
    const alertData = {
        channel: "connectifiAlerts",
        context: {
            type: "connect.notification",
            subject,
            body,
            alertType,
            priority,
            source: "alerts service",
            context: context,
        }
    };
 
    // Broadcast the alert to downstream applications
    receptorAgent.broadcast(token, from, alertData);
};
 
// Example usage:
sendAlert({
    subject: "Server Down",
    body: "The production server is down. Immediate action required.",
    alertType: "error",
    priority: 1,
    context: {
        type: "custom.alert",
        data: { serverId: 'PROD-01' }
    }
});

2. Target Application – Listening for Alerts

On the receiving side, each application must register a listener using the Connectifi Agent SDK to handle the incoming alert context:

import { DesktopAgent } from '@finos/fdc3';
import { createAgent } from 'https://platform.connectifi.app/agent/main.bundle.js';
 
const initializeAgent = async () => {
    const agent: DesktopAgent = await createAgent('https://platform.connectifi.app', 'YOUR_APP_DIRECTORY_ID');
    
    // Listen for alert contexts (e.g., "connect.notification")
    agent.addContextListener('connect.notification', (context) => {
        console.log('Alert received:', context);
        // Process incoming alert - for example, show a popup notification
        // Your custom alert handling logic here
    });
};
 
initializeAgent();

Using this pattern ensures that any alert pushed through the broadcast Receptor is received by all subscriber applications registered on the alert channel.

Connectifi Platform Configuration

To enable this workflow in the Connectifi Admin UI, you need to:

1. Create or configure your application directory where your applications are registered. Ensure the directory Interop Strategy is set to ‘Open & Auth’ or ‘Strict’
2. Configure your Receptor in the application you wish to broadcast from. Permission the allowed channels for the receptor to include “connect.notification”.
3. After configuring get the Receptor API Key and end point Url and use these in your broadcasting code.
4. Register your receiving applications with the Connectifi Agent SDK so that they can subscribe to the “connect.notification” or custom alert contexts.