Best Practices

Version Control

Store Everything in Git

• Solution XML (extracted)
• Flowon packages (.flop)
• Data specification files
• Mapping files (per environment)
• Extracted business data
• Pipeline definitions

Branch Strategy

main (production)
├── develop (integration)
│   ├── feature/new-workflow
│   ├── feature/api-update
│   └── bugfix/validation-error
└── hotfix/critical-fix

Environment Management

Maintain Separate Mappings

mappings/
├── development/
│   ├── configuration.datamap.xml
│   ├── entity.datamap.xml
│   ├── localizedresources.datamap.xml
│   └── serviceconnection.datamap.xml
├── uat/
│   ├── configuration.datamap.xml
│   ├── entity.datamap.xml
│   ├── localizedresources.datamap.xml
│   └── serviceconnection.datamap.xml
└── production/
    ├── configuration.datamap.xml
    ├── entity.datamap.xml
    ├── localizedresources.datamap.xml
    └── serviceconnection.datamap.xml

Use Environment Variables for Secrets

# Never commit credentials
export FLOWON_CONNECTION_STRING="AuthType=ClientSecret;..."

Deployment Safety

Pre-Deployment Checklist

1. ✅ Disable plugins before data migration
2. ✅ Backup target environment
3. ✅ Verify mapping files are correct
4. ✅ Test in UAT first
5. ✅ Have rollback plan ready

Plugin Management During Deployment

# 1. Disable plugins (environment-wide)
flowon-dynamics disable-plugins --connectionstring "$CONNECTION_STRING"

# 2. Import solution, package and data
flowon-dynamics import \
  --connectionstring "$CONNECTION_STRING" \
  --solution-file-path "./artifacts/solutions/MyProject_managed.zip" \
  --package-file-path "./artifacts/flowon/MyProject.flop" \
  --map-file-path "./mappings/production/configuration.datamap.xml"

# 3. Re-enable plugins (environment-wide)
flowon-dynamics enable-plugins --connectionstring "$CONNECTION_STRING"

Data Management

Separate Reference Data from Transactional

• Reference data: Countries, statuses, templates → Version controlled
• Transactional data: Customers, orders → NOT version controlled

Use Data Specs for Consistency

• Define which entities to extract
• Specify import behaviors
• Document dependencies

Troubleshooting

Common Issues

Issue	Cause	Solution
Import fails with GUID mismatch	Records have different IDs	Use entity mapping files
Plugin errors after deployment	Plugin still disabled	Run enable-plugins command
Localization not showing	LCID mismatch	Verify localized resource map
Service connection fails	Wrong credentials	Update service connection map

Verbose Logging

flowon-dynamics import \
  --log-level Verbose \
  --connectionstring "$CONNECTION_STRING" \
  --solution-file-path "..." 2>&1 | tee deployment.log

---

Quick Reference

Common Workflows

Initial Setup:

# 1. Install tools
dotnet tool install --global FlowOn.Xrm.Tools.CommandLine

# 2. Generate mapping files from an exported .flop package
flowon-dynamics generate-mappings \
  --project-file-path "./artifacts/flowon/MyProject.flop" \
  --output-directory "./mappings/dev"

# 3. Copy and modify for target environments
cp -r ./mappings/dev ./mappings/uat
cp -r ./mappings/dev ./mappings/production
# Edit target values in each environment's files

Daily Export:

flowon-dynamics export \
  --connectionstring "$CONNECTION_STRING" \
  --project-name "MyProject" \
  --output-directory "./artifacts" \
  --solution-managed --solution-unmanaged \
  --data-spec-file-path "./specs/data-spec.xml"

Deploy to Environment:

flowon-dynamics import \
  --connectionstring "$CONNECTION_STRING" \
  --solution-file-path "./artifacts/solutions/MyProject_managed.zip" \
  --package-file-path "./artifacts/flowon/MyProject.flop" \
  --map-file-path "./mappings/production/configuration.datamap.xml" \
  --data-file-path "./artifacts/data/crm_documenttype.xml"

Version Bump:

flowon-dynamics increment-solution-version \
  --connectionstring "$CONNECTION_STRING" \
  --solution "MyProject" \
  --version Minor

---

Project Structure Recommendation

my-project/
├── .github/
│   └── workflows/
│       └── deploy.yml            # GitHub Actions pipeline
├── azure-pipelines.yml           # Azure DevOps pipeline
├── specs/
│   └── data-spec.xml             # Data extraction specification
├── mappings/
│   ├── development/
│   │   ├── configuration.datamap.xml
│   │   ├── entity.datamap.xml
│   │   ├── localizedresources.datamap.xml
│   │   └── serviceconnection.datamap.xml
│   ├── uat/
│   │   └── ...
│   └── production/
│       └── ...
├── artifacts/                    # Generated (gitignored)
│   ├── solutions/
│   ├── flowon/
│   └── data/
└── README.md

Security Recommendations

Connection String Security

1. Never commit credentials to version control
2. Use environment variables or secret management
3. Create separate service accounts per environment
4. Use least privilege principle for service accounts

Service Account Permissions

Environment	Required Roles
Development	System Administrator (for full export)
UAT	System Customizer, Logic API Customizer
Production	System Customizer, Logic API Customizer

Audit Trail

• All deployments logged with timestamps
• Git history provides change tracking
• Pipeline logs capture deployment details