Deploy & ALM

Deploy & ALM best practices

Habits that make Logic Fabric deployments predictable, repeatable and safe.

Good ALM makes a release unremarkable: the same files, the same commands, the same result in every environment. These practices help you get there with the Logic Fabric CLI.

Source control

Commit everything a release needs: the unmanaged solution (to see what changed), the Logic Fabric package, the data specification, and one folder of data map files per environment.
Keep secrets out. Connection strings and production API keys belong in your pipeline’s secret store, not in data map files in the repository.
Pin the CLI version with a .NET tool manifest so every machine and pipeline uses the same one.

Suggested layout:

contoso-service/
├── .config/dotnet-tools.json
├── azure-pipelines.yml              (or .github/workflows/release.yml)
├── specs/reference-data.xml
├── mappings/
│   ├── uat/   configuration, entity, localizedresources, serviceconnection .datamap.xml
│   └── prod/  same files, production values (secrets injected at run time)
└── solution/                        unmanaged solution, for review

Environments

Build once, deploy many times. Export from development once per release and import the same files into test and production. Don’t export from test to production.
Deploy managed solutions to test and production. Develop only in development.
Increase the solution version on every release. Import skips a managed solution when the target already has the same or a newer version, so an unchanged version means unchanged customizations. Use increment-solution-version in the build.
Leave --override-unmanaged-customizations off by default. Turn it on deliberately when you want to remove unmanaged changes someone made on top of your managed components in a target environment.
Review data map files whenever the project gains a configuration value, service connection, localized resource or record reference. Run generate-mappings on the new package and compare it with your environment folders.

Reference data

Move reference and configuration records with a data specification; never move transactional data.
Make sure every exported table has unique record names, because records are matched by name.
Give every lookup column an import behavior, so a missing referenced record has a predictable result.

Logic API

Publish API drafts in development before exporting. publish-api refuses a draft with issues, which keeps broken APIs out of the release.
Generate the OpenAPI schema with generate-openapi in the build and keep it with the release, so app teams always have the schema of what is deployed.

Pipelines

Rely on exit codes: every command exits with 1 on failure, and import stops at the first failed step.
Use --log-level info in pipelines; switch to verbose when you investigate.
Put an approval in front of production.
If you disable Logic Fabric plug-in steps for a bulk data load, always enable them again, even when the load fails.

Troubleshooting

Symptom	Likely cause	What to do
`Project '…' was not found in the Dataverse environment.`	Wrong project name or environment.	Run `projects` and copy the exact name.
The solution step is skipped	The target already has the same or a newer version of the managed solution.	Increase the version in development and export again.
`Could not import solution file '…'; nothing else was imported.`	The solution import failed, for example because of a missing dependency.	Run with `--log-level verbose`, fix the cause, run again.
Logic uses development URLs in production	Data map files weren’t passed, or Target values weren’t edited.	Pass the environment’s files with `-m`, or use `apply-mappings`.
Data import stops with a missing-reference error	A lookup with `FailIfNotExists` has no matching record.	Import the referenced data first, or change the import behavior.
`This draft can't be published because it has N issues.`	The API draft has open issues.	Open it in API Studio, fix the issues, save, publish again.