organizationsetup

Command: organizationsetup

Configures Navigator environments by copying reference data, system configuration, and master data from a template environment to a target environment. This command automates the setup of foundational configuration required for Navigator deployments.

Overview

The organizationsetup command is an environment configuration tool that establishes the foundational reference data and system settings needed for a Navigator deployment. Unlike data migration tools that move business data, this command copies reference data (lookup values, configuration settings, access templates) from a master data environment to prepare a new or existing environment.

This command always operates on two environments simultaneously:

Master Data Environment - The source environment containing template/reference data
Target Environment - The environment being configured

When to Use

Use organizationsetup when you need to:

✅ Set up a new Navigator environment with standard reference data
✅ Copy outcomes framework configuration from one environment to another
✅ Transfer service and contract definitions between environments
✅ Synchronise reference data across multiple Navigator instances
✅ Restore reference data after an environment refresh
✅ Establish consistent configuration across development, test, and production environments

Command Syntax

.\WhanauTahi.Xpm.Tooling.exe organizationsetup 
    --MasterDataUrl <master-data-url>
    --EnvironmentUrl <target-url>
    --ClientId <client-id>
    [--Secret <client-secret>]
    [--DataSet <dataset-option>]
    [--AddToExistingData]
    [--UpdateExisting]

Parameters

Parameter	Required	Description
`MasterDataUrl`	Yes	URL of the source environment containing template/reference data (e.g., `https://orgname.crm6.dynamics.com`)
`EnvironmentUrl`	Yes	URL of the target environment to be configured (e.g., `https://targetorg.crm6.dynamics.com`)
`ClientId`	Yes	Azure AD application (client) ID with permissions to both environments
`Secret`	No	Client secret for authentication. If omitted, uses default secret from configuration
`DataSet`	No	Controls which operations are performed. Options: `All`, `OutcomesFramework`, `ServiceTransfer`, `ServiceTransferWithoutDomainRelationships`. Default: `All`
`AddToExistingData`	No	Allow adding data even if target environment already contains records. Default: `false`
`UpdateExisting`	No	Update existing records instead of skipping them. Default: `false`

DataSet Options

The DataSet parameter controls which configuration operations are performed. Choose the option that matches your scenario:

All (Complete Setup)

Use when: Setting up a brand new environment from scratch

Performs 40+ operations including:

Access teams and standard teams
System configuration and autonumber records
All reference data (age groups, ethnicities, tribes, education levels, etc.)
PRIMHD configuration
Contract and service definitions
Complete outcomes framework
Predefined outcomes and activities

See detailed documentation →

OutcomesFramework

Use when: Adding or updating only outcomes-related configuration

Performs 8 operations:

Outcome domains and domain indicators
Outcome areas and categories
Domain-area and area-category relationships
Predefined outcomes and activities

See detailed documentation →

ServiceTransfer

Use when: Migrating service and contract configuration with full outcomes framework

Performs 18 operations:

PRIMHD teams
Contract types, grouping, service types, and service sites
Funding contracts and contract services
Service eligibility rules
Complete outcomes framework
Activity groups and consent types
Predefined outcomes and activities

See detailed documentation →

ServiceTransferWithoutDomainRelationships

Use when: Migrating services when domain relationships already exist or aren't needed

Same as ServiceTransfer (18 operations) but excludes:

Domain-area relationships
Area-category relationships

See detailed documentation →

How It Works

Dual-Environment Architecture

The command establishes connections to both the master data and target environments simultaneously:

┌─────────────────────┐
│  Master Data Env    │
│  (Template Source)  │
└──────────┬──────────┘
           │
           │ Reads reference data
           │
           ▼
    ┌──────────────┐
    │ Organisation │
    │    Setup     │
    │   Command    │
    └──────┬───────┘
           │
           │ Writes configuration
           │
           ▼
┌──────────────────────┐
│   Target Env         │
│  (Being Configured)  │
└──────────────────────┘

Operation Flow

For each table being copied:

Check Target State
- If AddToExistingData is false and target has data, skip the table entirely
- If UpdateExisting is false and record exists, skip the record
Retrieve Template Data
- Query all active records from master data environment
- Include inactive records if specified (e.g., assessment tools)
Process Each Record
- Check if record already exists in target (by GUID or name)
- Resolve all EntityReference fields by looking up names in target
- Create or update record based on configuration flags
Console Feedback
- + or C = Record created
- - = Record skipped (already exists)
- U = Record updated
- "done" = Operation completed

EntityReference Resolution

The command handles lookups between environments by name resolution:

// Template environment lookup
Source: mag_contractservice -> "Mental Health Service A"

// Find in target environment
Target: mag_contractservice where mag_name = "Mental Health Service A"

// Create resolved reference
EntityReference -> Target GUID for "Mental Health Service A"

This ensures referential integrity even when GUIDs differ between environments.

Real-World Scenarios

Scenario 1: New Production Environment Setup

Context: You're deploying Navigator to a new production environment and need all reference data.

.\WhanauTahi.Xpm.Tooling.exe organizationsetup `
    --MasterDataUrl "https://masterdata.crm6.dynamics.com" `
    --EnvironmentUrl "https://newprod.crm6.dynamics.com" `
    --ClientId "12345678-1234-1234-1234-123456789abc" `
    --Secret "your-secret-here" `
    --DataSet "All"

Result: Complete environment setup with all reference data, teams, system configuration, and outcomes framework.

Scenario 2: Outcomes Framework Update

Context: You've updated the outcomes framework in your master data environment and need to sync it 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

Result: Outcomes domains, areas, categories, and predefined outcomes updated to match master data.

Scenario 3: Service Configuration Migration

Context: Migrating contract and service setup from one environment to another, including outcomes.

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

Result: Services, contracts, eligibility rules, and full outcomes framework copied from source to target.

Scenario 4: Post-Refresh Reference Data Restore

Context: After refreshing a sandbox from production, you need to restore development-specific reference data.

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

Result: Development reference data added/updated in refreshed environment.

Critical Warnings

⚠️ Fixed GUIDs - DO NOT CHANGE

The following GUIDs are hard-coded in the Navigator codebase and must never be changed:

Team Template	GUID
Individual Team Template	`8F1D681D-B770-E711-810F-000C2975F09B`
Family Group Team Template	`1EFF884E-C070-E711-810F-000C2975F09B`
Plan Team Template	`7D42E7A9-5568-E711-8108-000C2975F09B`

Standard Team	GUID
Intake Team	`C030632C-D4D4-4F3C-9E3F-7452D834834A`

Why this matters: These GUIDs are referenced in plugins, workflows, and code. Changing them will break Navigator functionality.

⚠️ Assessment Tools Load Inactive

Assessment tools are always created in an inactive state (statecode=1, statuscode=809730000). This is intentional.

Why: Activating an assessment tool triggers plugin step registration. Users must manually activate each assessment tool to ensure proper plugin configuration.

Action required: After running organizationsetup, manually activate required assessment tools in the target environment.

⚠️ Autonumber Position Reset

Autonumber records always set wtl_currentposition = 0 in the target environment, regardless of the source value.

Why: Current position is environment-specific and should not be copied. Starting at 0 ensures no number conflicts.

⚠️ Date Validation

Date fields on contracts and services are validated against a historical lower limit (January 1, 1850). Dates before this are set to null.

Why: Prevents invalid or corrupted date values from being copied.

Best Practices

1. Master Data Environment Strategy

Maintain a dedicated master data environment containing:

Approved reference data values
Standard outcomes framework
Template contracts and services
Verified configuration settings

Update this environment through a controlled process, then propagate changes to other environments using organizationsetup.

2. Pre-Flight Checks

Before running the command:

✅ Verify both environments are accessible
✅ Confirm ClientId has permissions to both environments
✅ Back up target environment if using UpdateExisting
✅ Review which DataSet option matches your needs
✅ Test with AddToExistingData=false first (safer default)

3. Idempotent Operations

The command is safe to re-run. By default:

Existing records are skipped (console shows -)
Only missing records are created (console shows + or C)

Use UpdateExisting flag only when you intentionally want to overwrite existing data.

4. Console Output Monitoring

Watch console output for progress indicators:

Funding contracts ...
C++-U+C+-
 done

C or + = Created successfully
- = Skipped (already exists)
U = Updated existing record
Errors will display with details

5. Composite Key Awareness

Some tables use composite keys for uniqueness:

Eligibility Rules: mag_eligibilityrulename + mag_contractserviceid
Predefined Activities: mag_name + mag_service

The command handles these automatically, but be aware that records with the same name but different lookup values are treated as distinct.

6. Two-Pass Processing

Contract grouping uses two-pass processing:

First pass: Create all group records without parent references
Second pass: Update parent references

Console output will show both passes. This is normal and ensures hierarchical data is created correctly.

Performance Considerations

Typical Execution Times

DataSet Option	Approximate Duration	Records Processed
All	5-10 minutes	500-2000+ records
OutcomesFramework	1-3 minutes	50-200 records
ServiceTransfer	3-7 minutes	200-500 records

Factors affecting duration:

Network latency between environments
Volume of reference data in master environment
Number of existing records in target (when using UpdateExisting)

Optimise for Large Datasets

Run during off-peak hours for large All operations
Use specific DataSet options when possible (faster than All)
Monitor console output for stalled operations

Troubleshooting

Command Shows "Invalid DataSet"

Problem: Error message lists valid DataSet values

Solution: Check DataSet parameter spelling. Valid values:

All
OutcomesFramework
ServiceTransfer
ServiceTransferWithoutDomainRelationships

Case-sensitive - use exact capitalisation shown above.

Records Not Created (All Show `-`)

Problem: Console output shows all records skipped with -

Cause: Target environment already has data and AddToExistingData=false (default)

Solution: Add --AddToExistingData flag to allow creation in populated environments

EntityReference Resolution Failures

Problem: Console shows "Could not resolve [entity] reference"

Cause: Referenced record doesn't exist in target environment

Solution:

Ensure prerequisite data exists in target
Run operations in correct order (use All DataSet for proper sequencing)
Check that referenced records exist in master data environment

Authentication Failures

Problem: Cannot connect to one or both environments

Solution:

Verify ClientId has permissions to both environments
Check Secret is correct and not expired
Confirm environment URLs are accessible
Ensure app registration has required API permissions

Duplicate Records Created

Problem: Multiple records with same name created

Cause: Using AddToExistingData without understanding composite keys

Solution:

For eligibility rules and predefined activities, duplicates may be valid (composite keys)
For other tables, check if UpdateExisting should be used instead

Tables Affected

The organizationsetup command affects 50+ tables depending on DataSet option. See individual DataSet documentation for complete table lists:

organizationsetup

Overview

When to Use

Command Syntax

Parameters

DataSet Options

All (Complete Setup)

OutcomesFramework

ServiceTransfer

ServiceTransferWithoutDomainRelationships

How It Works

Dual-Environment Architecture

Operation Flow

EntityReference Resolution

Real-World Scenarios

Scenario 1: New Production Environment Setup

Scenario 2: Outcomes Framework Update

Scenario 3: Service Configuration Migration

Scenario 4: Post-Refresh Reference Data Restore

Critical Warnings

⚠️ Fixed GUIDs - DO NOT CHANGE

⚠️ Assessment Tools Load Inactive

⚠️ Autonumber Position Reset

⚠️ Date Validation

Best Practices

1. Master Data Environment Strategy

2. Pre-Flight Checks

3. Idempotent Operations

4. Console Output Monitoring

5. Composite Key Awareness

6. Two-Pass Processing

Performance Considerations

Typical Execution Times

Optimise for Large Datasets

Troubleshooting

Command Shows "Invalid DataSet"

Records Not Created (All Show -)

EntityReference Resolution Failures

Authentication Failures

Duplicate Records Created

Tables Affected

See Also

Records Not Created (All Show `-`)