organizationsetup - OutcomesFramework DataSet

DataSet Value: OutcomesFramework

The OutcomesFramework DataSet option copies outcomes-specific configuration from a template environment to a target environment, including outcome domains, areas, categories, their relationships, and predefined outcomes and activities.

When to Use

Use the OutcomesFramework DataSet when:

✅ Adding or updating outcome domains, areas, and categories
✅ Synchronising outcomes configuration across environments
✅ Updating predefined outcomes and activities without touching other reference data
✅ Establishing outcomes framework in environment that already has other reference data
✅ Testing outcomes changes before full deployment

Do not use when:

❌ You need complete environment setup (use All instead)
❌ You need service/contract configuration (use ServiceTransfer instead)
❌ You only need to update specific outcomes tables (consider datamanipulation instead)

Command Syntax

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://target.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework"

How It Works

Operation Sequence

The OutcomesFramework DataSet performs 8 operations in dependency order:

1. Foundation Tables
   ├── Outcome domains
   ├── Domain indicators
   ├── Outcome areas
   └── Outcome categories

2. Relationship Tables
   ├── Domain-area relationships
   └── Area-category relationships

3. Predefined Templates
   ├── Predefined outcomes
   └── Predefined outcome activities

Dependency Chain

The operation order ensures referential integrity:

Domains
  ↓
Domain Indicators (reference domains)
  ↓
Areas
  ↓
Categories
  ↓
Domain-Area Relationships (reference domains + areas)
  ↓
Area-Category Relationships (reference areas + categories)
  ↓
Predefined Outcomes (reference domains, areas, categories)
  ↓
Predefined Activities (reference predefined outcomes)

What Gets Copied

Outcome structure:

  • Outcome domains (top-level categorisation)
  • Domain indicators (measurable indicators within domains)
  • Outcome areas (specific areas within domains)
  • Outcome categories (detailed categorisation)

Relationships:

  • Which areas belong to which domains (many-to-many)
  • Which categories belong to which areas (many-to-many)

Templates:

  • Predefined outcomes (template outcomes for plans)
  • Predefined outcome activities (template activities linked to outcomes)

Tables Affected

Outcome Domains

Table: mag_domain

Purpose: Top-level outcome categorisation (e.g., Health, Education, Employment)

Fields:

  • mag_name - Domain name (primary identifier)
  • mag_outcomemap - Outcome mapping option
  • statecode, statuscode - State information

Example domains:

  • Health and Wellbeing
  • Education and Learning
  • Employment and Income
  • Housing and Living Environment
  • Social Connectedness

Domain Indicators

Table: mag_outcomedomainindicator

Purpose: Measurable indicators within outcome domains

Fields:

  • mag_name - Indicator name
  • mag_indicatorcode - Indicator code
  • mag_outcomedomain - Parent domain reference (resolved by mag_name)
  • statecode, statuscode - State information

EntityReference Resolution:

  • Looks up domain name in template environment
  • Finds matching domain in target by name
  • Creates reference to target domain

Error Handling:

  • Console: "Could not resolve domain reference for indicator: [name]" if parent not found
  • Skips indicator if parent domain cannot be resolved

Outcome Areas

Table: mag_outcomearea

Purpose: Specific outcome areas that can span multiple domains

Fields:

  • mag_name - Area name (primary identifier)
  • statecode, statuscode - State information

Example areas:

  • Mental Health
  • Physical Health
  • Academic Achievement
  • Vocational Skills
  • Financial Capability

Outcome Categories

Table: mag_outcomecategory

Purpose: Detailed categorisation within outcome areas

Fields:

  • mag_name - Category name (primary identifier)
  • statecode, statuscode - State information

Example categories:

  • Depression Management
  • Chronic Disease Management
  • Literacy Development
  • Job Readiness
  • Budgeting Skills

Domain-Area Relationships

Table: mag_mag_outcomearea_mag_domain

Purpose: Many-to-many relationships between domains and areas

Primary Field: mag_mag_outcomearea_mag_domainid (relationship record ID)

Fields:

  • mag_domainid - Domain EntityReference
  • mag_outcomeareaid - Outcome area EntityReference

Processing Logic:

  1. Retrieve source relationship:

    • Get domain GUID and area GUID from template relationship record

  2. Look up names:

    • Retrieve domain name from template using domain GUID
    • Retrieve area name from template using area GUID

  3. Find targets:

    • Query target for domain matching source domain name
    • Query target for area matching source area name

  4. Create relationship:

    • Build new relationship record using target domain and area EntityReferences
    • Create in target environment

Console Output:

Domain-Area relationships ...
Source: Domain 'Health and Wellbeing' - Area 'Mental Health'
Creating relationship in target between Health and Wellbeing and Mental Health
+
Source: Domain 'Health and Wellbeing' - Area 'Physical Health'
Creating relationship in target between Health and Wellbeing and Physical Health
+
 done

Error Handling:

  • "Couldn't find source domain or area" - Template data missing
  • "Couldn't find matching domain or area in target" - Target missing prerequisite data
  • Returns false and skips relationship if resolution fails

Area-Category Relationships

Table: mag_mag_outcomecategory_mag_outcomearea

Purpose: Many-to-many relationships between areas and categories

Primary Field: mag_mag_outcomecategory_mag_outcomeareaid (relationship record ID)

Fields:

  • mag_outcomeareaid - Outcome area EntityReference
  • mag_outcomecategoryid - Outcome category EntityReference

Processing Logic: Same pattern as domain-area relationships

Console Output:

Area-Category relationships ...
Source IDs - Area: [guid], Category: [guid]
Source: Area 'Mental Health' - Category 'Depression Management'
Target IDs - Area: [target-guid], Category: [target-guid]
Creating relationship in target between Mental Health and Depression Management
+
 done

Verbose Logging: Includes source/target GUIDs to help troubleshoot resolution issues

Predefined Outcomes

Table: mag_predefinedoutcome

Purpose: Template outcomes that can be added to client plans

Fields:

  • mag_predefinedoutcomeid - Preserved GUID
  • mag_name - Outcome name (primary identifier)
  • mag_outcomename - Display name
  • mag_pdbnumber - PDB number
  • mag_description - Outcome description
  • Duration fields: mag_duration, mag_stdduration
  • mag_createfromreferral - Auto-create from referral flag

EntityReference Fields (All Resolved by mag_name):

Service references:

  • mag_activitydefaultservice - Default service for activities
  • mag_service - Associated contract service

Analysis fields:

  • mag_analysis1, mag_analysis2, mag_analysis3 - Custom analysis lookups

Outcome framework references:

  • mag_domain1, mag_domain2, mag_domain3 - Up to 3 associated domains
  • mag_outcomearea1, mag_outcomearea2, mag_outcomearea3 - Up to 3 associated areas
  • mag_outcomecategory1, mag_outcomecategory2, mag_outcomecategory3 - Up to 3 associated categories

Special Handling:

  • Custom PredefinedOutcomeWriter method handles multiple domain/area/category references
  • Each EntityReference independently resolved
  • NULL references preserved if source is NULL
  • GUID preserved to maintain consistency

Example predefined outcome:

Name: "Improve Mental Health"
Domains: Health and Wellbeing
Areas: Mental Health
Categories: Depression Management, Anxiety Management
Description: "Work with client to improve mental health outcomes through structured support"
Duration: 90 days

Predefined Outcome Activities

Table: mag_predefinedactivity

Purpose: Template activities that auto-create with predefined outcomes

Primary Key: Composite key of mag_name + mag_service

Fields:

Identification:

  • mag_name - Activity name (part of composite key)
  • mag_summary - Activity summary
  • mag_pdanumber - PDA number

Configuration:

  • mag_message - User message/instructions
  • mag_activitytype - Activity type option
  • mag_assessmenttype - Assessment type option
  • mag_who - Who performs activity option
  • mag_referralstagetogenerate - When to generate option

Boolean flags:

  • mag_familygroupactivity - Family group activity
  • mag_createbackdatedactivity - Can create backdated
  • mag_requiredforenrolment - Required for enrollment
  • mag_enrolment - Is enrollment activity
  • mag_clientfacing - Client-facing activity
  • mag_globalenrolment - Global enrollment flag

Timing configuration:

  • mag_startafterfrom - Start after from option
  • mag_startaftertype - Start after type option
  • mag_dueaftertype - Due after type option
  • mag_startat - Start at option
  • mag_startafter - Start after value (integer)
  • mag_dueafter - Due after value (integer)

EntityReference Fields (All Resolved by mag_name):

  • mag_service - Associated contract service (part of composite key)
  • mag_predefinedoutcome - Parent predefined outcome
  • mag_assessmenttool - Required assessment tool
  • mag_consenttype - Required consent type
  • mag_dynamicassessmenttemplate - Assessment template
  • mag_activitygroup1a, mag_activitygroup2a, mag_activitygroup3a - Activity groups

⚠️ COMPOSITE KEY: Multiple activities can have the same name if associated with different services. This is intentional and allows service-specific activity templates.

Console Output:

Predefined Outcome Activities ...
Processing: "Initial Assessment"
Checking predefined activity with name: Initial Assessment and service ID: [guid]
Retrieved mag_name: Mental Health Service
Creating new predefined activity
+
 done

Special Handling in EntityHelper.CreateIfNew:

  1. Queries for existing activity by name + service ID
  2. If exists and UpdateExisting=true, updates the activity
  3. If exists and UpdateExisting=false, skips
  4. If not exists, creates new activity with resolved service reference

Real-World Scenarios

Scenario 1: New Outcomes Framework Deployment

Context: You've developed a new outcomes framework in master data and need to deploy to test environment.

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://test.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework"

Expected Console Output:

Navigator environment prepration tool
Master Data: Whānau Tahi Master Data
Target System: Test Environment
Outcome domains ...+++++... done
Domain indicators ...+++++++... done
Outcomne areas ...++++++++... done
Outcome categories ...+++++++++++... done
Domain-Area relationships ...
Source: Domain 'Health and Wellbeing' - Area 'Mental Health'
Creating relationship in target between Health and Wellbeing and Mental Health
++++... done
Area-Category relationships ...
Source: Area 'Mental Health' - Category 'Depression Management'
Creating relationship in target between Mental Health and Depression Management
+++++... done
Predefined Outcome Activities ...++++++++++... done
Environment preparation completed

Result: Complete outcomes framework deployed to test environment.

Post-Deployment:

  1. Review outcome domains in target environment
  2. Verify domain-area relationships created correctly
  3. Test creating plan with predefined outcomes
  4. Confirm predefined activities auto-create as expected

Scenario 2: Outcomes Framework Update

Context: Updated outcomes framework in master data (added new categories, modified predefined outcomes) and need to sync to production.

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://production.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework" `
    --AddToExistingData `
    --UpdateExisting

Why these flags:

  • AddToExistingData - Production already has outcomes framework
  • UpdateExisting - Update existing predefined outcomes with new definitions

Expected Console Output:

Outcome domains ...-U-U+--... done
Domain indicators ...-U-+---... done
Outcomne areas ...-U---+-... done
Outcome categories ...--U++++--... done
Domain-Area relationships ...-+---... done
Area-Category relationships ...+++---... done
Predefined Outcome Activities ...UUUU+++UU... done
Environment preparation completed

Console legend:

  • - = Skipped (already exists, no update needed)
  • U = Updated existing record
  • + = Created new record

Result:

  • New outcome categories added
  • Existing predefined outcomes updated
  • New predefined activities created
  • Existing domains/areas/relationships preserved

Scenario 3: Multi-Environment Sync

Context: Need to synchronise outcomes framework across dev, test, and UAT environments.

Strategy: Use master data as single source of truth for all environments

# Sync to Dev
.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://dev.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework" `
    --UpdateExisting

# Sync to Test
.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://test.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework" `
    --UpdateExisting

# Sync to UAT
.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://uat.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework" `
    --UpdateExisting

Result: All three environments have identical outcomes framework matching master data.

Validation:

  • Export outcomes framework from each environment
  • Compare domain/area/category counts
  • Verify predefined outcomes match
  • Test plan creation in each environment

Scenario 4: Outcomes Framework Testing

Context: Testing proposed outcomes framework changes in isolated sandbox before committing to master data.

Steps:

  1. Create test master data environment:

    • Copy current master data to new environment
    • Make proposed changes to outcomes framework

  2. Deploy to test sandbox:

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://testmasterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://sandbox.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework"

  1. User acceptance testing:

    • Test creating plans with new predefined outcomes
    • Verify activity auto-creation works
    • Validate domain/area/category structure makes sense
    • Gather feedback from users

  2. If approved, promote to real master data:

    • Apply changes to official master data environment
    • Run organizationsetup to sync to all environments

Result: Changes validated before impacting production environments.

Scenario 5: Post-Refresh Outcomes Restore

Context: Refreshed sandbox from production, need to restore development-specific outcomes framework.

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://devmasterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://refreshedsandbox.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --DataSet "OutcomesFramework" `
    --AddToExistingData `
    --UpdateExisting

Why this works:

  • Sandbox has production outcomes framework after refresh
  • Dev master data has development-specific outcomes
  • AddToExistingData allows operations despite existing data
  • UpdateExisting overwrites production outcomes with dev outcomes
  • Development-specific predefined outcomes restored

Console Output:

Outcome domains ...----UU++... done
Predefined Outcome Activities ...----UUUUU++++... done

Result: Development-specific outcomes restored, ready for development work.

Performance Considerations

Typical Execution Time

OutcomesFramework DataSet: 1-3 minutes

Breakdown:

  • Outcome domains: 5-10 seconds
  • Domain indicators: 10-20 seconds
  • Outcome areas: 5-10 seconds
  • Outcome categories: 10-20 seconds
  • Domain-area relationships: 10-30 seconds
  • Area-category relationships: 10-30 seconds
  • Predefined outcomes: 20-40 seconds
  • Predefined activities: 20-60 seconds

Factors affecting duration:

  • Number of predefined outcomes and activities (can be hundreds)
  • Number of domain-area and area-category relationships
  • Network latency between environments
  • Use of UpdateExisting flag (slower than create-only)

Optimisation Tips

For faster execution:

  1. Run during off-peak hours
  2. Use default flags when possible (no AddToExistingData or UpdateExisting)
  3. Minimise predefined outcomes/activities in template environment

For large outcomes frameworks:

  • Monitor console output for stalled operations
  • Check for relationship resolution failures
  • Consider splitting into smaller deployments if needed

Troubleshooting

Domain Indicator Creation Fails

Problem: "Could not resolve domain reference for indicator: [name]"

Cause: Parent domain doesn't exist in target environment

Solution:

  1. Verify outcome domains operation completed successfully
  2. Check domain name spelling in template environment
  3. Ensure domain exists in target before indicators
  4. Review console output for domain creation errors

Relationship Creation Skipped

Problem: All relationship records show - (skipped)

Cause: Relationships already exist and UpdateExisting=false

Solution:

  • This is normal behavior if relationships already exist
  • Use UpdateExisting flag only if you need to recreate relationships
  • Relationships are typically stable and don't need frequent updates

Relationship Creation Fails

Problem: "Couldn't find matching domain or area in target"

Cause: Prerequisite entities missing from target

Solution:

  1. Ensure domains operation completed before domain-area relationships
  2. Ensure areas operation completed before area-category relationships
  3. Check console output for earlier errors
  4. Verify source data is correct in template environment

Predefined Activity Duplicates

Problem: Multiple predefined activities with same name created

Cause: Activities can have same name with different services (composite key)

Solution:

  • Review mag_service field on duplicate activities
  • This is expected if activities belong to different services
  • If truly duplicate (same name + same service), check source data

EntityReference Resolution Fails

Problem: "Could not resolve [entity] reference" for predefined outcomes/activities

Cause: Referenced entity doesn't exist in target

Solution:

  1. Ensure all prerequisite operations completed:
    • Domains, areas, categories must exist for predefined outcomes
    • Predefined outcomes must exist for predefined activities
    • Services must exist if referenced
  2. Check operation order in console output
  3. Verify referenced records exist in template environment

Predefined Outcome GUID Mismatch

Problem: Same predefined outcome has different GUID in target vs template

Cause: Predefined outcome was deleted and recreated in target

Solution:

  1. Delete incorrect predefined outcome from target
  2. Re-run organizationsetup to recreate with correct GUID
  3. GUID preservation is important for consistency

Update Not Taking Effect

Problem: Updated predefined outcomes in master data but changes not appearing in target

Cause: UpdateExisting=false (default) skips existing records

Solution:

  • Add --UpdateExisting flag to command
  • This will update existing predefined outcomes/activities with new values
  • Test in non-production environment first

Best Practices

Outcomes Framework Design

Master data environment structure:

  1. Clear domain hierarchy:

    • Define 3-7 top-level domains
    • Each domain has meaningful indicators
    • Avoid overly complex domain structures

  2. Logical area groupings:

    • Areas should be reusable across domains
    • Keep area names client-friendly
    • Document area-domain relationships

  3. Granular categories:

    • Categories provide specific outcome focus
    • Link categories to relevant areas
    • Use consistent naming conventions

  4. Well-defined predefined outcomes:

    • Clear outcome names and descriptions
    • Appropriate duration estimates
    • Correct domain/area/category associations
    • Service references where applicable

  5. Thoughtful predefined activities:

    • Activities that support outcome achievement
    • Realistic timing configurations
    • Appropriate assessment tool linkages
    • Clear service associations

Change Management

Before making outcomes framework changes:

✅ Document current framework structure
✅ Identify impact of proposed changes
✅ Test changes in development environment
✅ Get stakeholder approval for structural changes
✅ Plan deployment schedule
✅ Communicate changes to users

Version control:

  1. Maintain documentation of outcomes framework versions
  2. Tag master data environment with version/date
  3. Keep change log of modifications
  4. Document reasons for structural changes

Testing workflow:

  1. Make changes in master data environment
  2. Deploy to development using OutcomesFramework DataSet
  3. Test plan creation with new predefined outcomes
  4. Verify activity auto-creation works
  5. UAT testing with end users
  6. Deploy to production during scheduled maintenance

Incremental Updates

For ongoing maintenance:

  1. Update master data first:

    • Make all changes to master data environment
    • Test changes within master data
    • Document changes made

  2. Deploy to dev:

    --DataSet "OutcomesFramework" --UpdateExisting
    • Test deployment in dev
    • Verify updates applied correctly

  3. Deploy to test/UAT:

    • Same command to test/UAT environments
    • Conduct user testing
    • Validate changes

  4. Schedule production deployment:

    • Choose low-usage time
    • Communicate to users
    • Deploy with same command
    • Monitor for issues

Validation Checklist

After OutcomesFramework deployment:

Domains & Indicators: ✅ Count of outcome domains matches template
✅ Domain indicators reference correct domains
✅ No orphaned indicators (indicators without parent domain)

Areas & Categories: ✅ Count of outcome areas matches template
✅ Count of outcome categories matches template
✅ Categories can be associated with areas correctly

Relationships: ✅ Domain-area relationships created
✅ Area-category relationships created
✅ Relationship counts match template environment
✅ No duplicate relationships

Predefined Outcomes: ✅ Predefined outcomes present
✅ Domain/area/category references resolved
✅ Service references (if any) resolved
✅ Descriptions and durations correct

Predefined Activities: ✅ Predefined activities present
✅ Linked to correct predefined outcomes
✅ Assessment tool references resolved
✅ Timing configurations correct

Integration Testing: ✅ Create test plan with predefined outcome
✅ Verify predefined activities auto-create
✅ Test activity timing (start after, due after)
✅ Confirm assessment tools work correctly

Disaster Recovery

Include outcomes framework in DR plan:

  1. Backup master data environment:

    • Regular automated backups
    • Manual exports before major changes
    • Store backup exports securely

  2. Document deployment commands:

    • Save complete organizationsetup commands
    • Include DataSet options used
    • Note any special flags

  3. Test recovery process:

    • Periodically restore to test environment
    • Verify outcomes framework restores correctly
    • Update DR documentation

  4. Recovery sequence:

    • Restore Dataverse environment
    • Run organizationsetup with OutcomesFramework DataSet
    • Verify relationship tables populated
    • Test predefined outcome functionality

Tables Summary

The OutcomesFramework DataSet affects 8 tables:

Foundation:

  1. mag_domain - Outcome domains
  2. mag_outcomedomainindicator - Domain indicators
  3. mag_outcomearea - Outcome areas
  4. mag_outcomecategory - Outcome categories

Relationships: 5. mag_mag_outcomearea_mag_domain - Domain-area relationships 6. mag_mag_outcomecategory_mag_outcomearea - Area-category relationships

Templates: 7. mag_predefinedoutcome - Predefined outcomes 8. mag_predefinedactivity - Predefined outcome activities

See Also