Engage Community Member Sync Tool

Synchronize members across Viva Engage communities, Calendar meeting series, and Teams group chats - via a web interface or GitHub Copilot agents.

🎯 What It Does

Source of Truth: Viva Engage community membership
Sync Direction: From Engage → Calendar and Teams Chat

In Engage	In Calendar	In Chat	Action
✅	❌	❌	Add to Both
✅	❌	✅	Add to Calendar
✅	✅	❌	Add to Chat
❌	✅	✅	No action (add-only mode)

---

🖥️ Web Interface

A full Next.js web application for visual member sync operations.

Features

• Microsoft Login - Authenticate with your M365 account via MSAL
• Source Selector - Pick your Engage community, Calendar meeting, and Teams chat
• Comparison Table - See all members with their sync status across sources
• Sync Preview - Dry run mode shows exactly what will change before you confirm
• Dark/Light Theme - Toggle between themes
• Add-Only Mode - Never removes members, only adds missing ones

Running the Web App

# Install dependencies
npm install

# Set environment variables
cp .env.local.example .env.local
# Edit .env.local with your Azure App Registration

# Start development server
npm run dev

Open http://localhost:3000

Screenshots

┌────────────────────────────────────────────────────────────┐
│  🔥 One Sync to Rule Them All              🌙  [Sign In]  │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│  │ 📢 Community    │ │ 📅 Calendar     │ │ 💬 Chat      │ │
│  │ All The Vibes   │ │ Weekly Standup  │ │ Team Chat    │ │
│  └─────────────────┘ └─────────────────┘ └──────────────┘ │
│                                                            │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Member          │ Engage │ Calendar │ Chat │ Action │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │ alice@co...     │   ✅   │    ❌    │  ✅  │  +Cal  │  │
│  │ bob@cont...     │   ✅   │    ✅    │  ❌  │ +Chat  │  │
│  │ carol@co...     │   ✅   │    ❌    │  ❌  │ +Both  │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                            │
│                          [Preview Sync]  [Execute Sync]    │
└────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology
Framework	Next.js 14+ (App Router)
Language	TypeScript
Styling	Tailwind CSS + shadcn/ui
Auth	MSAL React (@azure/msal-react)
API Client	@microsoft/microsoft-graph-client

Environment Variables

NEXT_PUBLIC_AZURE_CLIENT_ID=your-app-registration-client-id
NEXT_PUBLIC_AZURE_TENANT_ID=your-tenant-id

---

🤖 Copilot Agents

Alternatively, use GitHub Copilot Chat agents for command-line style operations.

User Query
    │
    ├─── @sync ────────────► Sync Agent
    │                            │
    │                       Graph API calls
    │                       (members, attendees, chat)
    │                            │
    │                       ◄────┴──── runSubagent("research")
    │
    └─── @research ────────► Research Agent
                                 │
                            Work IQ queries
                            (content, analytics, discovery)
                                 │
                            ◄────┴──── runSubagent("sync")

🚀 Quick Start

Prerequisites

• GitHub Copilot subscription
• VS Code with Copilot Chat extension
• Work IQ MCP configured (for @research)
• Azure App Registration with Graph API permissions (for @sync)

Usage

In VS Code Copilot Chat:

# Sync operations
@sync List members of the "All The Vibes" community
@sync Compare community with the weekly standup attendees
@sync Add missing members to the calendar meeting

# Research operations
@research What's trending in the AI community this week?
@research Who are the top contributors?
@research Generate a weekly engagement report

📁 Project Structure

.github/
├── agents/
│   ├── sync.md              # Member sync via Graph API
│   └── research.md          # Content discovery via Work IQ
├── skills/
│   ├── graph-api/           # Graph API patterns
│   ├── m365-integration/    # M365 SDK patterns  
│   └── engage-management/   # Engage community patterns
├── hooks/
│   ├── engage-sync.json     # Hook configuration
│   └── scripts/             # Validation & logging
└── copilot-instructions.md  # Project context

app/                         # Next.js web UI
components/                  # React components
lib/                         # Graph client, utils

🔧 Agents

@sync - Member Sync Agent

Purpose: Synchronize members across Engage, Calendar, and Teams Chat

Handles:

• List community members (Graph API)
• Get calendar attendees
• Manage Teams chat members
• Sync operations with dry-run preview

Key Pattern:

// Calendar PATCH replaces ALL attendees
PATCH /me/events/{seriesMasterId}
{ "attendees": [...all existing + new...] }

@research - Discovery Agent

Purpose: Search content and analyze engagement via Work IQ

Handles:

• Search Engage posts and discussions
• Find trending topics
• Identify active contributors
• Generate engagement reports

Key Pattern:

workiq-ask_work_iq({ 
  question: "Who are the most active contributors in [Community]?" 
})

🔐 Permissions

Permission	Purpose	Admin Consent
Community.Read.All	List communities	✅
GroupMember.Read.All	Read members	✅
Calendars.ReadWrite	Update attendees	❌
ChatMember.ReadWrite.All	Manage chat	✅

🔄 Agent Handoffs

Agents automatically hand off to each other based on intent:

If @sync receives...	Action
"what's trending"	→ runSubagent("research")
"top contributors"	→ runSubagent("research")
"summarize activity"	→ runSubagent("research")

If @research receives...	Action
"sync members"	→ runSubagent("sync")
"add to meeting"	→ runSubagent("sync")
"update attendees"	→ runSubagent("sync")

📊 Logging

All tool usage is logged to logs/:

logs/
├── tools.log       # All tool calls with agent context
├── tool-stats.csv  # timestamp, agent, tool, result
├── handoffs.log    # Agent-to-agent handoffs
├── failures.log    # Failed operations
└── session.log     # Session start/end

🛡️ Dry Run Mode

All sync operations run in dry run mode by default. No changes are made until you explicitly confirm.

How It Works

@sync Add missing members to the weekly standup

Step 1: Preview - Agent shows proposed changes:

┌─────────────────────────────────────────────────────────┐
│ DRY RUN PREVIEW - No changes will be made              │
├─────────────────────────────────────────────────────────┤
│ Community: All The Vibes (47 members)                  │
│ Meeting: Weekly Standup (32 attendees)                 │
├─────────────────────────────────────────────────────────┤
│ 📥 ADD to Calendar:                                    │
│   • alice@contoso.com                                  │
│   • bob@contoso.com                                    │
│   • carol@contoso.com                                  │
├─────────────────────────────────────────────────────────┤
│ Total: +3 members to add                               │
└─────────────────────────────────────────────────────────┘

Type "proceed" or "yes" to apply these changes.

Step 2: Confirm - Only after explicit approval:

proceed

Step 3: Execute - Changes are applied and logged.

Why Dry Run?

Risk	Mitigation
Calendar PATCH replaces ALL attendees	Preview shows complete list before overwrite
Wrong meeting/chat selected	Verify target before changes
Rate limiting	Batch operations visible in preview

Note: This tool only ADDS members. It never removes attendees from Calendar or Chat, even if they're not in the Engage community.

Disabling Dry Run

To apply changes immediately (not recommended):

@sync Add members to standup --no-dry-run

🔒 Safety

• Dry run by default - Preview changes before applying
• Explicit confirmation - No modifications without user approval
• Hook validation - Dangerous commands are blocked
• Audit trail - All operations logged

📚 Resources

• Microsoft Graph API
• Viva Engage API
• Work IQ MCP
• GitHub Copilot Agents

📄 License

MIT