Nonprofits

Migrate from AppSource Volunteer Management to the open-source build

This guide explains how to move an environment from the AppSource Volunteer Management solution (installed from the marketplace) to the open-source (OS) Volunteer Management build compiled from this repository.

Both solutions are published by Microsoft; they are distinguished by origin — the AppSource managed solution versus the OS build from the public GitHub repository. The AppSource solution is no longer supported and is being removed from AppSource, so existing customers and partners should migrate to the OS build.

Why a migration is needed

The OS build ships under its own identity so it can be installed side-by-side with the AppSource solution. Once the OS build is in place, the unsupported AppSource solution can be removed. The separate identities are:

Aspect	AppSource (marketplace)	Open-source build
Solution unique name	VolunteerManagement	volunteermanagementos
Solution display name	Volunteer Management	Volunteer Management (OS)
Plugin assembly	Plugins (token 8ad1edaac4bc000c)	PluginsOS (token 703f25cc8a15a472)
PCF controls	shipped & owned	shipped & owned (its own copies)

Because the identities differ, both solutions can coexist during the migration. Your data (volunteers, engagement opportunities, participations, etc.) lives on the shared Dataverse tables and is not deleted when the AppSource solution is removed — only the solution layer and its metadata are.

Before you start

• Take a full backup of the environment. The migration edits active form/view layers in place and deleting the AppSource solution is irreversible without a backup.
• Ensure you have System Administrator access to the target environment.
• Install the tools used below:
  • .NET SDK (to build the OS solution)
  • Power Platform CLI (pac)
  • Azure CLI (az) (used by the migration script to acquire a Dataverse token)
• Run all commands from the repository root.

Migration overview

1. Build and import the OS solution side-by-side with the AppSource solution.
2. Strip the AppSource PCF control references that block deletion, then publish.
3. Delete the unsupported AppSource solution.
4. Re-import/upgrade the OS solution.
5. Remove the active layers created in step 2 so the OS forms and controls take over.
6. Verify the result.

Steps 2, 3, 5, and 6 are automated by Deployment/Migrate-VolunteerManagementToOpenSource.ps1. See Deployment/README.md for the full script reference, parameters, and authentication options.

Step-by-step

1. Build and import the OS solution

dotnet build .\VolunteerManagement\VolunteerManagement\VolunteerManagement.cdsproj -c Release
pac solution import --path .\VolunteerManagement\VolunteerManagement\bin\Release\VolunteerManagement_managed.zip

The OS solution installs alongside the AppSource one because it uses a separate unique name (volunteermanagementos) and plugin assembly (PluginsOS).

2. Strip the AppSource PCF references and publish

The AppSource forms and views reference its PCF controls in the active (merged) layer. That Form -> Control dependency is Published and blocks deletion of the AppSource solution. This stage rewrites those active layers to substitute the default control, then runs PublishAllXml.

.\VolunteerManagement\Deployment\Migrate-VolunteerManagementToOpenSource.ps1 -EnvironmentUrl https://contoso.crm.dynamics.com -StripReferences

Tip: add -WhatIf to preview every change without applying it.

3. Delete the AppSource solution

.\VolunteerManagement\Deployment\Migrate-VolunteerManagementToOpenSource.ps1 -EnvironmentUrl https://contoso.crm.dynamics.com -DeleteAppSourceSolution

Before deleting, the script checks that:

• the open-source solution volunteermanagementos is installed,
• the target solution is managed, and
• every table in the target solution is also in another managed solution, such as volunteermanagementos or Common Data Model for Nonprofits. Deleting a managed solution deletes the tables that only it holds, together with their data.

The script doesn’t try to tell the AppSource build apart from an open-source build installed before the solution was renamed to volunteermanagementos. Both use the unique name VolunteerManagement, the same publisher, and the same plug-in assembly and signing key. Both are migrated the same way, and the table check above protects the data in either case.

If any check fails, the script stops and lists the reasons, including the tables that would be deleted. -Force overrides the checks; use it only with a verified backup.

4. Re-import / upgrade the OS solution

pac solution import --path .\VolunteerManagement\VolunteerManagement\bin\Release\VolunteerManagement_managed.zip --force-overwrite

--force-overwrite overwrites unmanaged customizations on the components in the solution, including changes you made to Volunteer Management forms. Export or document them first and reapply them in your own solution afterwards.

5. Restore the OS PCF controls

Step 2 rewrites forms and views through the Web API, which leaves an active (unmanaged) layer on each of them. A managed import does not replace that layer, so the forms keep showing the default controls instead of the OS-owned PCF controls. This stage removes the active layer of exactly the forms and views that step 2 rewrote (recorded in vm-migration-stripped.json), then publishes.

.\VolunteerManagement\Deployment\Migrate-VolunteerManagementToOpenSource.ps1 -EnvironmentUrl https://contoso.crm.dynamics.com -RestoreControls

Removing the active layer also removes any other unmanaged customization on those forms and views. Preview the list with -WhatIf and reapply needed customizations in your own solution.

6. Verify

.\VolunteerManagement\Deployment\Migrate-VolunteerManagementToOpenSource.ps1 -EnvironmentUrl https://contoso.crm.dynamics.com -Verify

The verification report lists the plugin assemblies, the owning solutions of each PCF control, and the SDK steps registered on PluginsOS. After a successful migration you should see only the PluginsOS assembly and the PCF controls owned by volunteermanagementos.

Authentication

By default the script acquires a Dataverse token with the Azure CLI (az account get-access-token). Sign in first with az login, or:

• pass a pre-acquired bearer token with -AccessToken <token>, or
• point -AzCommand at an alternate/isolated Azure CLI executable for a non-default sign-in.

Safety and rollback

• Every stage of the script is opt-in; running it with no stage switch does nothing.
• The destructive stages support -WhatIf and -Confirm (the script declares ConfirmImpact = 'High'), so you can preview each PATCH / publish / delete.
• If a step fails, restore from the backup taken before step 1 and retry.

Related

• Deployment/README.md — full migration script reference.
• Deployment/Migrate-VolunteerManagementToOpenSource.ps1 — the migration script.

This site is open source. Improve this page.