organizationsetup - ServiceTransfer DataSets

DataSet Values: ServiceTransfer | ServiceTransferWithoutDomainRelationships

The ServiceTransfer DataSets copy service delivery configuration from a template environment to a target environment, including PRIMHD teams, contracts, services, eligibility rules, and the complete outcomes framework.

When to Use

Use the ServiceTransfer DataSet when:

✅ Setting up service delivery in new environment
✅ Migrating service configuration between environments
✅ Adding new contract services with eligibility rules
✅ Establishing complete service infrastructure including outcomes
✅ Synchronising service setup across environments

Use the ServiceTransferWithoutDomainRelationships variant when:

✅ All outcome relationships (domain-area AND area-category) already exist in target
✅ Want to skip ALL relationship table processing for performance
✅ Updating services without touching any outcome relationships
✅ Outcome framework structure is completely stable and doesn't need sync

Do not use when:

❌ You need complete environment setup (use All instead)
❌ You only need outcomes framework (use OutcomesFramework instead)
❌ You only need specific tables (use datamanipulation instead)

DataSet Comparison

Feature	ServiceTransfer	ServiceTransferWithoutDomainRelationships
PRIMHD Teams	✅ Yes	✅ Yes
Contract Grouping	✅ Yes	✅ Yes
Funding Contract Types	✅ Yes	✅ Yes
Funding Contracts	✅ Yes	✅ Yes
Contract Services	✅ Yes	✅ Yes
Service Eligibility Rules	✅ Yes	✅ Yes
Contract Service Types	✅ Yes	✅ Yes
Contract Service Sites	✅ Yes	✅ Yes
Outcome Domains	✅ Yes	✅ Yes
Domain Indicators	✅ Yes	✅ Yes
Outcome Areas	✅ Yes	✅ Yes
Outcome Categories	✅ Yes	✅ Yes
Domain-Area Relationships	✅ Yes	❌ No
Area-Category Relationships	✅ Yes	❌ No
Activity Groups	✅ Yes	✅ Yes
Predefined Outcomes	✅ Yes	✅ Yes
Consent Types	✅ Yes	✅ Yes
Predefined Activities	✅ Yes	✅ Yes
Operation Count	18 operations	16 operations

Key difference: The WithoutDomainRelationships variant skips creating both mag_mag_outcomearea_mag_domain (domain-area) and mag_mag_outcomecategory_mag_outcomearea (area-category) relationship records. All other operations are identical.

Command Syntax

ServiceTransfer (Full)

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

ServiceTransferWithoutDomainRelationships (Optimised)

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

How It Works

Operation Sequence - ServiceTransfer

The ServiceTransfer DataSet performs 18 operations in dependency order:

1. PRIMHD Configuration
   └── PRIMHD teams

2. Contract Infrastructure - Types & Grouping
   ├── Funding contract types
   ├── Contract grouping (2-pass: create, then link parents)
   ├── Contract service types
   └── Contract service sites

3. Contract Infrastructure - Contracts & Services
   ├── Funding contracts
   ├── Contract services
   └── Service eligibility rules

4. Outcomes Framework - Foundation
   ├── Outcome domains
   ├── Domain indicators
   ├── Outcome areas
   └── Outcome categories

5. Outcomes Framework - Relationships
   ├── Domain-area relationships ← ONLY IN ServiceTransfer
   └── Area-category relationships

6. Supporting Reference Data
   └── Activity groups

7. Outcomes Framework - Templates
   ├── Predefined outcomes
   ├── Consent types
   └── Predefined outcome activities

Operation Sequence - ServiceTransferWithoutDomainRelationships

Same as ServiceTransfer except skips step 5 entirely (both relationship operations):

5. Outcomes Framework - Relationships
   ├── Domain-area relationships ← SKIPPED
   └── Area-category relationships ← SKIPPED

Result: 16 operations instead of 18.

Dependency Chain

PRIMHD Teams (standalone)
  ↓
Contract Grouping → Grouping with parent references
  ↓
Contract Types → Funding Contracts → Contract Services
                                       ↓
                        Service Eligibility Rules (composite key: name + service)
                                       ↓
                        Service Types/Sites (supporting tables)
  ↓
Outcome Domains
  ↓
Domain Indicators (reference domains)
  ↓
Outcome Areas
  ↓
Outcome Categories
  ↓
Domain-Area Relationships [OPTIONAL] (reference domains + areas)
  ↓
Area-Category Relationships [OPTIONAL] (reference areas + categories)
  ↓
Predefined Outcomes (reference domains, areas, categories, services)
  ↓
Predefined Activities (reference predefined outcomes, services)
  ↓
Activity Groups (standalone)
Consent Types (standalone)

Tables Affected

PRIMHD Teams

Table: mag_primhdteam

Purpose: PRIMHD reporting team configuration

Fields:

• mag_primhdteamid - GUID (preserved)
• mag_primhdcode - PRIMHD team code
• mag_primhdteamname - Team name (primary identifier)
• mag_teamcode - Team code

Special Handling:

• GUID preserved for consistency
• Name-based uniqueness checking

Example teams:

• Mental Health Team (code: MH01)
• Youth Services Team (code: YS02)
• Family Support Team (code: FS03)

Contract Grouping

Table: mag_grouping

Purpose: Hierarchical organisation of funding contracts

Fields:

• mag_name - Grouping name (primary identifier)
• mag_description - Grouping description
• mag_abbreviation - Grouping abbreviation
• mag_parentgrouping - Parent grouping reference

Two-Pass Processing:

First Pass - Create groupings:

Contract grouping ...
Processing: Health Services
+
Processing: Mental Health Services
+
Processing: Youth Mental Health
+
 done

Second Pass - Link parent references:

Updating grouping parent references ...
Grouping: Mental Health Services
Parent: Health Services
Retrieved parent grouping from target: Health Services ([guid])
U
Grouping: Youth Mental Health
Parent: Mental Health Services
Retrieved parent grouping from target: Mental Health Services ([guid])
U
 done

Why two passes:

1. All groupings must exist before setting parent references
2. Parent references resolved by name in target environment
3. Supports multi-level hierarchies

Example hierarchy:

Health Services
  ├── Mental Health Services
  │   ├── Youth Mental Health
  │   └── Adult Mental Health
  └── Physical Health Services

Funding Contract Types

Table: mag_contracttype

Purpose: Contract type definitions

Fields:

• mag_name - Contract type name (primary identifier)
• mag_description - Description
• mag_contracttypecode - Type code

Special Handling:

• addToExistingData = true (allows adding to populated environments)
• Name-based uniqueness

Example types:

• Service Delivery Contract
• Support Services Contract
• Assessment Contract

Funding Contracts

Table: mag_fundingcontract

Purpose: Funding contract records with dates and financial configuration

Scalar Fields:

• mag_name - Contract name (primary identifier)
• mag_contractnumber - Contract number
• mag_startdate, mag_expirydate - Contract period
• mag_noticerequired - Notice period required
• mag_totalfunding - Total funding amount
• mag_usevoucherfunding - Use voucher funding flag
• mag_fundingrunoutdate - Funding run-out date
• mag_description - Contract description

EntityReference Fields (Resolved by mag_name):

• mag_contracttype - Contract type
• mag_grouping - Contract grouping
• mag_billinggroup - Billing group
• mag_currency - Currency
• mag_analysis1, mag_analysis2, mag_analysis3 - Custom analysis lookups
• mag_billinganalysis - Billing analysis

Special Handling - Date Validation:

⚠️ Dates before January 1, 1850 are set to NULL

This prevents errors from invalid or placeholder dates:

DateTime lowerLimit = new DateTime(1850, 1, 1);
if (contract["mag_startdate"] != null && (DateTime)contract["mag_startdate"] < lowerLimit)
{
    contract["mag_startdate"] = null;
}

Why this matters:

• Some data migrations use very early dates as placeholders
• Dataverse has minimum date restrictions
• NULL is better than invalid date

Example contract:

Name: "Community Mental Health Services 2024"
Contract Number: "CMH-2024-001"
Start Date: 2024-01-01
Expiry Date: 2024-12-31
Contract Type: Service Delivery Contract
Grouping: Mental Health Services
Total Funding: $500,000

Contract Services

Table: mag_contractservice

Purpose: Services delivered under funding contracts

Scalar Fields:

Service identification:

• mag_name - Service name (primary identifier)
• mag_servicecode - Service code
• mag_shortname - Short name
• mag_description - Service description

Configuration:

• mag_active - Active status
• mag_startdate, mag_enddate - Service period
• mag_canclose - Can close flag
• mag_showonplans - Show on plans flag
• mag_globalenrolment - Global enrollment flag
• mag_consentexpirydays - Consent expiry days
• mag_allowpastdatededit - Allow past date edit
• mag_defaultnotcaptured - Default not captured flag

Assessment configuration:

• mag_autocreateinitialassessment - Auto-create initial assessment
• mag_autogeneratereassessments - Auto-generate reassessments
• mag_allowmultipleprimaryassessments - Allow multiple primary assessments
• mag_daysforautogeneratedreassessment - Days for auto-generated reassessment
• mag_autocreateinitialassessmentdays - Auto-create initial assessment days
• mag_riskassessmentmessage - Risk assessment message

Exit configuration:

• mag_exitreasonrequired - Exit reason required
• mag_exitlockreason - Exit lock reason
• mag_allowexitreasonchange - Allow exit reason change
• mag_allownoexit - Allow no exit

Financial configuration:

• mag_isvoucherservice - Is voucher service
• mag_voucherexpiryperiod - Voucher expiry period
• mag_vouchervalue - Voucher value
• mag_vouchermessage - Voucher message

EntityReference Fields (All Resolved by mag_name):

• mag_fundingcontract - Parent funding contract
• mag_assessmenttype - Default assessment type
• mag_riskassessmenttype - Risk assessment type
• mag_defaultconsenttype - Default consent type
• mag_contractservicetype - Contract service type
• mag_contractservicesite - Contract service site
• mag_currency - Currency
• mag_voucher - Voucher configuration
• mag_servicetransfer - Service transfer configuration
• mag_referralservice - Referral service

Special Handling - Date Validation: Same as funding contracts - dates before January 1, 1850 set to NULL

Example service:

Name: "Youth Mental Health Support"
Service Code: "YMHS"
Funding Contract: "Community Mental Health Services 2024"
Service Type: Mental Health Service
Start Date: 2024-01-01
End Date: 2024-12-31
Active: Yes
Show on Plans: Yes
Auto-create Initial Assessment: Yes
Days for Auto-generated Reassessment: 90
Exit Reason Required: Yes

Service Eligibility Rules

Table: mag_eligibilityrule

Purpose: Define who can enroll in services based on criteria

Primary Key: Composite key of mag_eligibilityrulename + mag_contractserviceid

Scalar Fields:

• mag_eligibilityrulename - Rule name (part of composite key)
• mag_eligibilityrule - Rule logic
• mag_eligibilityrulecode - Rule code
• mag_allowenrolment - Allow enrollment flag
• mag_allowclosingenrolment - Allow closing enrollment flag
• mag_allowreferral - Allow referral flag
• mag_gender - Gender restriction
• mag_minage, mag_maxage - Age range restrictions

EntityReference Fields (Resolved by mag_name):

• mag_contractserviceid - Parent contract service (part of composite key)
• mag_agegroup - Age group restriction
• mag_ethnicity - Ethnicity restriction
• mag_levelofeducation - Education level restriction

⚠️ COMPOSITE KEY: Multiple rules can have the same name if associated with different services.

Special Handling in EntityHelper.CreateIfNew:

// Query for existing rule by NAME + SERVICE
QueryExpression query = new QueryExpression("mag_eligibilityrule");
query.Criteria.AddCondition("mag_eligibilityrulename", ConditionOperator.Equal, entity["mag_eligibilityrulename"]);
query.Criteria.AddCondition("mag_contractserviceid", ConditionOperator.Equal, entity["mag_contractserviceid"]);

// Console output shows both identifying fields
Console.Write($"Checking eligibility rule with name: {entity["mag_eligibilityrulename"]} and service ID: {serviceId}");

Console Output:

Eligibility rules ...
Checking eligibility rule with name: Youth Age Restriction and service ID: [guid]
Retrieved mag_name: Youth Mental Health Support
Creating new eligibility rule
+
Checking eligibility rule with name: Adult Age Restriction and service ID: [guid]
Retrieved mag_name: Adult Mental Health Support
Creating new eligibility rule
+
 done

Why composite key:

• Same eligibility rule logic can apply to multiple services
• Service-specific age restrictions (e.g., "Youth" means different ages for different services)
• Allows copying rule templates across services

Example rules:

Rule: "Youth Age Restriction"
Service: Youth Mental Health Support
Min Age: 12
Max Age: 25
Allow Enrollment: Yes

Rule: "Youth Age Restriction"  ← SAME NAME, DIFFERENT SERVICE
Service: Youth Substance Abuse
Min Age: 10
Max Age: 18
Allow Enrollment: Yes

Contract Service Types

Table: mag_contractservicetype

Purpose: Categorise contract services

Fields:

• mag_name - Service type name (primary identifier)

Example types:

• Mental Health Service
• Family Support Service
• Youth Service
• Assessment Service

Contract Service Sites

Table: mag_contractservicesite

Purpose: Physical locations where services are delivered

Fields:

• mag_name - Site name (primary identifier)
• mag_sitecode - Site code
• mag_sitedescription - Site description

Example sites:

• Auckland Central Clinic (code: AKL-CENTRAL)
• Christchurch Community Hub (code: CHC-COMM)
• Wellington Youth Centre (code: WLG-YOUTH)

Outcome Domains

Table: mag_domain

Purpose: Top-level outcome categorisation

Fields:

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

See organizationsetup-outcomes.md for complete details.

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
• statecode, statuscode - State information

See organizationsetup-outcomes.md for complete details.

Outcome Areas

Table: mag_outcomearea

Purpose: Specific outcome areas spanning multiple domains

Fields:

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

See organizationsetup-outcomes.md for complete details.

Outcome Categories

Table: mag_outcomecategory

Purpose: Detailed categorization within outcome areas

Fields:

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

See organizationsetup-outcomes.md for complete details.

Domain-Area Relationships

Table: mag_mag_outcomearea_mag_domain

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

⚠️ ONLY CREATED BY ServiceTransfer - The ServiceTransferWithoutDomainRelationships variant skips this operation.

Fields:

• mag_domainid - Domain EntityReference
• mag_outcomeareaid - Outcome area EntityReference

See organizationsetup-outcomes.md for complete details.

When to skip:

• Domain-area relationships already correct in target
• Updating services without changing outcome structure
• Performance optimisation (relationship creation can be slow)

Area-Category Relationships

Table: mag_mag_outcomecategory_mag_outcomearea

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

⚠️ ONLY CREATED BY ServiceTransfer - The ServiceTransferWithoutDomainRelationships variant skips this operation (along with domain-area relationships).

Fields:

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

See organizationsetup-outcomes.md for complete details.

Predefined Outcomes

Table: mag_predefinedoutcome

Purpose: Template outcomes linked to services

Key Fields:

• mag_predefinedoutcomeid - GUID (preserved)
• mag_name - Outcome name (primary identifier)
• mag_service - Associated contract service (EntityReference)

Multiple EntityReferences:

• Service reference: mag_service, mag_activitydefaultservice
• Outcome framework references: mag_domain1-3, mag_outcomearea1-3, mag_outcomecategory1-3
• Analysis references: mag_analysis1-3

See organizationsetup-outcomes.md for complete details.

ServiceTransfer importance:

• Predefined outcomes often reference contract services
• Service references must resolve correctly
• Contract services created earlier in operation sequence ensure references work

Predefined Outcome Activities

Table: mag_predefinedactivity

Purpose: Template activities for predefined outcomes

Composite Key: mag_name + mag_service

Key Fields:

• mag_name - Activity name (part of composite key)
• mag_service - Associated contract service (part of composite key)
• mag_predefinedoutcome - Parent predefined outcome

See organizationsetup-outcomes.md for complete details.

ServiceTransfer importance:

• Activities frequently reference contract services
• Service association enables service-specific activity templates
• Contract services must exist before activities can be created

Activity Groups

Table: mag_activitygroup

Purpose: Group activities for reporting and organisation

Fields:

• mag_name - Activity group name (primary identifier)
• mag_activitygroupcode - Activity group code
• mag_description - Group description
• mag_sortorder - Display sort order
• mag_activitytype - Activity type option
• mag_contactfacing - Contact facing flag

Example groups:

• Assessments (code: ASSESS, sort: 1, type: Assessment)
• Case Management (code: CASEMGMT, sort: 2, type: Case Work)
• Therapeutic Interventions (code: THERAPY, sort: 3, type: Clinical)
• Family Support (code: FAMILY, sort: 4, type: Support)

Why included in ServiceTransfer:

• Activity groups often align with service types
• Services typically use consistent activity categorisation
• Ensures activity tracking consistency across environments

Consent Types

Table: mag_consenttype

Purpose: Define consent types for services and activities

Fields:

• mag_name - Consent type name (primary identifier)
• mag_consenttypecode - Consent type code
• statecode, statuscode - State information

Special Handling:

• Verbose logging enabled (logs each field being copied)
• Useful for debugging consent type issues

Example consent types:

• Service Enrollment Consent (code: ENROL)
• Information Sharing Consent (code: INFOSHARE)
• Assessment Consent (code: ASSESS)
• Photography Consent (code: PHOTO)

Why included in ServiceTransfer:

• Services often have default consent types
• Contract services reference consent types
• Consent requirements vary by service type

Real-World Scenarios

Scenario 1: New Service Environment Setup

Context: Setting up new UAT environment with complete service infrastructure.

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

Expected Console Output:

Navigator environment prepration tool
Master Data: Whānau Tahi Master Data
Target System: UAT Environment

PRIMHD teams ...+++... done

Contract grouping ...+++... done
Updating grouping parent references ...UU... done

Funding contract types ...++... done
Funding Contracts ...++++... done
Contract Services ...+++++++... done

Eligibility rules ...
Checking eligibility rule with name: Youth Age Restriction and service ID: [guid]
Retrieved mag_name: Youth Mental Health Support
Creating new eligibility rule
+++++++... done

Contract service types ...+++... done
Contract service sites ...+++++... done

Outcome domains ...+++++... done
Domain indicators ...+++++++... done
Outcomne areas ...++++++++... done
Outcome categories ...+++++++++++... done

Domain-Area relationships ...++++... done
Area-Category relationships ...+++++... done

Predefined Outcome Activities ...++++++++++... done

Activity groups ...++++... done
Consent types ...+++... done

Environment preparation completed

Result: Complete service infrastructure ready for use in UAT.

Post-Deployment Validation:

1. Review PRIMHD teams created
2. Verify contract hierarchy (grouping → contracts → services)
3. Check service eligibility rules
4. Test creating enrollment with predefined outcome
5. Confirm predefined activities auto-create

Scenario 2: Service Configuration Update with Existing Outcomes

Context: Production environment already has outcomes framework. Need to update service configuration only.

Strategy: Use ServiceTransferWithoutDomainRelationships to skip domain-area relationships (already correct).

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

Why this approach:

• ServiceTransferWithoutDomainRelationships - Skip domain-area relationships
• AddToExistingData - Production has existing services
• UpdateExisting - Update existing contract services with new configuration

Expected Console Output:

PRIMHD teams ...---U++... done
Contract grouping ...-UU+... done
Funding Contracts ...--UU++... done
Contract Services ...---UUUUU++... done
Eligibility rules ...--UUU+++... done

Outcome domains ...--------... done
Domain indicators ...--------... done
Outcomne areas ...--------... done
Outcome categories ...-U-U----... done

Domain-Area relationships ... ← SKIPPED
Area-Category relationships ...-----... done

Predefined Outcome Activities ...UUUUUU+++... done

Activity groups ...----U++... done
Consent types ...-----... done

Environment preparation completed

Console legend:

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

Performance gain:

• Skipped domain-area relationships operation
• Faster execution (10-15% time savings)

Result:

• New PRIMHD teams added
• Contract services updated with new configuration
• New eligibility rules created
• Predefined activities updated
• Domain-area relationships left unchanged

Scenario 3: Multi-Environment Service Sync

Context: Synchronised service configuration across dev, test, UAT, and production.

Step 1 - Update master data:

1. Make service configuration changes in master data environment
2. Test changes within master data
3. Document changes made

Step 2 - Deploy to dev (full sync):

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

Step 3 - Deploy to test (full sync):

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

Step 4 - UAT testing:

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

Step 5 - Production deployment (optimised):

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

Production deployment rationale:

• Use ServiceTransferWithoutDomainRelationships for faster execution
• Domain-area relationships already correct (synced in previous deployment)
• AddToExistingData and UpdateExisting for production safety

Result: All environments have identical service configuration.

Scenario 4: New Service Addition

Context: Adding new service to existing environment with minimal changes.

Changes in master data:

1. Created new funding contract "Early Intervention 2024"
2. Created new contract service "Youth Early Intervention"
3. Added eligibility rules for new service
4. Created predefined outcomes for new service
5. Created predefined activities for new service

Deployment:

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

Why these flags:

• ServiceTransferWithoutDomainRelationships - Outcomes framework unchanged
• AddToExistingData - Production has existing services
• NO UpdateExisting - Only add new service, don't modify existing

Expected Console Output:

PRIMHD teams ...--------... done
Contract grouping ...--------... done
Funding contract types ...--------... done
Funding Contracts ...------+... done (1 new)
Contract Services ...----------+... done (1 new)
Eligibility rules ...--------+++... done (3 new)
Outcome domains ...--------... done
Predefined Outcome Activities ...---------+++... done (3 new for new service)
Activity groups ...--------... done
Consent types ...--------... done
Environment preparation completed

Result: New service added without affecting existing services.

Scenario 5: Post-Refresh Service Restoration

Context: Refreshed test environment from production backup. Need to restore test-specific service configuration.

Challenge: Test environment now has production service configuration. Want test-specific services restored.

Solution:

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

Why this works:

• testmasterdata environment contains test-specific service configuration
• AddToExistingData allows adding to environment that has production services
• UpdateExisting overwrites production services with test-specific versions
• Test-specific predefined outcomes and activities restored

Result: Test environment has test-specific services while preserving production-like data.

Best practice:

• Maintain separate master data for test-specific configuration
• Document which services are test-only vs production
• Consider using service naming conventions (e.g., "TEST-" prefix)

Performance Considerations

Typical Execution Time

ServiceTransfer: 3-7 minutes ServiceTransferWithoutDomainRelationships: 2.5-6 minutes

Breakdown (ServiceTransfer):

• PRIMHD teams: 5-10 seconds
• Contract grouping (2 passes): 20-40 seconds
• Funding contract types: 5-10 seconds
• Funding contracts: 15-30 seconds
• Contract services: 30-90 seconds
• Eligibility rules: 20-60 seconds
• Contract service types/sites: 10-20 seconds
• Outcome domains/indicators: 15-30 seconds
• Outcome areas/categories: 15-30 seconds
• Domain-area relationships: 15-45 seconds ← SKIPPED IN VARIANT
• Area-category relationships: 15-45 seconds
• Predefined outcomes: 20-40 seconds
• Predefined activities: 30-90 seconds
• Activity groups: 10-20 seconds
• Consent types: 5-15 seconds

Performance gain with ServiceTransferWithoutDomainRelationships:

• Saves 15-45 seconds (domain-area relationships)
• Approximately 10-15% faster
• Most beneficial when domain-area relationships are numerous

Factors affecting duration:

• Number of contract services (can be dozens)
• Number of eligibility rules (multiple per service)
• Number of predefined outcomes and activities (can be hundreds)
• Complexity of contract grouping hierarchy
• Network latency between environments
• Use of UpdateExisting flag (slower than create-only)

Optimisation Tips

For faster execution:

1. Use ServiceTransferWithoutDomainRelationships if domain-area relationships unchanged
2. Run during off-peak hours
3. Use default flags when possible (no AddToExistingData or UpdateExisting)
4. Minimise test/template data in master data environment

For large service catalogs:

• Monitor console output for stalled operations
• Check for eligibility rule resolution failures
• Consider splitting into smaller deployments if needed
• Review contract service count (dozens of services can slow execution)

For repeated deployments:

• Use ServiceTransferWithoutDomainRelationships for service-only updates
• Skip unnecessary operations by choosing appropriate DataSet
• Consider datamanipulation tool for single-table updates

Troubleshooting

Grouping Parent References Not Set

Problem: Contract grouping created but mag_parentgrouping is NULL

Cause: Second pass (parent reference update) failed

Solution:

1. Check console output for "Updating grouping parent references" section
2. Verify parent grouping exists in target environment
3. Check for name mismatch between source and target
4. Ensure all groupings created before second pass begins

Contract Service Creation Fails

Problem: "Could not resolve [reference] for contract service"

Cause: Referenced entity doesn't exist in target

Solution:

1. Check operation order - contract types must exist before contracts
2. Verify funding contract exists before creating contract services
3. Check service type and service site exist in target
4. Review assessment type references
5. Ensure consent types created

Eligibility Rule Duplicates

Problem: Multiple eligibility rules with same name but different services

Cause: This is normal - composite key allows same name for different services

Solution:

• Review mag_contractserviceid field on rules
• Verify each rule is associated with correct service
• This is expected behavior if services require same eligibility logic

Predefined Activity Missing Service Reference

Problem: Predefined activity created but mag_service is NULL

Cause: Service reference couldn't be resolved

Solution:

1. Verify contract services operation completed successfully
2. Check service name in template matches target
3. Review console output for EntityReference resolution errors
4. Ensure service exists before creating predefined activities

Date Fields Set to Null

Problem: Contract or service date fields are NULL despite having dates in template

Cause: Source dates before January 1, 1850 (invalid dates)

Solution:

• Review source data for placeholder dates
• Update template data with valid dates (>= 1850-01-01)
• Re-run organizationsetup
• NULL is expected if source has invalid dates

PRIMHD Team Not Created

Problem: PRIMHD team from template not appearing in target

Cause: Duplicate name or GUID conflict

Solution:

1. Check console output for team creation errors
2. Verify team doesn't already exist with different GUID
3. Review idempotent behavior (skips if exists)
4. Use UpdateExisting if need to update existing team

Domain-Area Relationships Missing (ServiceTransfer)

Problem: Used ServiceTransfer but domain-area relationships not created

Cause: Relationship creation failed or was skipped

Solution:

1. Check console output for "Domain-Area relationships" section
2. Verify outcome domains and areas exist in target
3. Check for name resolution errors
4. Ensure domains and areas created before relationships
5. Review console for "Couldn't find matching domain or area in target"

Performance Degradation

Problem: ServiceTransfer taking much longer than expected (>10 minutes)

Cause: Large number of services, outcomes, or complex relationships

Solution:

1. Use ServiceTransferWithoutDomainRelationships if appropriate
2. Check for network latency issues
3. Review master data for excessive test/template data
4. Consider cleaning up unused predefined outcomes/activities
5. Monitor console to identify slow operation

Best Practices

Master Data Management

Service template environment:

1. Maintain production-like services:

   • Keep master data aligned with production services
   • Document service configuration standards
   • Use consistent naming conventions

2. Contract hierarchy:

   • Design logical grouping structure (2-3 levels max)
   • Use meaningful grouping names
   • Avoid circular parent references

3. Service configuration:

   • Set realistic dates (after 1850-01-01)
   • Configure assessment auto-creation appropriately
   • Define exit reason requirements
   • Set consent expiry days

4. Eligibility rules:

   • Use clear, descriptive rule names
   • Document eligibility logic
   • Test eligibility rules before deployment
   • Consider service-specific vs shared rules

5. Predefined outcomes:

   • Link outcomes to appropriate services
   • Set realistic durations
   • Configure domain/area/category associations
   • Test outcome creation flow

6. Predefined activities:

   • Configure timing appropriately (start after, due after)
   • Link to correct assessment tools
   • Set consent type requirements
   • Test activity auto-creation

Change Management

Before making service changes:

✅ Document current service configuration
✅ Identify impact of proposed changes
✅ Plan rollback strategy
✅ Test changes in development environment
✅ Get stakeholder approval
✅ Schedule deployment window
✅ Communicate to users

Service configuration versioning:

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

Testing workflow:

1. Make changes in master data environment
2. Deploy to development using ServiceTransfer
3. Test enrollment flow with new services
4. Verify eligibility rules work correctly
5. Test predefined outcome/activity auto-creation
6. UAT with end users
7. Deploy to production during scheduled maintenance

DataSet Selection Strategy

Use ServiceTransfer when:

• Setting up new environment
• Complete service infrastructure sync needed
• Outcomes framework changed alongside services
• First deployment to environment

Use ServiceTransferWithoutDomainRelationships when:

• Updating existing environment
• Outcome domain structure unchanged
• Only service configuration changed
• Performance optimisation needed
• Domain-area relationships already correct

Decision tree:

Need to deploy service configuration?
  ├─ Yes → New environment?
  │         ├─ Yes → ServiceTransfer (full setup)
  │         └─ No → Outcomes changed?
  │                  ├─ Yes → ServiceTransfer (include relationships)
  │                  └─ No → ServiceTransferWithoutDomainRelationships (faster)
  └─ No → Consider OutcomesFramework or datamanipulation

Validation Checklist

After ServiceTransfer deployment:

PRIMHD Configuration: ✅ PRIMHD teams created
✅ Team codes match template

Contract Infrastructure: ✅ Contract groupings created
✅ Parent grouping references set correctly
✅ Funding contract types present
✅ Funding contracts created with correct dates
✅ Contract services present and active

Eligibility: ✅ Eligibility rules created
✅ Age restrictions configured correctly
✅ Service associations correct

Supporting Tables: ✅ Contract service types present
✅ Contract service sites present
✅ Activity groups created
✅ Consent types present

Outcomes Framework: ✅ Outcome domains, areas, categories present
✅ Domain-area relationships created (if using ServiceTransfer)
✅ Area-category relationships created
✅ Predefined outcomes linked to services
✅ Predefined activities linked to outcomes and services

Integration Testing: ✅ Create test enrollment in contract service
✅ Verify eligibility rules enforced
✅ Add predefined outcome to plan
✅ Confirm predefined activities auto-create
✅ Test assessment tool linkage
✅ Verify consent type functionality

Incremental Updates

For ongoing service maintenance:

1. Update master data:

   • Make service configuration changes
   • Update eligibility rules as needed
   • Modify predefined outcomes/activities
   • Test changes

2. Deploy to dev:

   --DataSet "ServiceTransferWithoutDomainRelationships" --UpdateExisting
   

   • Test deployment
   • Verify updates applied

3. Deploy to test/UAT:

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

4. Production deployment:

   • Schedule deployment window
   • Communicate to users
   • Deploy with appropriate flags
   • Monitor for issues
   • Verify critical services still working

Rollback plan:

1. Keep backup of service configuration before changes
2. Document all modifications made
3. Test rollback in dev environment first
4. Be prepared to restore from backup if needed

Environment-Specific Considerations

Development:

• Use ServiceTransfer for complete rebuilds
• Test new service configurations
• Experiment with eligibility rules
• Validate predefined outcome flows

Test/UAT:

• Use ServiceTransfer or optimised variant
• Mirror production service catalog
• Add test-specific services if needed
• Validate changes before production

Production:

• Use ServiceTransferWithoutDomainRelationships when appropriate
• Always use AddToExistingData and UpdateExisting flags
• Schedule during maintenance windows
• Monitor console output carefully
• Validate critical services immediately after deployment

Disaster Recovery

Include service configuration in DR plan:

1. Backup master data:

   • Regular automated backups
   • Export service configuration before major changes
   • Store exports securely
   • Document master data environment details

2. Document deployment commands:

   • Save complete organizationsetup commands
   • Note DataSet options used
   • Document any special flags
   • Keep version history

3. Test recovery process:

   • Periodically restore to test environment
   • Verify service configuration restores correctly
   • Validate contract hierarchies
   • Test enrollment flows

4. Recovery sequence:

   • Restore Dataverse environment
   • Run organizationsetup with ServiceTransfer DataSet
   • Verify contract grouping hierarchy
   • Validate eligibility rules
   • Test predefined outcome functionality
   • Confirm PRIMHD teams present

Tables Summary

The ServiceTransfer DataSet affects 18 tables:

PRIMHD:

1. mag_primhdteam - PRIMHD teams

Contracts: 2. mag_grouping - Contract grouping 3. mag_contracttype - Funding contract types 4. mag_fundingcontract - Funding contracts 5. mag_contractservice - Contract services 6. mag_eligibilityrule - Service eligibility rules 7. mag_contractservicetype - Contract service types 8. mag_contractservicesite - Contract service sites

Outcomes Foundation: 9. mag_domain - Outcome domains 10. mag_outcomedomainindicator - Domain indicators 11. mag_outcomearea - Outcome areas 12. mag_outcomecategory - Outcome categories

Outcomes Relationships: 13. mag_mag_outcomearea_mag_domain - Domain-area relationships 14. mag_mag_outcomecategory_mag_outcomearea - Area-category relationships

Outcomes Templates: 15. mag_predefinedoutcome - Predefined outcomes 16. mag_predefinedactivity - Predefined outcome activities

Supporting: 17. mag_activitygroup - Activity groups 18. mag_consenttype - Consent types

The ServiceTransferWithoutDomainRelationships DataSet affects 17 tables (excludes #13: Domain-area relationships).

See Also

• organizationsetup - Overview
• organizationsetup - All DataSet
• organizationsetup - OutcomesFramework DataSet
• Navigator Platform CLI Introduction