Event Gateways - Gateway Instances
Create and manage event gateway instances for asynchronous messaging
Overview
Gateway instances are individual running instances of event gateways that process asynchronous events in ColdFusion. Each instance is based on a gateway type (SMS, IM, custom) and can be configured with specific settings, startup behavior, and CFCs to handle incoming messages or events.
Event gateways enable ColdFusion applications to respond to events from external systems without requiring direct HTTP requests, making them ideal for SMS processing, instant messaging, directory monitoring, and custom integration scenarios.
Gateway Instance Configuration
Essential settings for creating and managing gateway instances.
Gateway ID
SMS_Notifications or Order_Directory_MonitorGateway Type
CFC Path
/opt/coldfusion2025/cfusion/gateway/cfc/SMSHandler.cfc). Separate multiple paths with commas.onIncomingMessage() by default for gateways such as CFML, SMS, and XMPP; onAdd(), onChange(), and onDelete() by default for DirectoryWatcherConfiguration File
Startup Mode
Manual: Must be started explicitly
Disabled: Gateway will not start
Development: Manual for testing
Common Gateway Types
Built-in gateway types and their typical use cases.
SMS Gateway
- Purpose
- Send and receive SMS messages
- Use Cases
- Notifications, two-factor authentication, mobile alerts
- Requirements
- SMS provider account and credentials
Processes incoming SMS messages and sends outbound messages through SMS providers. Deprecated in ColdFusion 2025.
XMPP (Jabber) Gateway
- Purpose
- Instant messaging integration
- Use Cases
- Chat bots, notifications, team communication
- Requirements
- XMPP server connection details
Enables ColdFusion to send and receive instant messages via XMPP protocol.
Directory Watcher
- Purpose
- Monitor file system for changes
- Use Cases
- File processing, import automation, batch jobs
- Requirements
- Directory path and file permissions
Watches directories for file additions, changes, or deletions and triggers CFC processing.
DataManagement Gateway
- Purpose
- BlazeDS data synchronization
- Use Cases
- Flex/Flash applications (legacy)
- Status
- Removed in ColdFusion 2025
Provided data services for Adobe Flex applications. Not available in ColdFusion 2025.
Gateway Instance Management
Operations available for managing gateway instances.
Start/Stop/Restart
Status Monitoring
Example Gateway Listener CFC
Basic gateway listener CFC showing core functionality:
// gateway/cfc/SMSHandler.cfc
component {
/**
* Process incoming SMS messages
* @cfcEvent The event object containing message data
*/
public void function onIncomingMessage(required struct cfcEvent) {
// Extract message data
var senderPhone = arguments.cfcEvent.originatorID;
var messageText = arguments.cfcEvent.data.message;
var gatewayID = arguments.cfcEvent.gatewayID;
// Log the incoming message
writeLog(
file = "sms-gateway",
type = "information",
text = "SMS from #senderPhone#: #messageText#"
);
try {
// Process the message
processSMSCommand(senderPhone, messageText);
} catch (any e) {
// Log errors
writeLog(
file = "sms-gateway",
type = "error",
text = "Error processing SMS: #e.message#"
);
}
}
/**
* Process SMS commands
*/
private void function processSMSCommand(
required string phone,
required string message
) {
// Parse command (e.g., "SUBSCRIBE", "STOP", "HELP")
var command = trim(ucase(arguments.message));
switch (command) {
case "SUBSCRIBE":
// Add to subscription list
subscribeUser(arguments.phone);
sendSMSReply(arguments.phone, "You are now subscribed!");
break;
case "STOP":
case "UNSUBSCRIBE":
// Remove from subscription list
unsubscribeUser(arguments.phone);
sendSMSReply(arguments.phone, "You have been unsubscribed.");
break;
case "HELP":
sendSMSReply(
arguments.phone,
"Commands: SUBSCRIBE, STOP, HELP"
);
break;
default:
sendSMSReply(arguments.phone, "Unknown command. Reply HELP for options.");
}
}
/**
* Send SMS reply
*/
private void function sendSMSReply(
required string phone,
required string message
) {
// Use SendGatewayMessage to send reply
var msgData = {
"command" = "submit",
"destAddress" = arguments.phone,
"shortMessage" = arguments.message
};
sendGatewayMessage("SMS_Notifications", msgData);
}
private void function subscribeUser(required string phone) {
// Database logic to add subscriber
queryExecute(
"INSERT INTO sms_subscribers (phone, subscribed_date) VALUES (?, ?)",
[arguments.phone, now()],
{datasource: "myDB"}
);
}
private void function unsubscribeUser(required string phone) {
// Database logic to remove subscriber
queryExecute(
"DELETE FROM sms_subscribers WHERE phone = ?",
[arguments.phone],
{datasource: "myDB"}
);
}
}// gateway/cfc/FileProcessor.cfc
component {
/**
* DirectoryWatcher calls onAdd, onChange, and onDelete by default
* (configurable via addFunction, changeFunction, deleteFunction).
* data.filename holds the path of the changed file.
*/
public void function onAdd(required struct cfcEvent) {
var fullPath = arguments.cfcEvent.data.filename;
writeLog(
file = "file-watcher",
type = "information",
text = "File #arguments.cfcEvent.data.type#: #fullPath#"
);
processNewFile(fullPath, getFileFromPath(fullPath));
}
public void function onChange(required struct cfcEvent) {
writeLog(file = "file-watcher", text = "File CHANGE: #arguments.cfcEvent.data.filename#");
}
public void function onDelete(required struct cfcEvent) {
writeLog(file = "file-watcher", text = "File DELETE: #arguments.cfcEvent.data.filename#");
}
/**
* Process newly added files
*/
private void function processNewFile(
required string fullPath,
required string filename
) {
try {
// Read file content
var fileContent = fileRead(fullPath);
// Process based on file type
if (findNoCase(".csv", arguments.filename)) {
processCSVFile(fileContent, arguments.filename);
}
else if (findNoCase(".xml", arguments.filename)) {
processXMLFile(fileContent, arguments.filename);
}
// Archive processed file
archiveFile(fullPath);
} catch (any e) {
writeLog(
file = "file-watcher",
type = "error",
text = "Error processing #arguments.filename#: #e.message#"
);
// Move to error directory
moveToErrorDirectory(fullPath);
}
}
private void function processCSVFile(
required string content,
required string filename
) {
// CSV processing logic
writeLog(
file = "file-watcher",
text = "Processing CSV file: #arguments.filename#"
);
}
private void function processXMLFile(
required string content,
required string filename
) {
// XML processing logic
writeLog(
file = "file-watcher",
text = "Processing XML file: #arguments.filename#"
);
}
private void function archiveFile(required string filePath) {
var archivePath = expandPath("/archives/");
fileMove(arguments.filePath, archivePath);
}
private void function moveToErrorDirectory(required string filePath) {
var errorPath = expandPath("/errors/");
fileMove(arguments.filePath, errorPath);
}
}Programmatic Gateway Management
You can also manage gateway instances programmatically through the Admin API (CFIDE/adminapi/eventgateway.cfc). getGatewayHelper(gatewayID) is a different function: it returns a helper object for one gateway and does not list, start, or stop instances.
// Log in to the Admin API first
adminObj = createObject("component", "CFIDE.adminapi.administrator");
adminObj.login(adminPassword);
gw = createObject("component", "CFIDE.adminapi.eventgateway");
// List gateway instances
writeDump(gw.getGatewayInstances());
// Check one instance's status (returns true/false for started/stopped)
writeDump(gw.getGatewayInstanceStatus("SMS_Notifications"));
// Start, stop, or restart an instance
gw.startGatewayInstance("SMS_Notifications");
gw.stopGatewayInstance("SMS_Notifications");
gw.restartGatewayInstance("SMS_Notifications");
// Send an SMS message via a gateway instance
msgData = {
"command": "submit",
"destAddress": "5555551234",
"shortMessage": "Hello from ColdFusion!"
};
sendGatewayMessage("SMS_Notifications", msgData);Common Issues & Solutions
Gateway Fails to Start
- Check eventgateway.log for error messages
- Verify CFC path is correct and CFC file exists
- Ensure configuration file path is valid
- Check that required methods exist in listener CFC
- Verify external service connectivity (for SMS, IM gateways)
- Confirm file permissions on configuration files
Events Not Being Processed
- Verify gateway status is "Running" not just "Started"
- Check that the listener method the gateway calls (for example
onIncomingMessage(), oronAdd()for DirectoryWatcher) exists in the CFC - Review method signature matches gateway type requirements
- Add logging inside CFC to verify method is being called
- Restart gateway after CFC changes
- Check for errors in exception.log
Configuration Changes Not Taking Effect
- Restart the gateway instance (configuration is loaded at startup)
- For CFC changes, clear template cache or restart gateway
- Verify you modified the correct configuration file
- Check file permissions allow ColdFusion to read the file
- Ensure no syntax errors in configuration file