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

Retrieve Referrals: Queries mag_referral records with non-null mag_statusvalue
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
Batch Processing: Updates referrals in batches of 10
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:

Verify referrals exist with status values:

SELECT TOP 10 mag_referralid, mag_statusvalue, statecode, statuscode 
FROM mag_referral 
WHERE mag_statusvalue IS NOT NULL

Ensure data migration populated mag_statusvalue field

Issue: "Unknown status value"

Cause: mag_statusvalue contains a value not in the mapping.

Solution:

Identify unknown status values:

SELECT DISTINCT mag_statusvalue, COUNT(*) AS Count
FROM mag_referral
WHERE mag_statusvalue IS NOT NULL
GROUP BY mag_statusvalue

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:

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

Issue: "Some referrals not updated"

Cause: Referrals failed validation or had errors during update.

Solution:

Review log for ERROR messages
Check failed referral IDs
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

Deactivate Referrals from Status Value

Overview

When to Use This Operation

Use This Operation When:

Don't Use This Operation When:

Quick Start

Example 1: Preview Status Updates

Example 2: Update Referral Statuses

How It Works

Status Value Mapping

Exit Reason Mapping (for "Discharged")

Processing Steps

Parameters

Required Parameters

--DeactiveReferralFromStatusValue

--EnvironmentUrl (-e)

--ClientId (-c)

Optional Parameters

--Secret (-s)

--PreviewMode

Tip

Real-World Scenarios

Scenario 1: Post-Migration Status Standardisation

Scenario 2: Fix Incorrect Status After Partial Migration

Performance & Scalability

Processing Characteristics

Typical Performance

Note

Troubleshooting

Issue: "No referrals found to process"

Issue: "Unknown status value"

Issue: "Referrals stuck in incorrect status"

Issue: "Some referrals not updated"

Output & Logs

Log File Location

Log File Contents

Understanding the Results

See Also

`--DeactiveReferralFromStatusValue`

`--EnvironmentUrl` (-e)

`--ClientId` (-c)

`--Secret` (-s)

`--PreviewMode`