@memberjunction/entity-communications-base v2.48.0
@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 entitiesEntityCommunicationFields
: Array of communication field entitiesInstance
: Static singleton instance of the engine
Methods
Config(forceRefresh?, contextUser?, provider?)
: Initialize engine configurationGetEntityCommunicationMessageTypes(entityID)
: Get message types for an entityEntitySupportsCommunication(entityID)
: Check if entity supports communicationsRunEntityCommunication(params)
: Abstract method to implement communication execution
EntityCommunicationParams
EntityID
: ID of the entity to communicate withRunViewParams
: Parameters for fetching entity recordsProviderName
: Name of the communication providerProviderMessageTypeName
: Type of message (e.g., 'Email', 'SMS')Message
: Message content objectPreviewOnly?
: If true, preview without sendingIncludeProcessedMessages?
: Include processed message data in results
EntityCommunicationResult
Success
: Boolean indicating operation successErrorMessage?
: Error details if operation failedResults?
: Array ofEntityCommunicationResultItem
objects
EntityCommunicationResultItem
RecipientData
: Entity record data for recipientMessage
: 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
Build Notes
- TypeScript compilation:
npm run build
- Source files in
/src
, compiled to/dist
- Supports both CommonJS and ES modules
- Type definitions included
License
ISC
8 months ago
8 months ago
5 months ago
8 months ago
8 months ago
6 months ago
7 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
6 months ago
6 months ago
9 months ago
5 months ago
5 months ago
9 months ago
9 months ago
5 months ago
9 months ago
8 months ago
8 months ago
6 months ago
9 months ago
9 months ago
9 months ago
9 months ago
5 months ago
6 months ago
10 months ago
9 months ago
5 months ago
5 months ago
8 months ago
8 months ago
8 months ago
8 months ago
4 months ago
7 months ago
7 months ago
7 months ago
9 months ago
10 months ago
6 months ago
11 months ago
10 months ago
11 months ago
6 months ago
11 months ago
5 months ago
9 months ago
9 months ago
9 months ago
9 months ago
8 months ago
4 months ago
8 months ago
8 months ago
7 months ago
12 months ago
5 months ago
9 months ago
6 months ago
6 months ago
9 months ago
5 months ago
5 months ago
8 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago