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

-- 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

-- 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

-- 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)

-- 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

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

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

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

EXEC sp_AgentPerformance;
-- Shows per-agent: cases owned, active, closed, performance metrics

SLA Compliance Dashboard

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

   WHERE c.status IN ('Active', 'Waiting')
   

2. Use date filters for large tables

   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

   EXEC sp_ArchiveOldCases @YearsOld = 2;
   

---

Extending the Model

Add a Custom Field

-- 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

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:

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.

SELECT * FROM cdm.v_ActiveCasesSummary 
WHERE priority = 'High';

2. v_ContractSummary

Overview of all contracts and their status.

SELECT * FROM cdm.v_ContractSummary 
WHERE status = 'Active';

3. v_CaseServiceActivity

Cases linked with scheduled service work.

SELECT * FROM cdm.v_CaseServiceActivity 
WHERE status = 'Scheduled';

4. v_CustomerSupportStatus

Customer metrics across all cases and entitlements.

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

-- Check for overdue cases
EXEC sp_UpdateCaseOverdueStatus @ThresholdDays = 30;

Weekly

-- Update case statuses
EXEC sp_SLAComplianceReport;

Monthly

-- 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

-- Review contract renewals
EXEC sp_ContractRenewalAlerts @DaysUntilExpiry = 90;

-- Resource utilization report
EXEC sp_ResourceUtilizationReport @Days = 90;

Annually

-- 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:

  SELECT COUNT(*) FROM sys.indexes 
  WHERE object_id = OBJECT_ID('cdm.Case');
  -- Should be more than 10
  

• Check: Statistics are updated:

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