Table of Contents

Deactivate Referrals from Status Value

Map legacy status values to current referral status codes

Overview

The Deactivate Referrals from Status operation processes referrals that have been migrated from legacy systems and updates their status codes based on the mag_statusvalue field. This ensures referrals have the correct state (Active/Inactive) and status code in the new system.

The operation:

  • Reads mag_statusvalue text field from migrated data
  • Maps legacy status values to current Dataverse status codes
  • Updates statecode (Active/Inactive) and statuscode fields
  • Handles exit reasons when closing referrals
  • Uses parallel processing for high performance

When to Use This Operation

Use This Operation When:

✅ After data migration from legacy systems with different status models
✅ Referrals have mag_statusvalue populated but incorrect statecode/statuscode
✅ You need to bulk-update referral statuses based on text values
✅ Converting from text-based status to option set-based status
✅ Standardising referral states across migrated data

Don't Use This Operation When:

❌ Referrals don't have mag_statusvalue populated
❌ Referrals already have correct statecode and statuscode
❌ You need to update individual referral statuses (use UI or API)
❌ Status values don't match the expected mapping

Quick Start

Example 1: Preview Status Updates

Test to see how many referrals will be updated and what status codes will be applied:

.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --DeactiveReferralFromStatusValue `
  --EnvironmentUrl https://myorg.crm6.dynamics.com `
  --ClientId a1b2c3d4-e5f6-7890-1234-567890abcdef `
  --Secret YourClientSecretHere `
  --PreviewMode

Expected Output:

[2024-11-17 16:20:15.123] Starting referral status update in PREVIEW MODE...
[2024-11-17 16:20:15.456] Counting referrals with status values...
[2024-11-17 16:20:18.789] Found 12,450 referrals to process
[2024-11-17 16:20:19.012] PREVIEW: Status breakdown:
  - "Admitted" → Active (809730002): 8,200 referrals
  - "Approval Required" → Entered (809730008): 1,850 referrals
  - "Pre-admitted" → Entered (809730008): 680 referrals
  - "Referral Approved" → Entered (809730008): 420 referrals
  - "Discharged" → Provider Declined (809730001): 980 referrals
  - "Referral Cancelled" → Client Non-Contact (809730006): 250 referrals
  - "Referral Declined" → Provider Declined (809730001): 70 referrals
[2024-11-17 16:20:19.345] Preview completed. No changes made.

Example 2: Update Referral Statuses

After verifying the preview, run for real:

.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --DeactiveReferralFromStatusValue `
  --EnvironmentUrl https://myorg.crm6.dynamics.com `
  --ClientId a1b2c3d4-e5f6-7890-1234-567890abcdef `
  --Secret YourClientSecretHere

Expected Output:

[2024-11-17 16:25:22.123] Starting referral status update...
[2024-11-17 16:25:22.456] Found 12,450 referrals to process
[2024-11-17 16:25:23.789] Creating pool of 50 service clients...
[2024-11-17 16:25:25.012] Processing referrals in parallel...
[2024-11-17 16:25:45.345] Progress: 5,000/12,450 (40.2%)
[2024-11-17 16:26:12.678] Progress: 10,000/12,450 (80.3%)
[2024-11-17 16:26:28.901] Progress: 12,450/12,450 (100.0%)
[2024-11-17 16:26:29.234] Referral status update completed
[2024-11-17 16:26:29.567] Total referrals processed: 12,450
[2024-11-17 16:26:29.890] Total time: 67.0 seconds
[2024-11-17 16:26:29.123] Average throughput: 185 referrals/sec

How It Works

Status Value Mapping

The operation maps legacy status values to Navigator Platform status codes:

mag_statusvalue Target State Target Status Code Status Code Value Notes
"Admitted" Active (0) Active 809730002 Referral is actively being serviced
"Approval Required" Active (0) Entered 809730008 Awaiting approval
"Pre-admitted" Active (0) Entered 809730008 Pre-admission stage
"Referral Approved" Active (0) Entered 809730008 Approved but not yet admitted
"Discharged" Inactive (1) Varies by mag_reasonforexit See exit mapping Uses mag_reasonforexit to determine exact status
"Referral Cancelled" Inactive (1) Client Non-Contact 809730006 Client didn't respond
"Referral Declined" Inactive (1) Provider Declined 809730001 Service provider declined referral

Exit Reason Mapping (for "Discharged")

When mag_statusvalue = "Discharged", the operation checks mag_reasonforexit:

mag_reasonforexit Target Status Code Status Code Value
Contains "Client Non" Client Non-Contact 809730006
Contains "Provider Decl" Provider Declined 809730001
Contains "Complete" Close 809730000
Any other value Close 809730000

Processing Steps

  1. Retrieve Referrals: Queries mag_referral records with non-null mag_statusvalue
  2. For Each Referral:
    • Read mag_statusvalue
    • Determine target statecode and statuscode based on mapping
    • If "Discharged", check mag_reasonforexit for specific exit status
    • Update referral record
  3. Batch Processing: Updates referrals in batches of 10
  4. Parallel Execution: Processes batches across 50 concurrent threads

Parameters

Required Parameters

--DeactiveReferralFromStatusValue

Flag to enable the operation.

Example:

--DeactiveReferralFromStatusValue

--EnvironmentUrl (-e)

The URL of your Dataverse environment.

Example:

--EnvironmentUrl https://myorg.crm6.dynamics.com

--ClientId (-c)

The Azure AD application (client) ID for authentication.

Example:

--ClientId a1b2c3d4-e5f6-7890-1234-567890abcdef

Optional Parameters

--Secret (-s)

The client secret for authentication. If omitted, uses the default secret.

Example:

--Secret YourClientSecretHere

--PreviewMode

Run in preview mode without updating referrals. Shows what would be done.

Example:

--PreviewMode
Tip

Always run with --PreviewMode first to verify the status mapping is correct.

Real-World Scenarios

Scenario 1: Post-Migration Status Standardisation

Situation: You've migrated 10,000 referrals from a legacy system that used text-based status values like "Admitted", "Discharged", etc. You need to convert these to the Navigator Platform's status codes.

Solution:

# Step 1: Preview to verify mapping
.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --DeactiveReferralFromStatusValue `
  -e https://prod.crm6.dynamics.com `
  -c a1b2c3d4-e5f6-7890-1234-567890abcdef `
  -s $env:DATAVERSE_SECRET `
  --PreviewMode

# Step 2: Review the preview results
$logFile = Get-ChildItem ".\Logs\ParallelProcessing_DeactivateReferralFromStatus_*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Get-Content $logFile | Select-String "PREVIEW: Status breakdown" -Context 0,10

# Step 3: If mapping looks correct, run for real
.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --DeactiveReferralFromStatusValue `
  -e https://prod.crm6.dynamics.com `
  -c a1b2c3d4-e5f6-7890-1234-567890abcdef `
  -s $env:DATAVERSE_SECRET

# Step 4: Verify referral statuses in Power Apps
# Use Advanced Find:
# Entity: Referral
# Filter: Status Value (Is Not Null)
# Check that State Code and Status Code match expectations

Expected Outcome:

  • All "Admitted" referrals → Active state, Active status
  • All "Discharged" referrals → Inactive state, appropriate exit status
  • All "Approval Required" referrals → Active state, Entered status
  • Referrals display correct status in views and forms

Scenario 2: Fix Incorrect Status After Partial Migration

Situation: A previous migration attempt updated 5,000 of 10,000 referrals. You need to process only the remaining 5,000.

Solution:

The operation automatically processes all referrals with mag_statusvalue. To process only specific referrals, filter beforehand:

# Option 1: Clear mag_statusvalue for already-processed referrals
# Use Power Apps Advanced Find or bulk edit:
# Entity: Referral
# Filter: Status Value (Is Not Null) AND State Code (Equals Active) AND Status Code (Equals Active)
# Set: mag_statusvalue = null

# Option 2: Run the operation (it's idempotent)
# Referrals with correct status will be updated to the same values (no harm)
.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --DeactiveReferralFromStatusValue `
  -e https://prod.crm6.dynamics.com `
  -c a1b2c3d4-e5f6-7890-1234-567890abcdef `
  -s $env:DATAVERSE_SECRET

Expected Outcome:

  • All 10,000 referrals have correct status codes
  • No duplicates or conflicts
  • mag_statusvalue remains for audit trail

Performance & Scalability

Processing Characteristics

Configuration Value
Max Concurrent Threads 50
Records per Batch 10 referrals
Page Size (Retrieve) 5,000
Preview Mode Limit 100 referrals

Typical Performance

Referrals Estimated Time Throughput
1,000 5-10 seconds 100-200 referrals/sec
5,000 25-50 seconds 100-200 referrals/sec
10,000 50-100 seconds 100-200 referrals/sec
50,000 4-8 minutes 100-200 referrals/sec
Note

Performance depends on network latency, Dataverse throttling, and plugins/workflows on referral update.

Troubleshooting

Issue: "No referrals found to process"

Cause: No referrals have mag_statusvalue populated.

Solution:

  1. Verify referrals exist with status values:
SELECT TOP 10 mag_referralid, mag_statusvalue, statecode, statuscode 
FROM mag_referral 
WHERE mag_statusvalue IS NOT NULL
  1. Ensure data migration populated mag_statusvalue field

Issue: "Unknown status value"

Cause: mag_statusvalue contains a value not in the mapping.

Solution:

  1. Identify unknown status values:
SELECT DISTINCT mag_statusvalue, COUNT(*) AS Count
FROM mag_referral
WHERE mag_statusvalue IS NOT NULL
GROUP BY mag_statusvalue
  1. Update the operation code to handle new status values, or manually update referrals with unknown values

Issue: "Referrals stuck in incorrect status"

Cause: Validation rules, plugins, or workflows preventing status update.

Solution:

  1. Check for validation errors in the log file
  2. Review plugins/workflows on mag_referral entity that might be blocking status changes
  3. Temporarily disable validation rules if safe to do so

Issue: "Some referrals not updated"

Cause: Referrals failed validation or had errors during update.

Solution:

  1. Review log for ERROR messages
  2. Check failed referral IDs
  3. Manually investigate and fix issues with those specific referrals

Output & Logs

Log File Location

Logs\ParallelProcessing_DeactivateReferralFromStatus_2024-11-17_16-25-22-123.log

Log File Contents

Startup Phase:

[2024-11-17 16:25:22.123] Starting referral status update...
[2024-11-17 16:25:22.456] Counting referrals with status values...
[2024-11-17 16:25:23.789] Found 12,450 referrals to process
[2024-11-17 16:25:24.012] Creating pool of 50 service clients...
[2024-11-17 16:25:25.345] Service client pool created successfully

Processing Phase:

[2024-11-17 16:25:26.678] Processing referral: Smith Family Referral (mag_statusvalue: "Admitted")
[2024-11-17 16:25:26.901] Mapping "Admitted" → statecode: 0 (Active), statuscode: 809730002 (Active)
[2024-11-17 16:25:27.234] Processing referral: Jones Family Referral (mag_statusvalue: "Discharged")
[2024-11-17 16:25:27.567] mag_reasonforexit: "Service Complete - Goals Achieved"
[2024-11-17 16:25:27.890] Mapping "Discharged" → statecode: 1 (Inactive), statuscode: 809730000 (Close)
[2024-11-17 16:25:45.456] Progress: 5,000/12,450 (40.2%) - 180 referrals/sec

Completion Phase:

[2024-11-17 16:26:29.234] Referral status update completed
[2024-11-17 16:26:29.567] Total referrals processed: 12,450
[2024-11-17 16:26:29.890] Total time: 67.0 seconds
[2024-11-17 16:26:29.123] Average throughput: 185 referrals/sec
[2024-11-17 16:26:29.456] Status breakdown:
  - Active (809730002): 8,200
  - Entered (809730008): 2,950
  - Close (809730000): 980
  - Client Non-Contact (809730006): 250
  - Provider Declined (809730001): 70
[2024-11-17 16:26:29.789] Successful: 12,450
[2024-11-17 16:26:29.012] Failed: 0

Understanding the Results

Success Indicators:

  • ✅ "Total referrals processed" matches expected count
  • ✅ "Failed: 0"
  • ✅ No ERROR lines in log
  • ✅ Status breakdown matches preview

Warning Signs:

  • ⚠️ "Failed: X" where X > 0 - Review error messages
  • ⚠️ "Unknown status value" - Add mapping or fix data
  • ⚠️ Status breakdown doesn't match preview - Re-run preview

See Also