The ALM Accelerator uses JSON formatted files for updating connection references, setting environment variables, and setting permissions for Azure Active Directory (AD) groups and Microsoft Dataverse teams, in addition to sharing canvas apps and updating ownership of solution components such as Power Automate flows. The instructions in this article are optional and depend on what type of components your solution pipelines deploy. For instance, if your solution contains only Dataverse tables, columns, and model-driven apps with no per-environment configuration or data needed, some of these steps might not be necessary and can be skipped. The following configuration files allow you to fully automate the deployment of your solutions and specify how to configure items that are specific to the environment to which the solution is being deployed.

For an example of configuration and data deployment configuration, go to the ALMAcceleratorSampleSolution deployment settings and custom deployment settings.

The following documentation is intended to be a step-by-step process for setting up deployment configuration files manually. However, we recommend that you use the in-app feature to generate this information on export of your solution. This article provides details and context for the actions that are performed by the ALM Accelerator for Power Platform app and pipelines, and acts as a reference for administrators who want to know the specifics of each step in the process.

When storing the customDeploymentSettings.json in the root of the config directory, the same configuration will apply to all environments. Assuming that you're using file transformation or token replacement pipeline tasks to store all of the environment-specific information, you can specify the environment-specific values in your pipeline variables. However, you can also create environment-specific customDeploymentSettings.json files by creating subdirectories in the config directory with the name of the environment, to allow for more flexibility. The directory name in this case must match the EnvironmentName pipeline variable you created when setting up your pipeline (validate, test, production). If no environment-specific deployment settings JSON and directory are found, the pipelines will revert to the configuration in the root of the config directory.

Additionally, you can create user-specific configuration files (for example, the JohannaDev directory in the preceding image) for individual developers to use when importing unmanaged solutions from source control. When the user imports an unmanaged solution from source control in the ALM accelerator, they're presented with the option to choose a specific configuration.

The deployment settings JSON file is used to configure connection references and environment variables.

To create the deployment settings JSON file, follow these steps:

Copy the preceding JSON code sample to a new file named deploymentSettings.json.

Create a new folder named config and save the new file under the config folder in Git.

The connection reference property in the customDeploymentConfiguration.json is ConnectionReferences. The connection reference property is used for setting connection references in your solution to specific connections after the solution is imported. Additionally, the ConnectionReferences are used to enable flows after the solution is imported, based on the owner of the connection specified in the variable.

Create the connections manually in your target environments.

Copy the IDs for the connections, to use in the following JSON value.

The logical name for the connection reference can be obtained from the connection reference component in your solution.

The connection ID can be obtained via the URL of the connection after you create it. For example, the ID of the following connection is 9f66d1d455f3474ebf24e4fa2c04cea2 where the URL is 'https://.../connections/shared_commondataservice/9f66d1d455f3474ebf24e4fa2c04cea2/details'.

After you've gathered the connection reference schema names and connection IDs, go to the customDeploymentSettings.json and paste the values into the ConnectionReferences property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create the connection [connection_reference_logicalname]. For this example, the pipeline variable is named connection.cat_CDS_Current.

Set the value to the connection ID you gathered earlier, and then select Keep this value secret if you want to ensure that the value isn't saved as plain text.

Where applicable, repeat these steps for each solution and pipeline you create.

The environment variable property in the customDeploymentConfiguration.json is EnvironmentVariables. The environment variable property is used for setting Dataverse environment variables in your solution after the solution is imported into an environment.

Important

When exporting and source-controlling solutions, environment variable values are exported with the solution. In some cases, this can be a security risk when the environment variables contain sensitive information. We recommend that you not store sensitive information in environment variables. One way to ensure that your environment variable values aren't source-controlled is to create a solution specifically for environment variable values in your development environments, and set the current value of the environment variables in that solution. This will prevent the current values from being exported during the solution export and being stored in source control.

The format of the JSON for these variables takes the form of an array of name/value pairs.

After you've gathered the environment variable schema names and values, go to the customDeploymentSettings.json and paste the JSON in the EnvironmentVariables property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create a pipeline variable for each token in your configuration, for example variable.cat_TextEnvironmentVariable.

Set the value to the environment variable value for that specific environment, and then select Keep this value secret if you want to ensure that the value isn't saved as plain text.

Where applicable, repeat these steps for each solution and pipeline you create.

The custom deployment settings JSON file contains the configuration settings required to automate the deployment of your solution. This file contains the configuration for activating flows on behalf of a user, specifying ownership of flows, sharing canvas apps with Azure AD Groups, and creating Dataverse group teams after deployment. The following sample is a custom deployment settings JSON file that will provide your pipelines with the necessary information required to configure a solution after it's been deployed to an environment.

Copy the preceding JSON to a new file named customDeploymentSettings.json.

If you haven't already, create a new directory named config and save the new file under the config folder in Git.

The environment variable property in the customDeploymentConfiguration.json is DefaultEnvironmentVariables. The DefaultEnvironmentVariables variable is used in the export pipeline for setting Dataverse default environment variables in your solution when the solution is exported and stored in source control.

Note

The default environment variables settings only apply if the export pipeline is configured with the pipeline variable VerifyDefaultEnvironmentVariableValues = true.

The format of the JSON for these variables takes the form of an array of name/value pairs.

After you've gathered the environment variable schema names and values, go to the customDeploymentSettings.json and paste the JSON in the DefaultEnvironmentVariables property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create a pipeline variable for each of the tokens in your configuration, for example defaultvariable.cat_TextEnvironmentVariable.

As necessary, repeat these steps for each solution and pipeline you create.

The Azure AD group canvas configuration property in the customDeploymentConfiguration.json is AadGroupCanvasConfiguration. The Azure AD group canvas configuration property is used for sharing canvas apps in your solution with specific Azure AD groups after the solution is imported into an environment.

The format of the JSON for these variables takes the form of an array of objects. The roleName can be one of CanView, CanViewWithShare, and CanEdit.

The schema name for the canvas app can be obtained from the canvas app component in your solution.

The Azure AD group ID can be obtained from the Group blade in Azure AD from the Azure portal.

After you've gathered the environment variable schema names and values, go to the customDeploymentSettings.json and paste the JSON in the AadGroupCanvasConfiguration property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create a pipeline variable for each of the tokens in your configuration, for example canvasshare.aadGroupId.

Set the value to the Azure AD group ID to which the app must be shared for that specific environment, and then select Keep this value secret if you want to ensure that the value isn't saved as plain text.

Where applicable, repeat these steps for each solution and pipeline you create.

The Azure AD group canvas configuration property in the customDeploymentConfiguration.json is AadGroupTeamConfiguration. The Azure AD group canvas configuration property is used for mapping Dataverse teams and roles to specific Azure AD groups in your solution with specific Azure AD groups after the solution is imported into an environment.

Note

The security roles must be added to your solution if they aren't manually created in the target environment.

The formats of the JSON for these variables take the form of an array of objects. One or many roles can be applied to a team. These roles provide permissions to solution components required by the users in the group.

The Dataverse team name can be any existing team or a new team to be created in Dataverse and mapped to an Azure AD group after the solution is imported via the pipeline.

The Azure AD group ID can be obtained from the Group blade in Azure AD from the Azure portal.

After you've gathered the team names, Azure AD group IDs, and roles, go to the customDeploymentSettings.json and paste the JSON in the AadGroupTeamConfiguration property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create a pipeline variable for each of the tokens in your configuration, for example team.aadSecurityGroupId.

Set the value to the Azure AD group ID to associate with the team in Dataverse, and then select Keep this value secret if you want to ensure that the value isn't saved as plain text.

Where applicable, repeat these steps for each solution and pipeline you create.

The solution component ownership property in the customDeploymentConfiguration.json is SolutionComponentOwnershipConfiguration. The solution component ownership property is used for assigning ownership of solution components to Dataverse users after the solution is imported into an environment. Assigning component ownership is useful for components such as flows that by default will be owned by the service principal user when the solution is imported by the pipeline, and organizations want to reassign them after import. Additionally, the SolutionComponentOwnershipConfiguration property is used to enable flows that don't have any connection references. The flow will be enabled by the user specified when no connection references are found to use to enable the flow.

Note

The current pipeline only implements the ability to set ownership of flows.

The format of the JSON for these variables takes the form of an array of objects.

After you've gathered the component type codes, unique name of the components, and owner email addresses, go to the customDeploymentSettings.json and paste the JSON in the AadGroupTeamConfiguration property.

If you're using the Replace Tokens extension and adding tokens in your configuration as in the preceding example, open the pipeline for your solution, and then select Edit > Variables.

On the Pipeline Variables screen, create a pipeline variable for each of the tokens in your configuration, for example owner.ownerEmail.

Set the value to the email address of the owner of the component, and then select Keep this value secret if you want to ensure that the value isn't saved as plain text.

Where applicable, repeat these steps for each solution and pipeline you create.

In many cases, you'll want to import configuration or seed data into your Dataverse environment initially after deploying your solution to the target environment. The pipelines are configured to import data by using the Configuration Migration tool, available via NuGet. To add configuration data for your pipeline, use the following steps. For more information about the Configuration Migration tool, go to Manage configuration data.

Clone the Azure DevOps repo where your solution is to be source-controlled and where you created your solution pipeline YAML to your local machine.

If you haven't already created a config directory, under your solution folder, create a new directory named config under the config folder.

Install the Configuration Migration tool following the instructions in Download tools from NuGet.

Open the Configuration Migration tool, select Create schema, and then select Continue.

Sign in to the tenant from which you want to export your configuration data.

Select your environment.

Select the tables and columns you want to export for your configuration data.

Select Save and Export and save the data to the directory path config\ConfigurationMigrationData in your local Azure DevOps repo under the solution folder for which this configuration data is to be imported.

Note

The pipeline will look for this specific folder to run the import after your solution is imported. Ensure that the name of the folder and the location are the same as the following screenshot.

Similar to the note earlier in this article regarding specific configuration files for each environment, the preceding steps create configuration data that will be deployed to all environments. However, if you have specific configuration data for each environment, you can create subdirectories in the config directory with the name of the environment to allow for more flexibility. The directory name in this case must match the EnvironmentName pipeline variable you created when setting up your pipeline (validate, test, production). If no environment-specific configuration data and directory are found, the pipelines will revert to the configuration data in the root of the config directory.

When prompted to export the data, select Yes.

Choose the same location for your exported data, select Save, then select Export Data.

When the export is complete, unzip the files from the data.zip file to the ConfigurationMigrationData directory, and delete the data.zip and SampleData.xml files.

Finally, commit the changes with your data to Azure DevOps.

Configure user permissions