secondbrain/CDM_QUICKSTART.md

# 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! 🚀