Populate Exit for Referral

Automatically link exit activities to referrals and create child exits for additional referrals

Overview

The Populate Exit for Referral operation processes exit activities (mag_exit) and ensures they're properly linked to the correct referrals. It also creates child exit activities for additional (child) referrals that were created via the "Recreate Additional Referrals" operation.

The operation:

Finds exit activities with linked referrals via mag_inboundreferral
Updates the parent referral with exit information (exit date, reason, exited by)
Finds child referrals (where mag_masterreferral points to parent)
Creates new exit activities for each child referral
Populates mag_relationships JSON on all exit activities
Uses parallel processing for high performance

When to Use This Operation

Use This Operation When:

✅ After creating child referrals via --RecreateAdditionalReferrals
✅ Exit activities exist but referrals don't have exit data populated
✅ Parent referrals have exits but child referrals don't
✅ You need to sync exit data from activities to referral records
✅ After data migration where exits and referrals were imported separately

Don't Use This Operation When:

❌ No child referrals exist (no mag_masterreferral relationships)
❌ Exit activities don't have mag_inboundreferral populated
❌ Referrals already have correct exit data
❌ You want to manually manage exits for each referral

Quick Start

Example 1: Preview Exit Population

Test to see how many exits will be created and which referrals will be updated:

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

Expected Output:

[2024-11-17 16:40:15.123] Starting exit population for referrals in PREVIEW MODE...
[2024-11-17 16:40:15.456] Counting exit activities with referrals...
[2024-11-17 16:40:18.789] Found 3,850 parent exit activities
[2024-11-17 16:40:19.012] Analyzing child referrals...
[2024-11-17 16:40:22.345] Found 8,420 child referrals requiring exits
[2024-11-17 16:40:22.678] PREVIEW: Would update 3,850 parent referrals with exit data
[2024-11-17 16:40:22.901] PREVIEW: Would create 8,420 child exit activities
[2024-11-17 16:40:22.234] Preview completed. No changes made.

Example 2: Populate Exits for Referrals

After verifying the preview, run for real:

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

Expected Output:

[2024-11-17 16:45:22.123] Starting exit population for referrals...
[2024-11-17 16:45:22.456] Found 3,850 parent exit activities to process
[2024-11-17 16:45:23.789] Creating pool of 50 service clients...
[2024-11-17 16:45:25.012] Processing exits in parallel...
[2024-11-17 16:45:45.345] Progress: 1,500/3,850 (39.0%)
[2024-11-17 16:46:12.678] Progress: 3,000/3,850 (77.9%)
[2024-11-17 16:46:28.901] Progress: 3,850/3,850 (100.0%)
[2024-11-17 16:46:29.234] Exit population completed
[2024-11-17 16:46:29.567] Total parent exits processed: 3,850
[2024-11-17 16:46:29.890] Total parent referrals updated: 3,850
[2024-11-17 16:46:29.123] Total child exits created: 8,420
[2024-11-17 16:46:29.456] Total time: 67.0 seconds
[2024-11-17 16:46:29.789] Average throughput: 125 exits/sec

How It Works

Processing Steps

Retrieve Parent Exits: Queries mag_exit activities where:
- mag_inboundreferral is not null (exit is linked to a referral)
- Exit activity exists
For Each Parent Exit:
- Retrieve the linked parent referral
- Update parent referral with:
  - mag_exitedby (from exit activity's mag_exitedby)
  - mag_exitdate (from exit activity's mag_exitdate)
  - mag_exitreason (from exit activity's mag_exitreason)
Find Child Referrals:
- Query mag_referral where mag_masterreferral equals parent referral ID
- Retrieve all child referrals
Create Child Exit Activities:
- For each child referral:
  - Create new mag_exit activity
  - Set mag_inboundreferral to child referral ID
  - Copy mag_exitedby, mag_exitdate, mag_exitreason from parent exit
  - Copy mag_familygroupmember from child referral's mag_contact
  - Build mag_relationships JSON with Individual and Referral data
Batch Processing: Creates child exits in batches for efficiency
Parallel Execution: Processes parent exits across 50 concurrent threads

mag_relationships JSON Format

The operation builds this JSON structure for each exit activity:

{
  "Individuals": [
    {"Id": "12345678-1234-1234-1234-123456789012"}
  ],
  "Referrals": [
    {"Id": "23456789-2345-2345-2345-234567890123"}
  ]
}

Field Population for Child Exits

Fields Copied from Parent Exit:

mag_exitedby → Who initiated the exit
mag_exitdate → When the exit occurred
mag_exitreason → Reason for exit

Fields Set from Child Referral:

mag_inboundreferral → Child referral ID
mag_familygroupmember → Child referral's contact (mag_contact)
mag_relationships → JSON with Individual and Referral IDs

Fields Set to Defaults:

statecode → Active (0)
statuscode → Active (809730000)
mag_activitytype → Exit (809730012)

Parameters

Required Parameters

`--PopulateExitForReferral`

Flag to enable the operation.

Example:

--PopulateExitForReferral

`--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 creating exits or updating referrals. Shows what would be done.

Example:

--PreviewMode

Tip

Always run with --PreviewMode first to verify the count of exits to be created.

Real-World Scenarios

Scenario 1: Complete Exit Process After Creating Child Referrals

Situation: You ran --RecreateAdditionalReferrals and created 2,000 child referrals. Now you need to create exit activities for the 500 child referrals whose parent referrals have already been exited.

Solution:

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

# Step 2: Review the preview log
$logFile = Get-ChildItem ".\Logs\ParallelProcessing_PopulateExitForReferral_*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Get-Content $logFile | Select-String "Would create", "Would update"

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

# Step 4: Verify child exits created
# Use Power Apps Advanced Find:
# Entity: Exit
# Filter: Inbound Referral → Master Referral (Is Not Null)

Expected Outcome:

Parent referrals have mag_exitedby, mag_exitdate, mag_exitreason populated
Each child referral has its own exit activity
All exit activities have mag_relationships JSON
Child exits show correct individual and referral links

Scenario 2: Fix Missing Exit Data After Migration

Situation: After data migration, 3,000 exit activities exist and are linked to referrals, but the referral records don't have the exit data fields (mag_exitedby, mag_exitdate, mag_exitreason) populated.

Solution:

# Run the operation to sync exit data to referrals
.\WhanauTahi.Xpm.Tooling.CLI.exe datamanipulation `
  --PopulateExitForReferral `
  -e https://prod.crm6.dynamics.com `
  -c a1b2c3d4-e5f6-7890-1234-567890abcdef `
  -s $env:DATAVERSE_SECRET

# Verify referral exit data populated
# SQL Query or Advanced Find:
# Entity: Referral
# Filter: Exit Date (Is Not Null)
# Verify: Exit Date, Exit Reason, Exited By fields are populated

Expected Outcome:

All parent referrals have exit data fields populated
Exit data matches corresponding exit activities
Child referrals (if any) have their own exit activities created

Scenario 3: Scheduled Nightly Sync

Situation: New exit activities are created throughout the day. You want to automatically sync them to referrals every night.

Solution:

# nightly-exit-sync.ps1
$ErrorActionPreference = "Stop"

$env:CLIENT_SECRET = Get-Secret -Name "DataverseClientSecret"

& "C:\Tools\WhanauTahi.Xpm.Tooling.CLI.exe" datamanipulation `
  --PopulateExitForReferral `
  -e https://prod.crm6.dynamics.com `
  -c a1b2c3d4-e5f6-7890-1234-567890abcdef `
  -s $env:CLIENT_SECRET

# Archive log
$logFile = Get-ChildItem ".\Logs\ParallelProcessing_PopulateExitForReferral_*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Copy-Item $logFile "\\fileserver\logs\exit-sync-$(Get-Date -Format 'yyyy-MM-dd').log"

# Send summary
$summary = Get-Content $logFile | Select-String "Total", "Average throughput"
Send-MailMessage -To "admin@example.com" -Subject "Exit Sync Complete" -Body ($summary -join "`n")

Schedule via Windows Task Scheduler:

Trigger: Daily at 11:30 PM
Action: Run PowerShell script

Performance & Scalability

Processing Characteristics

Configuration	Value
Max Concurrent Threads	50
Records per Batch	10 parent exits
Child Exits per Batch	Variable (depends on child referrals)
Preview Mode Limit	100 parent exits

Typical Performance

Parent Exits	Avg Children/Parent	Total Operations	Estimated Time	Throughput
500	2	1,500	10-20 seconds	75-150 ops/sec
1,000	2	3,000	20-40 seconds	75-150 ops/sec
5,000	2	15,000	100-200 seconds	75-150 ops/sec

Note

"Operations" includes parent referral updates + child exit creations. Performance depends on network latency, Dataverse throttling, and plugins/workflows.

Troubleshooting

Issue: "No parent exits found"

Cause: No exit activities have mag_inboundreferral populated.

Solution:

Verify exits exist with referral links:

SELECT TOP 10 mag_exitid, mag_inboundreferral, mag_exitdate, mag_exitreason 
FROM mag_exit 
WHERE mag_inboundreferral IS NOT NULL

Ensure exit activities are properly linked to referrals

Issue: "No child referrals found"

Cause: No referrals have mag_masterreferral populated (no child referrals exist).

Solution:

This is expected if you haven't run --RecreateAdditionalReferrals
The operation will still update parent referrals with exit data
If you expected child referrals, run --RecreateAdditionalReferrals first

Issue: "Parent referral not found"

Cause: mag_inboundreferral on exit points to a non-existent referral.

Solution:

Verify referrals exist:

SELECT mag_referralid FROM mag_referral WHERE mag_referralid = '<guid from exit>'

Fix exit activities to point to correct referrals, or delete orphaned exits

Issue: "Duplicate child exits created"

Cause: Operation ran multiple times without checking for existing child exits.

Solution: This shouldn't happen as the operation checks for existing child exits. If duplicates exist:

Identify duplicates:

SELECT mag_inboundreferral, mag_exitdate, COUNT(*) AS DuplicateCount
FROM mag_exit
GROUP BY mag_inboundreferral, mag_exitdate
HAVING COUNT(*) > 1

Delete duplicates manually (keep the newest)

Output & Logs

Log File Location

Logs\ParallelProcessing_PopulateExitForReferral_2024-11-17_16-45-22-123.log

Log File Contents

Startup Phase:

[2024-11-17 16:45:22.123] Starting exit population for referrals...
[2024-11-17 16:45:22.456] Counting exit activities with referrals...
[2024-11-17 16:45:23.789] Found 3,850 parent exit activities
[2024-11-17 16:45:24.012] Creating pool of 50 service clients...
[2024-11-17 16:45:25.345] Service client pool created successfully

Processing Phase:

[2024-11-17 16:45:26.678] Processing parent exit: Exit for Smith Family (12345678-1234-1234-1234-123456789012)
[2024-11-17 16:45:26.901] Parent referral: Smith Family Referral (23456789-2345-2345-2345-234567890123)
[2024-11-17 16:45:27.234] Updating parent referral with exit data...
[2024-11-17 16:45:27.567]   mag_exitdate: 2024-11-01
[2024-11-17 16:45:27.890]   mag_exitreason: Service Complete
[2024-11-17 16:45:27.123]   mag_exitedby: John Practitioner (34567890-3456-3456-3456-345678901234)
[2024-11-17 16:45:27.456] Finding child referrals for parent...
[2024-11-17 16:45:27.789] Found 3 child referrals
[2024-11-17 16:45:28.012] Creating child exit for referral: Jane Smith Referral (45678901-4567-4567-4567-456789012345)
[2024-11-17 16:45:28.345] Creating child exit for referral: John Smith Jr Referral (56789012-5678-5678-5678-567890123456)
[2024-11-17 16:45:28.678] Creating child exit for referral: Emily Smith Referral (67890123-6789-6789-6789-678901234567)
[2024-11-17 16:45:28.901] Batch created 3 child exits successfully
[2024-11-17 16:45:45.456] Progress: 1,500/3,850 (39.0%) - 120 ops/sec
[2024-11-17 16:46:12.789] Progress: 3,000/3,850 (77.9%) - 125 ops/sec

Completion Phase:

[2024-11-17 16:46:29.234] Exit population completed
[2024-11-17 16:46:29.567] Total parent exits processed: 3,850
[2024-11-17 16:46:29.890] Total parent referrals updated: 3,850
[2024-11-17 16:46:29.123] Total child exits created: 8,420
[2024-11-17 16:46:29.456] Total time: 67.0 seconds
[2024-11-17 16:46:29.789] Average throughput: 125 exits/sec
[2024-11-17 16:46:29.012] Successful: 3,850 parents / 8,420 children
[2024-11-17 16:46:29.345] Failed: 0

Understanding the Results

Success Indicators:

✅ "Total parent referrals updated" matches parent exits count
✅ "Total child exits created" matches expected child referral count
✅ "Failed: 0"
✅ No ERROR lines in log

Warning Signs:

⚠️ "Failed: X" where X > 0 - Review error messages
⚠️ "Parent referral not found" - Fix referral links
⚠️ Child exit count is 0 but you expected children - Run --RecreateAdditionalReferrals first

Populate Exit for Referral

Overview

When to Use This Operation

Use This Operation When:

Don't Use This Operation When:

Quick Start

Example 1: Preview Exit Population

Example 2: Populate Exits for Referrals

How It Works

Processing Steps

mag_relationships JSON Format

Field Population for Child Exits

Parameters

Required Parameters

--PopulateExitForReferral

--EnvironmentUrl (-e)

--ClientId (-c)

Optional Parameters

--Secret (-s)

--PreviewMode

Tip

Real-World Scenarios

Scenario 1: Complete Exit Process After Creating Child Referrals

Scenario 2: Fix Missing Exit Data After Migration

Scenario 3: Scheduled Nightly Sync

Performance & Scalability

Processing Characteristics

Typical Performance

Note

Troubleshooting

Issue: "No parent exits found"

Issue: "No child referrals found"

Issue: "Parent referral not found"

Issue: "Duplicate child exits created"

Output & Logs

Log File Location

Log File Contents

Understanding the Results

See Also

`--PopulateExitForReferral`

`--EnvironmentUrl` (-e)

`--ClientId` (-c)

`--Secret` (-s)

`--PreviewMode`