Copying Environments

How to reconfigure KeyNamics for new environments

Where your KeyNamics license permits, you may take copies of the environment for development, testing or UAT purposes. The basic steps are to export your KeyNamics solution, import the exported KeyNamics solution into the target Dynamics 365 environment and then update important KeyNamics settings within the newly imported solution. Sections covering each of these steps are provided below.

Exporting the KeyNamics Solution

1. Visit https://make.powerapps.com/ and ensure your source environment is selected

2. Select Solutions on the left

3. On the Solutions page select the KeyNamics solution and choose "Export". It's important you export the KeyNamics solution as a "Unmanaged" solution. We would not recommend exporting KeyNamics as a managed solution as customization capabilities will be limited. All other export settings can be left as default. You can see an example below...

Please wait a few moments for the export to complete. Once complete you can download the solution as shown below...

Once downloaded you should have a single ZIP file named KeyfaxHub_X_X_X_X.zip - where X.X.X.X is the version number provided during export. Please keep this ZIP file safe as this is the main KeyNamics solution package you will later need to import into your target Dynamics environment.

Exporting the KeyNamics Dataverse entity data (Mappings, Settings, FetchXML, Help Pages etc)

If you've customized data stored within KeyNamics entities you may also wish to export your data. To export data please follow the steps below...

1. Install the Dynamics SDK (see below)

2. Launch the ConfigurationMigration\DataMigrationUtility.exe utility

3. Select "Generate Schema"

4. Authenticate & connect to your Dynamics environment...

Select the KeyNamics solution and add the following Dataverse entities and click "Save & export"...

Once schema export is completed you will be prompted if you wish to also export the schema data. choose "Yes"...

Select a location on your computer for the exported data file and click "Export Data" as shown below...

After export is complete you should see the following success messages...

This will create a single new file called data.zip. You will need to import this data.zip file into your target D365 environment.

TIP Once you've generated the schema file once you can reuse this same schema file to export data from other KeyNamics environments running the same version of KeyNamics. You don't need to re-create the schema file every time you export data unless you know something has changed. For subsequent exports you may be able to just choose the "Export Data" option within DataMigrationUtility.exe and can likely skip the "Generate Schema" phase.

Importing the KeyNamics Solution

1. Visit https://make.powerapps.com/ and ensure your target environment is selected
2. Click Solutions on the left

3. From the Solution page choose "Import". When prompted browse to and select the previously prepared KeyfaxHub_X_X_X_X.zip file.

4. After import is complete ensure you "Publish all customization's"

5. Ensure you check KeyNamics settings that may need to be updated for your new environment. See "Important Settings" below.

Importing the KeyNamics Dataverse data (Mappings, Settings, FetchXML, Help Pages etc)

1. Install the Dynamics SDK (see below)

2. Launch the ConfigurationMigration\DataMigrationUtility.exe utility

3. Select "Import Data"...

Authenticate & connect to your target Dynamics environment...

After you've successfully connected to your target environment select the previously created data.zip file...

Click "Import Data" to import the previously exported data.zip file into your target Dynamics environment. You should see results similar to the following...

TIP You may see warnings during the import process if data exists within your target D365 environment that doesn't exist within your exported data.

Important KeyNamics Settings

The following settings may need to be updated after importing the KeyNamics solution into your new environment. This should be done via the Settings area of your newly imported KeyNamics model driven app. Further details on key settings are provided below...

1. The Startup Template Setting

In the Settings section you will find one of more declarations which provide the contents of an XML 'startup template'. These XML documents are used as containers for all Startup elements (e.g. data elements that will be sent to Keyfax at startup). For each configuration file (e.g. 'Staff_Test') and each supported 'mode' an entry must exist. Major known 'modes' are:

• RD = Repair Diagnostics

• FL = General Enquiries

• ROL = Repairs Online (Self Service)

• EOL = Enquiries Online (Self Service)

The example below shows a template defined for the configuration 'Staff_Test' to suport mode 'ROL':

The Startup Template setting

1. The ReturnURL of the 'Completed' page of your new Dynamics environment in Template Settings (this node will be empty for Staff environments). If it does exist, there may be more than one occurrence for different configurations:

Configuring the Return URL

1. The WebServiceBaseUrl Setting

This is simply a URL that points at the instance of the Keyfax webservice you wish to use. You may have multiple instances of Keyfax installed (e.g. Production, Test, Development) and this allows you to switch between them:

Setting the Keyfax WebService you wish to point at

1. The Company (aka Config) Mapping - defines which configuration data will be used. This is held in the 'Mappings' area. Typically this could be 'Staff_TEST', 'Staff_DEV' etc. Omfax Systems can advise which Company codes are available for use on any particular Keyfax webserver. The example below is at the Global level although this can be overridden at the Entity level if required:

Example showing how to set the Company (aka COnfig) code

Testing the Imported KeyNamics Solution

If everything was successful within your target Dynamics environment you should see a new "KeyNamics" app. To test please follow the steps below...

1. Visit https://make.powerapps.com/ and ensure your target environment is selected
2. Click Apps on the left

3. Locate & launch the KeyNamics app

4. You should see the KeyNamics model driven app similar to that shown below...

1. Use the "Test" button on the left to test launching Keyfax

2. Don't forget to review your Settings for the new environment

Installing the Dynamics SDK

To install the Dynamics SDK you would create a new folder and then navigate to this folder via PowerShell. You should launch PowerShell as an administrator. Once you've navigated to your new installation folder execute the script below...

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$sourceNugetExe = "https://dist.nuget.org/win-x86-commandline/latest/nuget.exe"
$targetNugetExe = ".\nuget.exe"
Remove-Item .\Tools -Force -Recurse -ErrorAction Ignore
Invoke-WebRequest $sourceNugetExe -OutFile $targetNugetExe
Set-Alias nuget $targetNugetExe -Scope Global -Verbose

##
##Download Plugin Registration Tool
##
./nuget install Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool -O .\Tools
md .\Tools\PluginRegistration
$prtFolder = Get-ChildItem ./Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.PluginRegistrationTool.'}
move .\Tools\$prtFolder\tools\*.* .\Tools\PluginRegistration
Remove-Item .\Tools\$prtFolder -Force -Recurse

##
##Download CoreTools
##
./nuget install  Microsoft.CrmSdk.CoreTools -O .\Tools
md .\Tools\CoreTools
$coreToolsFolder = Get-ChildItem ./Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.CoreTools.'}
move .\Tools\$coreToolsFolder\content\bin\coretools\*.* .\Tools\CoreTools
Remove-Item .\Tools\$coreToolsFolder -Force -Recurse

##
##Download Configuration Migration
##
./nuget install  Microsoft.CrmSdk.XrmTooling.ConfigurationMigration.Wpf -O .\Tools
md .\Tools\ConfigurationMigration
$configMigFolder = Get-ChildItem ./Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.ConfigurationMigration.Wpf.'}
move .\Tools\$configMigFolder\tools\*.* .\Tools\ConfigurationMigration
Remove-Item .\Tools\$configMigFolder -Force -Recurse

##
##Download Package Deployer 
##
./nuget install  Microsoft.CrmSdk.XrmTooling.PackageDeployment.WPF -O .\Tools
md .\Tools\PackageDeployment
$pdFolder = Get-ChildItem ./Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.PackageDeployment.Wpf.'}
move .\Tools\$pdFolder\tools\*.* .\Tools\PackageDeployment
Remove-Item .\Tools\$pdFolder -Force -Recurse

##
##Download Package Deployer PowerShell module
##
./nuget install Microsoft.CrmSdk.XrmTooling.PackageDeployment.PowerShell -O .\Tools
$pdPoshFolder = Get-ChildItem ./Tools | Where-Object {$_.Name -match 'Microsoft.CrmSdk.XrmTooling.PackageDeployment.PowerShell.'}
move .\Tools\$pdPoshFolder\tools\*.* .\Tools\PackageDeployment.PowerShell
Remove-Item .\Tools\$pdPoshFolder -Force -Recurse

##
##Remove NuGet.exe
##
Remove-Item nuget.exe    

After executing this script you should see the following messages...

Within your new installation folder you'll now see a new "Tools" folder as shown below...

This "Tools" folder contains all the main utilities we'll use in this article.