README.md

Power Apps Package Deployer Template

A base template that introduces additional functionality when deploying Power Apps packages with the Package Deployer.

This project's aim is to build a powerful base Package Deployer template that simplifies common Power Apps package deployment tasks.

Table of contents

• Installation
• Usage
  • SLAs (classic)
    • Deactivate SLAs during import
    • Set SLAs as default
  • Processes
    • Set process states
  • SDK Steps
    • Set SDK step states
  • Connectors
    • Set base URLs
  • Connection references
    • Set connection references
  • Environment variables
    • Set environment variables
  • Data
    • Import data
  • Word templates
    • Import word templates
  • Attribute specific functionality
    • Set auto-number seed values
  • Mailboxes
    • Update, approve, test and enable shared mailboxes
• Azure Pipelines
• Contributing
• Licence

Installation

Add a NuGet reference to the Capgemini.PowerApps.PackageDeployerTemplate package in your Package Deployer package project. For more information on how to create the project, refer to Microsoft documentation

Update your PackageTemplate file (created by following the Microsoft documentation) to inherit from PackageTemplateBase e.g.

    public class PackageTemplate : PackageTemplateBase
    {
    }

Usage

All configuration for the package is placed within a <templateconfig> element in your package's ImportConfig.xml file.

SLAs (classic)

Note: this functionality is for the old SLA component - not the new SLA KPI component.

Deactivate SLAs during import

Deploying SLAs to an instance where they are already activated can cause problems during solution import. The package template will automatically deactivate all SLAs pre-deployment and activate all SLAs post-deployment. If you want to disable this functionality, you can add an activatedeactivateslas attribute to the <templateconfig> element.

<templateconfig activatedeactivateslas="false">
</templateconfig>

Set SLAs as default

Set SLAs as default after the deployment by setting the isdefault attribute on an <sla> element.

<templateconfig>
    <slas>
        <sla name="The name of the SLA<" isdefault="true" />
    </slas>
</templateconfig>

Processes

Set process states

All processes within the deployed solution(s) are activated by default after the deployment. You can manually set the state of processes after the deployment by setting the state attribute on a <process> element.

<templateconfig>
    <processes>
        <process name="The name of the process" state="Inactive" />
    </processes>
</templateconfig>

If your deployment is running as an application user then you may face some issues if your solution contains flows. If you wish to continue deploying as an application user, you can pass the LicensedUsername runtime setting to the Package Deployer (or set the PACKAGEDEPLOYER_SETTINGS_LICENSEDUSERNAME environment variable) and this user will be impersonated for flow activation.

You can also activate or deactivate processes that are not in your package by setting the external attribute to true on a <process> element. Be careful when doing this - deploying your package may introduce side-effects to an environment that make it incompatible with other solutions.

SDK steps

Set SDK step states

All SDK steps within the deployed solution(s) are activated by default after the deployment. You can manually set the state of SDK steps after the deployment by setting the state attribute on an <sdkstep> element.

<templateconfig>
    <sdksteps>
        <sdkstep name="The name of the SDK step" state="Inactive" />
    </sdksteps>
</templateconfig>

You can also activate or deactivate SDK steps that are not in your package by setting the external attribute to true on an <sdkstep> element. Be careful when doing this - deploying your package may introduce side-effects to an environment that make it incompatible with other solutions.

Connectors

Set base URLs

You can set the base URL (scheme, host, base path) for custom connector either through environment variables (for example, those exposed on Azure Pipelines from your variables or variable groups) or through Package Deployer runtime settings.

Environment variables must be prefixed with PACKAGEDEPLOYER_SETTINGS_CONNBASEURL_ and followed by the connector name (not display name). Similarly, runtime settings must be prefixed with ConnBaseUrl: and followed by the connector name (not display name). For example, if a custom connector name was new_testconnector, this could be set via either of the following:

Environment variable

$env:PACKAGEDEPLOYER_SETTINGS_CONNBASEURL_new_testconnector = "https://new-url.com/api"

Import-CrmPackage [...]

Runtime setting

$runtimeSettings =  "ConnBaseUrl:new_testconnector=https://new-url.com/api"

Import-CrmPackage [...] –RuntimePackageSettings $runtimeSettings

The runtime setting takes precedence if both an environment variable and runtime setting are found for the same connection reference.

To get your custom connector name, either query the web API for https://[your-environment].dynamics.com/api/data/v9.2/connectors and use the name property or if your solution is unpacked, use the name property in the .xml under the Connectors/ directory.

Connection references

Set connection references

You can set connections for connection references either through environment variables (for example, those exposed on Azure Pipelines from your variables or variable groups) or through Package Deployer runtime settings.

Environment variables must be prefixed with PACKAGEDEPLOYER_SETTINGS_CONNREF_ and followed by the logical name. Similarly, runtime settings must be prefixed with ConnRef: and followed by the connection reference logical name. For example, if a connection reference logical name was devhub_sharedvisualstudioteamservices_ca653, this could be set via either of the following:

Environment variable

$env:PACKAGEDEPLOYER_SETTINGS_CONNREF_DEVHUB_SHAREDVISUALSTUDIOTEAMSERVICES_CA653 = "shared-visualstudiot-44dd3131-3292-482a-9ec3-32cd7f3e799b"

Import-CrmPackage [...]

Runtime setting

$runtimeSettings =  "ConnRef:devhub_sharedvisualstudioteamservices_ca653=shared-visualstudiot-44dd3131-3292-482a-9ec3-32cd7f3e799b"

Import-CrmPackage [...] –RuntimePackageSettings $runtimeSettings

The runtime setting takes precedence if both an environment variable and runtime setting are found for the same connection reference.

To get your flow connection names, go to your environment and navigate to Data -> Connections within the Maker Portal. Opening a connection will reveal the connection name in the URL, which will have a format of 'environments/environmentid/connections/apiname/connectionname/details'.

As above, you will need to pass a licensed user's email via runtime settings or environment variables if the Package Deployer is not running in the context of a licensed user. In addition, the connections passed in need to be owned by the user doing the deployment or impersonated by the deployment.

Environment variables

Set environment variables

You can set Power App environment variables either through system environment variables (for example, those exposed on Azure Pipelines from your variables or variable groups) or through Package Deployer runtime settings.

Environment variables must be prefixed with PACKAGEDEPLOYER_SETTINGS_ENVVAR_ and followed by the schema name. Similarly, runtime settings must be prefixed with EnvVar: and followed by the environment variable schema name. For example, if an enviroment variable schema name was pdt_testvariable, this could be set via either of the following:

Environment variable

$env:PACKAGEDEPLOYER_SETTINGS_ENVVAR_PDT_TESTVARIABLE = "test_value"

Import-CrmPackage [...]

Runtime setting

$runtimeSettings = "EnvVar:pdt_testvariable=test_value"

Import-CrmPackage [...] –RuntimePackageSettings $runtimeSettings

The runtime setting takes precedence if both an environment variable and runtime setting are found for the same Power App environment variable.

If a value has already been set in the target environment then it will be overridden, otherwise a new environment variable value will be created and related to the environment variable definition determined by the given schema name.

Data

Import data

You can migrate data using the Dataverse data migrator tool by adding a <dataimports> element within the <templateconfig>. There are three attributes that can be added to the individual <dataimport> elements.

• datafolderpath - this is the path to the folder that contains the data files extracted using the data migrator tool.
• importconfigpath - this is the path to the json file containing the import configuration for the data migrator tool
• importbeforesolutions - this allows you to specify whether the data should be imported before or after importing the solutions.

<templateconfig>
    <dataimports>
        <dataimport 
            datafolderpath="ConfigurationData/Extract"
            importconfigpath="ConfigurationData/ImportConfig.json"
            importbeforesolutions="true"/>
    </dataimports>
</templateconfig>

Word templates

Import word templates

You can import word templates by adding <documenttemplate> elements.

<templateconfig>
    <documenttemplates>
        <documenttemplate path="Word Template.docx"/>
    </documenttemplates>
</templateconfig>

Attribute specific functionality

Set auto-number seed values

When deploying auto-numbers, seed values can be defined in the template for each entity. These are set post-deployment. Setting the <autonumberseedvalue> element determines that the column is an auto-number.

<templateconfig>
    <tables>
      <table name="account">
        <columns>
          <column name="new_accountautonumber" autonumberseedvalue="1"/>
        </columns>
      </table>
      <table name="contact">
        <columns>
          <column name="new_contactautonumber" autonumberseedvalue="2000"/>
        </columns>
      </table>
    </tables>
</templateconfig>

Important Note: When you set a seed value, it will reset the next number in the sequence to the seed value. Unless the autonumber column has an alternate key, it will not be enforced as unique. This means you could accidentally reset the count and end up with duplicate auto-number values.

You should set the seed once in the config file and avoid changing it. If you need to change the seed, ensure that it is a higher value than the current value on all target environments.

More information can be read on this functionality here: https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/create-auto-number-attributes

Mailboxes

Update, approve, test and enable shared mailboxes

You can update shared mailboxes with target email address, approve and test&enable by setting configurations either through environment variables (for example, those exposed on Azure Pipelines from your variables or variable groups) or through Package Deployer runtime settings.

Environment variables must be prefixed with PACKAGEDEPLOYER_SETTINGS_MAILBOX_ and followed by the source email address. Similarly, runtime settings must be prefixed with Mailbox: and followed by the source email address. For example, if a source email address was [email protected], this could be set via either of the following:

Environment variable

$env:PACKAGEDEPLOYER_SETTINGS_MAILBOX_SUPPORT-DEV@FAKE.COM = "[email protected]"

Import-CrmPackage [...]

Runtime setting

$runtimeSettings = "Mailbox:[email protected][email protected]" 

Import-CrmPackage [...] –RuntimePackageSettings $runtimeSettings

The runtime setting takes precedence if both an environment variable and runtime setting are found for the same shared mailbox.

Azure Pipelines

The template will automatically detect if your deployment is running on Azure Pipelines and will log with the appropriate logging commands to ensure that warnings and errors are reported on your pipeline or release.

Use the TraceLoggerAdapter rather than the PackageLog to ensure that your extensions also integrate seamlessly with Azure Pipelines.

Contributing

Please refer to the Contributing guide.

License

The Power Apps Package Deployer Template is released under the MIT license.