Calendar Properties

This table defines the structure of the calendar entity, including all properties and their descriptions.

🔹 Core Properties

Property	Type	Required	Description	Example
id	string	Yes	Unique identifier for the calendar	"123e4567-e89b-12d3-a456-426614174000"
name	string	No	Display name of the calendar	"Team Meetings Calendar"
email	string	No	Associated email address	"[email protected]"
type	string	Yes	Type of calendar (agent or asset)	"agent"
canonicalId	string	No	Provider/integration canonical identifier	"cal_12345"
timezone	string	Yes	IANA timezone identifier	"America/New_York"
tags	string[]	No	List of tags	["meetings", "team-a"]
services	array	No	Services associated to this calendar	See ServiceCalendar docs
userGroupId	string	No	UUID of associated user group	"123e4567-e89b-12d3-a456-426614174001"
organizationId	string	No	UUID of the organization	"123e4567-e89b-12d3-a456-426614174000"
extraFields	object	No	Additional custom fields	See example below
createdAt	string	No	ISO datetime when the calendar was created	"2025-05-22T10:30:00Z"
updatedAt	string	No	ISO datetime when the calendar was last updated	"2025-05-22T10:30:00Z"

📋 Calendar Types

Type	Description	Use Case
agent	Calendar for human agents/employees	Staff scheduling, personal calendars
asset	Calendar for resources/equipment	Room bookings, equipment scheduling

🧩 Example Entry

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Sales Team Calendar",
  "timezone": "America/New_York",
  "type": "agent",
  "email": "[email protected]",
  "canonicalId": "cal_12345",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "userGroupId": "123e4567-e89b-12d3-a456-426614174001",
  "tags": ["sales", "team-a", "west-region"],
  "extraFields": {
    "department": "Sales",
    "location": "West Wing",
    "capacity": 10,
    "features": ["video-conf", "whiteboard"]
  }
}

🔍 Interpretation

• Each calendar must have a unique identifier (id)
• External system identifiers are mapped internally; the public id is stable
• Timezone settings affect all calendar operations
• Calendar type determines its usage and restrictions
• Tags provide flexible organization and filtering
• Extra fields allow custom data storage
• Organization and group associations enable access control

✅ Use Cases

• 👥 Agent Calendars: Personal or team scheduling
• 🏢 Resource Management: Room and equipment booking
• 🌐 Multi-timezone Operations: Global team coordination
• 🔖 Categorization: Using tags for organization
• 🔐 Access Control: Group-based permissions
• 📊 Custom Data: Industry-specific requirements

📘 Notes

• Timezone: Must be valid IANA timezone identifier
• Tags: Maximum 100 characters per tag
• Type: Cannot be changed after creation
• Email: Optional but recommended for notifications
• Groups: Calendars can belong to one group at a time
• Extra Fields: Flexible JSON structure for custom data

🔒 Validation Rules

1. Identifiers

   • UUID format for id, organizationId, userGroupId
   • Unique constraints within organization

2. Type Validation

   • Must be either "agent" or "asset"

3. Tag Rules

   • Maximum 100 characters per tag
   • No duplicate tags allowed
   • Case-sensitive comparison

4. Extra Fields

   • Must be valid JSON object