@memberjunction/entity-communications-base NPM

@memberjunction/entity-communications-base

Base types and abstractions for implementing entity-level communications in MemberJunction. This package provides the foundation for building communication engines that can send messages (email, SMS, etc.) to entity records.

Overview

The Entity Communications Base package enables developers to:

Define communication message types for specific entities
Configure communication fields and templates per entity
Execute bulk communications against entity record sets
Support multiple communication providers (email, SMS, etc.)
Preview messages before sending

Installation

npm install @memberjunction/entity-communications-base

Core Components

EntityCommunicationsEngineBase

Abstract base class for implementing entity communication engines. Provides metadata loading, configuration, and validation capabilities.

import { EntityCommunicationsEngineBase } from '@memberjunction/entity-communications-base';

class MyEntityCommunicationEngine extends EntityCommunicationsEngineBase {
    async RunEntityCommunication(params: EntityCommunicationParams): Promise<EntityCommunicationResult> {
        // Implementation for sending communications
    }
}

EntityCommunicationMessageTypeExtended

Extended entity class that includes related communication fields.

const messageTypes = engine.GetEntityCommunicationMessageTypes(entityID);
messageTypes.forEach(messageType => {
    console.log(`Message Type: ${messageType.Name}`);
    console.log(`Fields: ${messageType.CommunicationFields.map(f => f.Name).join(', ')}`);
});

EntityCommunicationParams

Parameters for executing entity communications:

const params: EntityCommunicationParams = {
    EntityID: 'entity-id-here',
    RunViewParams: {
        EntityName: 'Contacts',
        ExtraFilter: 'Status = "Active"'
    },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        Subject: 'Hello {{FirstName}}',
        Body: 'Welcome to our service!',
        HTMLBody: '<h1>Welcome {{FirstName}}!</h1>'
    },
    PreviewOnly: false,
    IncludeProcessedMessages: true
};

Usage Examples

Basic Implementation

import { 
    EntityCommunicationsEngineBase, 
    EntityCommunicationParams, 
    EntityCommunicationResult 
} from '@memberjunction/entity-communications-base';
import { RegisterClass } from '@memberjunction/global';

@RegisterClass(EntityCommunicationsEngineBase)
export class CustomEntityCommunicationEngine extends EntityCommunicationsEngineBase {
    
    async RunEntityCommunication(params: EntityCommunicationParams): Promise<EntityCommunicationResult> {
        try {
            // Validate entity supports communication
            if (!this.EntitySupportsCommunication(params.EntityID)) {
                return {
                    Success: false,
                    ErrorMessage: 'Entity does not support communications'
                };
            }

            // Get message types for entity
            const messageTypes = this.GetEntityCommunicationMessageTypes(params.EntityID);
            
            // Process and send messages
            const results = await this.processMessages(params);
            
            return {
                Success: true,
                Results: results
            };
        } catch (error) {
            return {
                Success: false,
                ErrorMessage: error.message
            };
        }
    }
    
    private async processMessages(params: EntityCommunicationParams) {
        // Implementation specific to your communication provider
    }
}

Configuration and Initialization

import { CustomEntityCommunicationEngine } from './custom-engine';
import { UserInfo } from '@memberjunction/core';

// Initialize the engine
const engine = CustomEntityCommunicationEngine.Instance;

// Configure with user context
const user = new UserInfo();
await engine.Config(false, user);

// Check if entity supports communication
const entityID = 'some-entity-id';
if (engine.EntitySupportsCommunication(entityID)) {
    // Get available message types
    const messageTypes = engine.GetEntityCommunicationMessageTypes(entityID);
    console.log(`Found ${messageTypes.length} message types`);
}

Sending Communications

// Send email to all active contacts
const result = await engine.RunEntityCommunication({
    EntityID: 'contact-entity-id',
    RunViewParams: {
        EntityName: 'Contacts',
        ExtraFilter: 'IsActive = 1',
        OrderBy: 'LastName, FirstName'
    },
    ProviderName: 'SendGrid',
    ProviderMessageTypeName: 'Email',
    Message: {
        Subject: 'Monthly Newsletter',
        HTMLBody: '<html>...</html>',
        Body: 'Plain text version...'
    },
    PreviewOnly: false,
    IncludeProcessedMessages: true
});

if (result.Success) {
    console.log(`Sent ${result.Results.length} messages`);
    result.Results.forEach(item => {
        console.log(`Sent to: ${item.RecipientData.Email}`);
        console.log(`Message ID: ${item.Message.MessageID}`);
    });
} else {
    console.error(`Communication failed: ${result.ErrorMessage}`);
}

API Reference

EntityCommunicationsEngineBase

Properties

EntityCommunicationMessageTypes: Array of extended message type entities
EntityCommunicationFields: Array of communication field entities
Instance: Static singleton instance of the engine

Methods

Config(forceRefresh?, contextUser?, provider?): Initialize engine configuration
GetEntityCommunicationMessageTypes(entityID): Get message types for an entity
EntitySupportsCommunication(entityID): Check if entity supports communications
RunEntityCommunication(params): Abstract method to implement communication execution

EntityCommunicationParams

EntityID: ID of the entity to communicate with
RunViewParams: Parameters for fetching entity records
ProviderName: Name of the communication provider
ProviderMessageTypeName: Type of message (e.g., 'Email', 'SMS')
Message: Message content object
PreviewOnly?: If true, preview without sending
IncludeProcessedMessages?: Include processed message data in results

EntityCommunicationResult

Success: Boolean indicating operation success
ErrorMessage?: Error details if operation failed
Results?: Array of EntityCommunicationResultItem objects

EntityCommunicationResultItem

RecipientData: Entity record data for recipient
Message: Processed message with provider-specific details

Dependencies

@memberjunction/global: Global utilities and registration
@memberjunction/core: Core MemberJunction functionality
@memberjunction/core-entities: Core entity definitions
@memberjunction/communication-types: Communication type definitions

Integration with Other MJ Packages

This package integrates with:

@memberjunction/communication-types: Provides base communication types and interfaces
@memberjunction/core: Uses BaseEngine pattern and metadata providers
@memberjunction/templates: Can be used with template engine for dynamic content
@memberjunction/server: Server-side implementations typically extend this base