CommuniGate Pro Integration

Overview

RMP v2.0 integrates deeply with CommuniGate Pro, leveraging its powerful messaging, calendaring, and collaboration features. The integration uses two primary protocols:

XIMSS (XML Interface to Messaging, Scheduling and Signaling) - For real-time operations
CLI (Command Line Interface) - For administrative tasks

Key Points:

Direct connection to CommuniGate Pro - no middleware required
Real-time calendar and resource management
Multi-domain support for SaaS deployments
Persistent connection pooling for performance

Architecture

RMP v2.0 uses a multi-layered architecture for CommuniGate Pro integration:

Connection Flow

RMP v2.0 API Server
    ├── XIMSSService
    │   ├── Port 8100 (HTTP/Clear text)
    │   ├── Port 9100 (SSL/TLS encrypted)
    │   ├── HTTP XIMSS Authentication
    │   ├── Calendar Operations
    │   ├── Contact Management
    │   └── Free/Busy Queries
    │
    └── CLIService (Port 106)
        ├── Account Management
        ├── Domain Operations
        ├── Resource Creation
        └── System Configuration

Domain Structure

Domain Type	Pattern	Purpose
Main Domain	[your-domain]	Primary user accounts
Resource Subdomain	*.resources.[your-domain]	Resource accounts
Conference Rooms	confroom.resources.[your-domain]	Meeting rooms
Parking	parking.resources.[your-domain]	Parking spaces
Vehicles	vehicles.resources.[your-domain]	Company vehicles

XIMSS Protocol

XIMSS is the primary protocol for real-time operations in RMP v2.0.

Connection Ports

XIMSS Access Points:

Port 8100 - HTTP/Clear text XIMSS (default for development)
Port 9100 - SSL/TLS encrypted XIMSS (recommended for production)

Authentication

HTTP-based XIMSS login (both ports support the same authentication):

// XIMSS Login Request (Clear text - Port 8100)
POST http://[your-domain]:8100/XIMSSLogin/?errorAsXML=1

// XIMSS Login Request (SSL/TLS - Port 9100)
POST https://[your-domain]:9100/XIMSSLogin/?errorAsXML=1
Content-Type: application/x-www-form-urlencoded

userName=user@domain.com&password=userpassword

// Response
{
    "sessionId": "1-abc123-xyz789",
    "userName": "user",
    "domain": "domain.com",
    "realName": "User Name"
}

Session Commands

After authentication, send XML commands using the session ID:

// Calendar Open
<XIMSS>
  <calendarOpen id="req-1" 
                calendar="Calendar" 
                mailbox="user@domain.com/Calendar"/>
</XIMSS>

// Find Events
<XIMSS>
  <findEvents id="req-2"
              calendar="Calendar"
              timeFrom="20250821T000000"
              timeTill="20250822T000000"/>
</XIMSS>

// Free/Busy Query
<XIMSS>
  <freeBusyRead id="req-3"
                peer="resource@confroom.resources.domain.com"
                timeFrom="20250821T090000"
                timeTill="20250821T170000"/>
</XIMSS>

Calendar Publishing

Create calendar events using iCalendar XML format:

<XIMSS>
  <calendarPublish id="req-4" calendar="Calendar">
    <iCalendar xmlns="urn:ietf:params:xml:ns:xcal">
      <vCalendar method="PUBLISH" prodid="RMP v2.0" version="2.0">
        <vevent>
          <uid>RMP-1755185014489-5c56vwz1m</uid>
          <summary>Team Meeting</summary>
          <dtstart>20250822T140000</dtstart>
          <dtend>20250822T150000</dtend>
          <location>Conference Room 01</location>
          <organizer>MAILTO:organizer@domain.com</organizer>
          <attendee partstat="ACCEPTED" role="REQ-PARTICIPANT">
            MAILTO:user@domain.com
          </attendee>
          <attendee partstat="ACCEPTED" role="NON-PARTICIPANT" cutype="RESOURCE">
            MAILTO:room-01@confroom.resources.domain.com
          </attendee>
          <transp>OPAQUE</transp>
          <busystatus>BUSY</busystatus>
        </vevent>
      </vCalendar>
    </iCalendar>
  </calendarPublish>
</XIMSS>

Important: Always include both <transp>OPAQUE</transp> and <busystatus>BUSY</busystatus> for events to appear in free/busy queries.

CLI Protocol

CLI is used for administrative operations that require domain administrator privileges.

Common CLI Commands

# List domain objects
LISTDOMAINOBJECTS "[your-domain]" 1000 ACCOUNTS

# Create resource account
CREATEACCOUNT "room-01@confroom.resources.[your-domain]" {
  Password="SecurePass123";
  RealName="Conference Room 01";
  ServiceClass="Resource";
}

# Create calendar mailbox
CREATEMAILBOX "room-01@confroom.resources.[your-domain]" "Calendar"
SETMAILBOXCLASS "room-01@confroom.resources.[your-domain]" "Calendar" "IPF.Appointment"

# Get account settings
GETACCOUNTEFFECTIVESETTINGS "room-01@confroom.resources.[your-domain]"

# Update account settings
UPDATEACCOUNTSETTINGS "room-01@confroom.resources.[your-domain]" {
  AutoAccept="YES";
  ReplyAddress="noreply@domain.com";
}

Domain Services Configuration

Enable required services for resource domains:

# Enable all services for resource domain
UPDATEDOMAINSETTINGS "confroom.resources.[your-domain]" {
  DomainAccessModes=(Mail,Signal,TLS,POP,IMAP,MAPI,AirSync,
                     SIP,XMPP,WebMail,XIMSS,FTP,ACAP,PWD,
                     LDAP,RADIUS,S/MIME,WebCAL,WebSite,PBX,HTTP);
}

Authentication Patterns

Two-Layer Authentication

RMP v2.0 implements a two-layer authentication system:

Gatekeeper Database - Check if user is allowed to access the system
CommuniGate Pro - Authenticate against the messaging server

// Step 1: Check Gatekeeper Database
const gatekeeperUser = await db.query(
    'SELECT * FROM gatekeeper_users WHERE email = $1',
    [email]
);

if (!gatekeeperUser || !bcrypt.compareSync(password, gatekeeperUser.password_hash)) {
    throw new Error('Not authorized in gatekeeper');
}

// Step 2: Authenticate with CommuniGate Pro
const cgproSession = await XIMSSService.authenticate(
    email,
    cgpro_password || password,
    gatekeeperUser.cgpro_domain
);

// Step 3: Generate JWT with both contexts
const token = jwt.sign({
    email: email,
    gatekeeper_role: gatekeeperUser.role,
    cgpro_session: cgproSession.sessionId,
    cgpro_domain: gatekeeperUser.cgpro_domain
}, JWT_SECRET);

Calendar Operations

Calendar Access Patterns

Admin Cross-Account Access: Admin users MUST use tilde prefix (~) for accessing other users' calendars.

// Admin accessing another user's calendar
const isAdmin = user.role === 'admin' || user.role === 'super_admin';
const isOwnCalendar = accountId.split('@')[0] === currentUser;

let calendarPath;
if (isAdmin && !isOwnCalendar) {
    // MUST use tilde prefix for cross-account access
    calendarPath = `~${accountId}/Calendar`;
} else {
    // Standard path for own calendar
    calendarPath = `${accountId}/Calendar`;
}

Working Calendar Pattern

For complex meeting planning with multiple participants:

// Initialize working calendar
const workingCalendar = new WorkingCalendarService(ximssService);

// Load all participant calendars
await workingCalendar.initializeWithParticipants(
    resources,  // Array of resource emails
    users,      // Array of user emails
    dateRange   // { start: Date, end: Date }
);

// Check availability
const availability = workingCalendar.checkTimeslotAvailability(
    startTime,
    endTime
);

// Get busy participants
const busyParticipants = workingCalendar.getBusyParticipants(
    startTime,
    endTime
);

// Find next available slot
const nextSlot = await workingCalendar.findAvailableSlots(
    duration,    // Meeting duration in minutes
    constraints  // { excludeWeekends: true, morningOnly: false }
);

🆕 Delegate Rights & Event Management

New Documentation Available! Comprehensive guide on calendar delegate rights and event modification.

RMP v2.0 uses CommuniGate Pro's delegate rights system for cross-account calendar management. This enables powerful features like:

Key Features

Cross-Account Calendar Access - Write events directly to other users' calendars
all_events Organizer Pattern - Centralized event management with minimal delegate complexity
Event Modification Service - Users can modify their own events even when organized by system account
Mixed Mode Booking - Resources always direct write, users can receive invitations

Quick Example: Granting Delegate Rights

# Grant all_events delegate rights to a user's calendar
SETMAILBOXACL "user@domain" MAILBOX Calendar {all_events@domain=lrswipkxtea;}

# ACL Rights explained:
# l = List, r = Read, s = Seen, w = Write flags
# i = Insert, p = Post, k = Create, x = Delete mailbox
# t = Delete messages, e = Expunge, a = Administer

The all_events Pattern

Instead of every user needing delegate rights to every other calendar, we use a system account:

// Event created with all_events as organizer
<organizer CN="System Calendar">MAILTO:all_events@domain</organizer>
<X-RMP-ACTUAL-ORGANIZER>actualuser@domain</X-RMP-ACTUAL-ORGANIZER>

Benefits:

All events visible in central calendar
Minimal delegate rights management
Users can still modify their own events
Supports both direct write and invitation modes

Event Modification API

// Update an event (checks permissions automatically)
PUT /api/v2/bookings/:bookingId
{
    "title": "Updated Title",
    "start": "2025-09-01T14:00:00Z",
    "end": "2025-09-01T15:00:00Z",
    "attendees": ["user1@domain", "user2@domain"]
}

// Cancel an event
DELETE /api/v2/bookings/:bookingId
{
    "reason": "Schedule conflict"
}

View Full Documentation View Source Code

Contact Management

Detecting Contact Folders

Critical: The mailboxList command with filter: '*' only returns mail folders, NOT contact folders. You must use mailboxClass: 'IPF.Contact'.

<XIMSS>
  <mailboxList id="req-1" 
               filter="*" 
               mailboxClass="IPF.Contact"/>
</XIMSS>

// Response
<XIMSS>
  <mailbox name="Contacts" class="IPF.Contact"/>
  <mailbox name="AddressBook2" class="IPF.Contact"/>
  <response id="req-1"/>
</XIMSS>

Contact Groups (vCardGroup)

Contact groups are identified by specific patterns:

// Detect contact groups
function isContactGroup(contact) {
    const fromField = contact.From || '';
    const toField = contact.To || '';
    
    return (fromField.startsWith('[') && fromField.endsWith(']')) ||
           (toField === 'GROUP');
}

// vCardGroup XML structure
<vCardGroup>
  <FN><VALUE>Development Team</VALUE></FN>
  <MEMBER><VALUE>developer1@domain.com</VALUE></MEMBER>
  <MEMBER><VALUE>developer2@domain.com</VALUE></MEMBER>
  <NOTE><VALUE>Core development team members</VALUE></NOTE>
</vCardGroup>

Resource Accounts

Resource Recognition

Resources are regular CommuniGate Pro accounts in special subdomains:

// Detect resource accounts
function isResource(email) {
    return email.includes('.resources.');
}

// Resource subdomain patterns
const resourcePatterns = {
    'conference-room': 'confroom.resources.',
    'parking-space': 'parking.resources.',
    'company-vehicle': 'vehicles.resources.',
    'equipment': 'equipment.resources.',
    'catering-service': 'catering.resources.'
};

Resource Auto-Accept

Resources automatically accept bookings when configured properly:

// In calendar events, mark resources with:
<attendee partstat="ACCEPTED" 
          role="NON-PARTICIPANT" 
          cutype="RESOURCE">
  MAILTO:room-01@confroom.resources.domain.com
</attendee>

// Use METHOD:PUBLISH for direct calendar writes
<vCalendar method="PUBLISH" prodid="RMP v2.0" version="2.0">

Troubleshooting

Common Issues and Solutions

Cause: Calendar mailbox not created for the account
Solution: Create the Calendar mailbox:

CREATEMAILBOX "user@domain.com" "Calendar"
SETMAILBOXCLASS "user@domain.com" "Calendar" "IPF.Appointment"

Cause: Missing transp or busystatus fields
Solution: Always include both fields in events:

<transp>OPAQUE</transp>
<busystatus>BUSY</busystatus>

Cause: Subdomain not fully initialized
Solution: Wait a few seconds after creating subdomain accounts, or enable all services:

UPDATEDOMAINSETTINGS "subdomain.resources.domain.com" {
  DomainAccessModes=(Mail,XIMSS,WebCAL,HTTP,...);
}

Cause: Using wrong mailboxList parameters
Solution: Use mailboxClass parameter:

<mailboxList filter="*" mailboxClass="IPF.Contact"/>

Debug Commands

# Check account existence
GETACCOUNTLOCATION "user@domain.com"

# View account settings
GETACCOUNTEFFECTIVESETTINGS "user@domain.com"

# List mailboxes
LISTMAILBOXES "user@domain.com"

# Check domain settings
GETDOMAINEFFECTIVESETTINGS "domain.com"

# View access rights
GETACCOUNTRIGHTSLIST "user@domain.com"

Best Practices

Recommended Practices:

Use connection pooling for XIMSS and CLI connections
Cache calendar data with appropriate TTL (5-30 minutes)
Implement retry logic with exponential backoff
Use batch operations where possible (LISTDOMAINOBJECTS)
Close calendar sessions properly after operations
Handle rate limiting gracefully (CommuniGate Pro has built-in limits)
Use domain namespacing for multi-tenant deployments
Always validate email formats before operations

Contents