Add VoiceNotes firmware and CDM customer service SQL project
VoiceNotes is an Arduino sketch for the Waveshare ESP32-C6-LCD-0.85 that records meetings and voice memos to microSD and turns them into notes: - Records 16 kHz mono WAV (up to 4 h) from the ES7210 dual mics, with a boosted preamp and soft-limited digital gain - Transcribes via an OpenAI-compatible speech-to-text API in ~10 min parts cut at quiet points, with retries and resume after failures - Summarizes the transcript with Claude into meeting notes (decisions, action items, topics with timestamps), streamed to and from the card - Copies the notes to Nextcloud over WebDAV - Shows recording/processing state on the 0.85" LCD and the LED ring - Works around the board's SD card failing multi-sector reads Credentials live in VoiceNotes/secrets.h, which is git-ignored; see secrets.example.h. Also adds the Microsoft CDM customer service SQL implementation (DDL, sample data, reporting queries and docs). Its README is renamed to CDM_README.md so the repository README stays at the top level. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ravi Reddy
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
ef38a502d8
commit
3b371cdb28
@@ -0,0 +1,545 @@
|
||||
# CDM Customer Service - Quick Start Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This package contains a complete Microsoft Common Data Model (CDM) implementation for Customer Service applications in SQL Server, including:
|
||||
|
||||
- **26 core database tables** covering all customer service scenarios
|
||||
- **36 performance indexes** optimized for common queries
|
||||
- **4 analytical views** for dashboard and reporting
|
||||
- **20+ reporting and administrative procedures**
|
||||
- **Realistic sample data** for testing
|
||||
- **Comprehensive documentation**
|
||||
|
||||
## Files Included
|
||||
|
||||
### 1. **CDM_CustomerService_DDL.sql**
|
||||
The main database creation script.
|
||||
|
||||
**Contents:**
|
||||
- Database schema and objects creation
|
||||
- 26 tables with complete field definitions
|
||||
- 36 indexes for optimal performance
|
||||
- 4 pre-built views
|
||||
- Sample data (accounts, contracts, cases, activities, etc.)
|
||||
|
||||
**Size:** ~50KB | **Execution Time:** ~30 seconds
|
||||
|
||||
### 2. **CDM_Implementation_Guide.md**
|
||||
Complete technical documentation.
|
||||
|
||||
**Contents:**
|
||||
- Architecture and design patterns
|
||||
- Detailed table descriptions with field definitions
|
||||
- Relationship diagrams (conceptual)
|
||||
- Key design decisions and rationale
|
||||
- Performance recommendations
|
||||
- Security considerations
|
||||
- Common queries and examples
|
||||
- Extension guidelines
|
||||
|
||||
### 3. **CDM_Reporting_Queries.sql**
|
||||
Administrative and reporting tools.
|
||||
|
||||
**Contents:**
|
||||
- 4 dashboard views
|
||||
- 20+ stored procedures for reporting
|
||||
- Data quality validation queries
|
||||
- Maintenance procedures
|
||||
- Monthly/quarterly reports
|
||||
- Executive dashboards
|
||||
|
||||
**Size:** ~25KB
|
||||
|
||||
### 4. **CDM_QUICKSTART.md** (this file)
|
||||
Quick reference guide to get started.
|
||||
|
||||
---
|
||||
|
||||
## Getting Started in 5 Minutes
|
||||
|
||||
### Step 1: Create the Database
|
||||
|
||||
```sql
|
||||
-- Execute the entire CDM_CustomerService_DDL.sql file
|
||||
-- OR run these commands individually:
|
||||
|
||||
-- Create the database (if not exists)
|
||||
CREATE DATABASE CDM_CustomerService;
|
||||
GO
|
||||
|
||||
-- Switch to the new database
|
||||
USE CDM_CustomerService;
|
||||
GO
|
||||
|
||||
-- Run the entire CDM_CustomerService_DDL.sql script
|
||||
-- This creates all tables, indexes, views, and sample data
|
||||
```
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
```sql
|
||||
-- Check if all tables are created
|
||||
SELECT COUNT(*) as TableCount
|
||||
FROM INFORMATION_SCHEMA.TABLES
|
||||
WHERE TABLE_SCHEMA = 'cdm';
|
||||
-- Expected: 26
|
||||
|
||||
-- Check sample data
|
||||
SELECT COUNT(*) FROM cdm.Case; -- Should have 4 cases
|
||||
SELECT COUNT(*) FROM cdm.Account; -- Should have 4 accounts
|
||||
SELECT COUNT(*) FROM cdm.ServiceActivity; -- Should have 3 activities
|
||||
```
|
||||
|
||||
### Step 3: Run Your First Query
|
||||
|
||||
```sql
|
||||
-- View all active cases
|
||||
SELECT * FROM cdm.v_ActiveCasesSummary;
|
||||
|
||||
-- Check executive metrics
|
||||
SELECT * FROM cdm.v_ExecutiveDashboard;
|
||||
|
||||
-- View active contracts
|
||||
SELECT * FROM cdm.v_ContractSummary;
|
||||
```
|
||||
|
||||
### Step 4: Load Reporting Tools (Optional)
|
||||
|
||||
```sql
|
||||
-- Execute CDM_Reporting_Queries.sql to add:
|
||||
-- - Dashboard views
|
||||
-- - Reporting procedures
|
||||
-- - Administrative utilities
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### The Data Model Organizes Around 7 Categories
|
||||
|
||||
```
|
||||
Foundation (4 tables)
|
||||
├── User, Site, Account, Contact
|
||||
|
||||
Service Configuration (5 tables)
|
||||
├── Service, Resource, FacilityEquipment, SchedulingGroup, ResourceSpecification
|
||||
|
||||
Contracts (3 tables)
|
||||
├── Contract, ContractLine, ServiceContractContact
|
||||
|
||||
Entitlements (3 tables)
|
||||
├── Entitlement, EntitlementContact, EntitlementProduct
|
||||
|
||||
Cases (3 tables)
|
||||
├── Case, CaseResolution, ChildIncidentCount
|
||||
|
||||
Activities (2 tables)
|
||||
├── ServiceActivity, ActivityParty
|
||||
|
||||
Other (6 tables)
|
||||
├── KnowledgeArticle, SLAKPIInstance, Task, etc.
|
||||
```
|
||||
|
||||
### Key Relationships
|
||||
|
||||
**Customer Journey:**
|
||||
```
|
||||
Account → Contract → EntitlementContact → Case → ServiceActivity → Task
|
||||
```
|
||||
|
||||
**Service Hierarchy:**
|
||||
```
|
||||
Service → ContractLine → ServiceActivity → Resource
|
||||
```
|
||||
|
||||
**Support Structure:**
|
||||
```
|
||||
Entitlement → EntitlementProduct → Case → KnowledgeArticle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Find Active Cases
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
c.caseNumber,
|
||||
c.title,
|
||||
a.accountName,
|
||||
u.firstName + ' ' + u.lastName AS owner,
|
||||
c.priority,
|
||||
DATEDIFF(DAY, c.createdDate, GETUTCDATE()) AS daysOpen
|
||||
FROM cdm.Case c
|
||||
LEFT JOIN cdm.Account a ON c.accountId = a.accountId
|
||||
LEFT JOIN cdm.[User] u ON c.ownerUserId = u.userId
|
||||
WHERE c.status = 'Active'
|
||||
ORDER BY c.priority DESC, c.createdDate;
|
||||
```
|
||||
|
||||
### Analyze Contract Usage
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
c.contractNumber,
|
||||
s.serviceName,
|
||||
cl.quantityIncluded,
|
||||
cl.quantityUsed,
|
||||
CAST(CAST(cl.quantityUsed AS FLOAT) / CAST(cl.quantityIncluded AS FLOAT) * 100 AS DECIMAL(5,2)) AS utilizationPercent
|
||||
FROM cdm.Contract c
|
||||
JOIN cdm.ContractLine cl ON c.contractId = cl.contractId
|
||||
JOIN cdm.Service s ON cl.serviceId = s.serviceId
|
||||
WHERE c.status = 'Active'
|
||||
ORDER BY utilizationPercent DESC;
|
||||
```
|
||||
|
||||
### View Scheduled Activities
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
FORMAT(sa.startTime, 'yyyy-MM-dd HH:mm') AS scheduledTime,
|
||||
sa.subject,
|
||||
s.serviceName,
|
||||
u.firstName + ' ' + u.lastName AS technician,
|
||||
c.caseNumber,
|
||||
a.accountName
|
||||
FROM cdm.ServiceActivity sa
|
||||
JOIN cdm.Service s ON sa.serviceId = s.serviceId
|
||||
LEFT JOIN cdm.[User] u ON sa.ownerUserId = u.userId
|
||||
LEFT JOIN cdm.Case c ON sa.caseId = c.caseId
|
||||
LEFT JOIN cdm.Account a ON c.accountId = a.accountId
|
||||
WHERE sa.startTime >= GETUTCDATE()
|
||||
ORDER BY sa.startTime;
|
||||
```
|
||||
|
||||
### Check Agent Workload
|
||||
|
||||
```sql
|
||||
EXEC sp_AgentPerformance;
|
||||
-- Shows per-agent: cases owned, active, closed, performance metrics
|
||||
```
|
||||
|
||||
### SLA Compliance Dashboard
|
||||
|
||||
```sql
|
||||
EXEC sp_SLAComplianceReport;
|
||||
-- Shows which SLAs are compliant, warning, or critical
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Model Highlights
|
||||
|
||||
### Case Entity
|
||||
The heart of customer service - tracks issues from creation to resolution.
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| Active | Currently being worked |
|
||||
| Waiting | Waiting for customer response |
|
||||
| Resolved | Fixed, pending close |
|
||||
| Closed | Complete |
|
||||
|
||||
### Contract Entity
|
||||
Defines what services customers are entitled to.
|
||||
|
||||
- **ContractLine**: Individual services within contract with quantity limits
|
||||
- **ServiceContractContact**: Links key contacts to contracts
|
||||
|
||||
### Entitlement Entity
|
||||
Defines support/service access levels for customers.
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| Support | Help/troubleshooting |
|
||||
| Service | Service delivery |
|
||||
| Training | Training programs |
|
||||
|
||||
### Service Activity Entity
|
||||
Tracks actual work performed for cases.
|
||||
|
||||
- Scheduled or completed service work
|
||||
- Links technicians, cases, and services
|
||||
- Tracks time spent and location
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Indexes Included
|
||||
The script creates 36 indexes optimized for:
|
||||
- **Case lookups**: By number, account, owner, status, priority
|
||||
- **Contract queries**: By account, status, date ranges
|
||||
- **Activity scheduling**: By time ranges, status
|
||||
- **User lookups**: By email, user ID
|
||||
|
||||
### Query Best Practices
|
||||
|
||||
1. **Always filter by status when querying cases**
|
||||
```sql
|
||||
WHERE c.status IN ('Active', 'Waiting')
|
||||
```
|
||||
|
||||
2. **Use date filters for large tables**
|
||||
```sql
|
||||
WHERE c.createdDate >= DATEADD(MONTH, -3, GETUTCDATE())
|
||||
```
|
||||
|
||||
3. **Prefer indexed fields in WHERE clauses**
|
||||
- Indexed: status, priority, ownerUserId, createdDate
|
||||
- Use these for filtering first
|
||||
|
||||
4. **Archive old data regularly**
|
||||
```sql
|
||||
EXEC sp_ArchiveOldCases @YearsOld = 2;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Extending the Model
|
||||
|
||||
### Add a Custom Field
|
||||
|
||||
```sql
|
||||
-- Create extension table
|
||||
CREATE TABLE cdm.Case_CustomFields (
|
||||
customFieldId UNIQUEIDENTIFIER PRIMARY KEY DEFAULT NEWID(),
|
||||
caseId UNIQUEIDENTIFIER NOT NULL,
|
||||
clientReference NVARCHAR(100),
|
||||
internalNotes NVARCHAR(MAX),
|
||||
createdOn DATETIME2(7) DEFAULT GETUTCDATE(),
|
||||
FOREIGN KEY (caseId) REFERENCES cdm.Case(caseId)
|
||||
);
|
||||
|
||||
-- Add index
|
||||
CREATE NONCLUSTERED INDEX IX_Case_CustomFields_CaseId
|
||||
ON cdm.Case_CustomFields(caseId);
|
||||
```
|
||||
|
||||
### Add a Reporting View
|
||||
|
||||
```sql
|
||||
CREATE VIEW cdm.v_CustomDashboard AS
|
||||
SELECT
|
||||
c.caseNumber,
|
||||
cf.clientReference,
|
||||
c.priority,
|
||||
c.status
|
||||
FROM cdm.Case c
|
||||
LEFT JOIN cdm.Case_CustomFields cf ON c.caseId = cf.caseId;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sample Data
|
||||
|
||||
The script includes realistic sample data:
|
||||
|
||||
| Entity | Count | Purpose |
|
||||
|--------|-------|---------|
|
||||
| Users | 5 | Support staff |
|
||||
| Sites | 3 | Locations |
|
||||
| Accounts | 4 | Customers |
|
||||
| Contacts | 5 | Customer contacts |
|
||||
| Contracts | 3 | Active contracts |
|
||||
| Cases | 4 | Various scenarios |
|
||||
| ServiceActivities | 3 | Scheduled work |
|
||||
| Tasks | 4 | Work items |
|
||||
| KnowledgeArticles | 4 | Help resources |
|
||||
| SLA KPIs | 4 | Performance tracking |
|
||||
|
||||
### Use Sample Data For:
|
||||
- ✅ Testing queries
|
||||
- ✅ Learning the model
|
||||
- ✅ Developing reports
|
||||
- ✅ Training staff
|
||||
|
||||
### To Remove Sample Data:
|
||||
```sql
|
||||
DELETE FROM cdm.Case WHERE isActive = 1;
|
||||
DELETE FROM cdm.Account WHERE accountName IN ('Acme Corporation', 'TechVision Inc', 'Global Services Ltd', 'StartupX');
|
||||
-- Cascade will delete related records
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Views
|
||||
|
||||
### 1. v_ActiveCasesSummary
|
||||
All active and waiting cases with key info.
|
||||
|
||||
```sql
|
||||
SELECT * FROM cdm.v_ActiveCasesSummary
|
||||
WHERE priority = 'High';
|
||||
```
|
||||
|
||||
### 2. v_ContractSummary
|
||||
Overview of all contracts and their status.
|
||||
|
||||
```sql
|
||||
SELECT * FROM cdm.v_ContractSummary
|
||||
WHERE status = 'Active';
|
||||
```
|
||||
|
||||
### 3. v_CaseServiceActivity
|
||||
Cases linked with scheduled service work.
|
||||
|
||||
```sql
|
||||
SELECT * FROM cdm.v_CaseServiceActivity
|
||||
WHERE status = 'Scheduled';
|
||||
```
|
||||
|
||||
### 4. v_CustomerSupportStatus
|
||||
Customer metrics across all cases and entitlements.
|
||||
|
||||
```sql
|
||||
SELECT * FROM cdm.v_CustomerSupportStatus
|
||||
ORDER BY activeCases DESC;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Procedures
|
||||
|
||||
### Reporting
|
||||
- `sp_CaseVolumeByPriority` - Cases by priority
|
||||
- `sp_CustomerSatisfactionAnalysis` - Metrics per customer
|
||||
- `sp_SLAComplianceReport` - SLA tracking
|
||||
- `sp_MonthlyActivityReport` - Monthly summary
|
||||
- `sp_CustomerRevenueAnalysis` - Revenue per customer
|
||||
- `sp_KnowledgeArticleEffectiveness` - KB article usage
|
||||
|
||||
### Administration
|
||||
- `sp_CloseResolvedCases` - Auto-close old resolved cases
|
||||
- `sp_ArchiveOldCases` - Archive historical cases
|
||||
- `sp_DeactivateExpiredContracts` - Expire old contracts
|
||||
- `sp_UpdateEntitlementStatus` - Update entitlement expirations
|
||||
- `sp_ContractRenewalAlerts` - Alert on upcoming renewals
|
||||
|
||||
### Data Quality
|
||||
- `sp_CasesWithMissingData` - Find incomplete cases
|
||||
- `sp_FindOrphanedRecords` - Find orphaned records
|
||||
- `sp_UpdateCaseOverdueStatus` - Find overdue cases
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Schedule
|
||||
|
||||
### Daily
|
||||
```sql
|
||||
-- Check for overdue cases
|
||||
EXEC sp_UpdateCaseOverdueStatus @ThresholdDays = 30;
|
||||
```
|
||||
|
||||
### Weekly
|
||||
```sql
|
||||
-- Update case statuses
|
||||
EXEC sp_SLAComplianceReport;
|
||||
```
|
||||
|
||||
### Monthly
|
||||
```sql
|
||||
-- Run monthly activity report
|
||||
EXEC sp_MonthlyActivityReport @Year = 2024, @Month = 9;
|
||||
|
||||
-- Generate customer satisfaction analysis
|
||||
EXEC sp_CustomerSatisfactionAnalysis @Months = 1;
|
||||
|
||||
-- Check data quality
|
||||
EXEC sp_CasesWithMissingData;
|
||||
```
|
||||
|
||||
### Quarterly
|
||||
```sql
|
||||
-- Review contract renewals
|
||||
EXEC sp_ContractRenewalAlerts @DaysUntilExpiry = 90;
|
||||
|
||||
-- Resource utilization report
|
||||
EXEC sp_ResourceUtilizationReport @Days = 90;
|
||||
```
|
||||
|
||||
### Annually
|
||||
```sql
|
||||
-- Archive old cases
|
||||
EXEC sp_ArchiveOldCases @YearsOld = 2;
|
||||
|
||||
-- Revenue analysis
|
||||
EXEC sp_CustomerRevenueAnalysis;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Script Won't Run
|
||||
- **Check**: Ensure you're using SQL Server 2016 or later
|
||||
- **Check**: You have CREATE DATABASE permission
|
||||
- **Check**: No syntax errors in the script
|
||||
|
||||
### Missing Sample Data
|
||||
- **Cause**: Script ran but data didn't load
|
||||
- **Fix**: Check for constraint violations in the output
|
||||
- **Fix**: Re-run just the SAMPLE DATA section
|
||||
|
||||
### Performance Issues
|
||||
- **Check**: Indexes are created - verify with:
|
||||
```sql
|
||||
SELECT COUNT(*) FROM sys.indexes
|
||||
WHERE object_id = OBJECT_ID('cdm.Case');
|
||||
-- Should be more than 10
|
||||
```
|
||||
|
||||
- **Check**: Statistics are updated:
|
||||
```sql
|
||||
UPDATE STATISTICS cdm.Case;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support Resources
|
||||
|
||||
- **Microsoft CDM Docs**: https://github.com/microsoft/CDM
|
||||
- **SQL Server Docs**: https://learn.microsoft.com/sql/
|
||||
- **Performance Tuning**: Query Store analysis
|
||||
- **Sample Data**: Fully commented in CDM_CustomerService_DDL.sql
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ **Create the database** using CDM_CustomerService_DDL.sql
|
||||
2. ✅ **Review the structure** with CDM_Implementation_Guide.md
|
||||
3. ✅ **Add reporting tools** using CDM_Reporting_Queries.sql
|
||||
4. ✅ **Customize for your business** following the extension guidelines
|
||||
5. ✅ **Load your data** using migration scripts
|
||||
|
||||
---
|
||||
|
||||
## Version Information
|
||||
|
||||
- **Version**: 1.0
|
||||
- **Release Date**: 2026-09-23
|
||||
- **SQL Server**: 2016 and later
|
||||
- **Tables**: 26
|
||||
- **Views**: 4
|
||||
- **Procedures**: 20+
|
||||
- **Indexes**: 36
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
You now have a production-ready implementation of the Microsoft Common Data Model for Customer Service. Use this to:
|
||||
|
||||
- ✅ Track customer issues (Cases)
|
||||
- ✅ Manage service contracts and entitlements
|
||||
- ✅ Schedule technician work (ServiceActivities)
|
||||
- ✅ Monitor SLA compliance
|
||||
- ✅ Analyze customer satisfaction
|
||||
- ✅ Report on business metrics
|
||||
|
||||
Happy implementing! 🚀
|
||||
|
||||
Reference in New Issue
Block a user