@memberjunction/entity-communications-server

Server-side implementation of the MemberJunction Entity Communications Engine. Connects the entity/view system to the communication framework, enabling bulk messaging to records retrieved from entity views with full template rendering, related-entity data resolution, and multi-provider support.

Architecture

graph TD
    subgraph server["@memberjunction/entity-comm-server"]
        ECE["EntityCommunicationsEngine\n(Singleton)"]
    end

    subgraph base["@memberjunction/entity-communications-base"]
        ECB["EntityCommunicationsEngineBase"]
        PARAMS["EntityCommunicationParams"]
    end

    subgraph comm["@memberjunction/communication-engine"]
        CE["CommunicationEngine"]
    end

    subgraph core["@memberjunction/core"]
        RV["RunView"]
        MD["Metadata"]
    end

    subgraph providers["Registered Providers"]
        SG["SendGrid"]
        GM["Gmail"]
        TW["Twilio"]
        MSP["MS Graph"]
    end

    ECB --> ECE
    ECE -->|queries records| RV
    ECE -->|sends messages| CE
    CE --> SG
    CE --> GM
    CE --> TW
    CE --> MSP

    style server fill:#2d8659,stroke:#1a5c3a,color:#fff
    style base fill:#2d6a9f,stroke:#1a4971,color:#fff
    style comm fill:#7c5295,stroke:#563a6b,color:#fff
    style core fill:#b8762f,stroke:#8a5722,color:#fff
    style providers fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/entity-communications-server

Usage

Basic Example

import { EntityCommunicationsEngine } from '@memberjunction/entity-communications-server';
import { EntityCommunicationParams } from '@memberjunction/entity-communications-base';

const engine = EntityCommunicationsEngine.Instance;
await engine.Config(false, contextUser);

const params: EntityCommunicationParams = {
    EntityID: 'entity-uuid',
    RunViewParams: {
        EntityName: 'Contacts',
        ExtraFilter: 'Status = "Active"'
    },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        Subject: 'Welcome',
        Body: 'Hello {{FirstName}}!',
        HTMLBodyTemplate: htmlTemplate
    },
    PreviewOnly: false
};

const result = await engine.RunEntityCommunication(params);
if (result.Success) {
    console.log(`Sent ${result.Results.length} messages`);
}

Template Parameters with Related Entity Data

When templates reference related entities, the engine automatically fetches the related data in batch and populates each recipient's context:

const params: EntityCommunicationParams = {
    EntityID: 'customer-entity-id',
    RunViewParams: { EntityName: 'Customers', ViewName: 'Premium Customers' },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        BodyTemplate: templateWithRelatedEntities
    }
};
// Engine auto-fetches related orders for each customer
const result = await engine.RunEntityCommunication(params);

Checking Entity Communication Support

if (engine.EntitySupportsCommunication(entityID)) {
    const messageTypes = engine.GetEntityCommunicationMessageTypes(entityID);
    messageTypes.forEach(mt => {
        console.log(`Type: ${mt.BaseMessageType}`);
        mt.CommunicationFields.forEach(field => {
            console.log(`  Field: ${field.FieldName} (Priority: ${field.Priority})`);
        });
    });
}

Processing Pipeline

sequenceDiagram
    participant App as Application
    participant ECE as EntityCommunicationsEngine
    participant RV as RunView
    participant CE as CommunicationEngine
    participant P as Provider

    App->>ECE: RunEntityCommunication(params)
    ECE->>ECE: Validate entity, provider, message type
    ECE->>RV: RunView(params.RunViewParams)
    RV-->>ECE: Entity records[]
    ECE->>ECE: Load related entity data (batch)
    loop For each record
        ECE->>ECE: Build message with record context
        ECE->>CE: SendSingleMessage(provider, type, message)
        CE->>P: SendSingleMessage(processedMessage)
        P-->>CE: MessageResult
        CE-->>ECE: MessageResult
    end
    ECE-->>App: EntityCommunicationResult

Key Features

• Bulk Message Sending: Send to all records from an entity view in a single call
• Template Parameter Resolution: Automatically fetches related entity data for template parameters
• Multi-Provider Support: Works with any registered communication provider (email, SMS, etc.)
• Preview Mode: Test communications without sending (PreviewOnly: true)
• Context Data Population: Per-recipient template context from entity record fields
• Scheduled Sending: Supports provider-level SendAt scheduling
• Communication Logging: All sends are tracked through CommunicationRun and CommunicationLog entities

Configuration

Entity Communication Setup

For an entity to support communications:

1. Configure Entity Communication Message Types in the MJ metadata
2. Set up Entity Communication Fields to define recipient address fields
3. Configure field priorities for automatic recipient resolution

Template Parameters

Templates support multiple parameter types:

• Record: The current entity record being processed
• Entity: Related entity data fetched based on relationships
• Array/Scalar/Object: Direct programmatic use (not supported in messaging)

When using related entity parameters, the engine automatically:

1. Identifies unique relationships needed
2. Fetches all related data in batch queries
3. Filters related data per recipient record
4. Populates template context with filtered data

Dependencies

| Package | Purpose | |---------|---------| | @memberjunction/entity-communications-base | Shared types and base engine class | | @memberjunction/communication-engine | CommunicationEngine for message delivery | | @memberjunction/core | RunView, Metadata, UserInfo, EntityInfo | | @memberjunction/core-entities | Entity type definitions | | @memberjunction/global | Class registration |

Development

npm run build    # Compile TypeScript
npm start        # Watch mode