Upgrade Adxstudio Portals v7.x to xRM Portals Community Edition

With Adxstudio Portals having an end of support date announced as August 2018, many existing Adxstudio customers are looking to see what their upgrade options are. One of the options to upgrade to the new Dynamics 365 portals from Microsoft is to utilize the Portals Source Code version or xRM Portals Community Edition as part of the upgrade path. Hidden within the PowerShell scripts for importing the Portal Source Code version is logic to actually upgrade your portal data and make it compatible with the new data formats in the release of the Portals Source Code. This allows you to maintain your existing implementation instead of having to completely re-implement it on the new version. Once you are at Portal Source Code (v8.3 portals) you can then move to online portals maintaining the implementation as well. To trigger this you need to be aware of 2 site settings that will need to be created for each web site. In this post we will look at going the first step of the upgrade process, from Adxstudio Portals v7 to Portal Source Code/xRM Portals Community Edition.

Firstly, run a backup of your instance and read over some caveats to be aware of.

  • This example will use the Basic/Start/Custom Portal template with a completely out of the box portal.
  • The upgrade process will not perfectly upgrade all your components. The upgrade process is focused around transforming data to work within the new data model. You will need to review your configurations to ensure they all function properly within the new version.
  • Custom branding will likely need to be redone
  • New portal data from the latest version will not be imported. So you will not get any new templates or configurations from the new version, but your existing data will be maintained. If you want new portal data and configurations you can install a fresh portal in a new instance and manually copy over data.
  • If multiple web sites are present all web sites must be upgraded at once and therefore all must have the 2 site settings
  • Code customizations need to be transported to the updated code base and tested for compatibility OR implemented using new out of box configuration based method. NOTE: all custom code must be removed or abstracted to a Dynamics Portal Companion App approach before upgrading to the online Dynamics 365 portals
  • If you are not using ASP.NET Identity in Adxstudio Portals this is a required change prior to removing the Adxstudio solutions as the schema for the old forms based authentication will be removed with them.

For this example I have a new Dynamics 365 instance, version 8.2.x with Adxstudio Portals v7.0.0025 installed using the Basic Portal starter template. Here are the solutions installed in the system currently:

To do the upgrade we are doing to use the package deployer packages that come with the solutions components (MicrosoftDynamics365PortalsSolutions.exe). You can download that item from the Microsoft Download Center.

Within these packages there is logic that looks at the following 2 site settings to determine if it will run the data transformation to resolve the data model changes, UpgradeWebsiteData and WebsiteLCIDforUpgrade to determine the language to apply to the site. Below is an example of the site setting values:

Name Value Example Value Description
UpgradeWebsiteData true Boolean value, default of false
WebsiteLCIDforUpgrade 1033 LCID Code for web site. Use one of 43 supported portal languages.

Once you have these site settings in, and remember if you have multiple sites you will want to have the settings in for all sites. You cannot upgrade one site and then upgrade another site later. The sites all share the same solutions which will be upgraded on the first site being done. We can then proceed with running the PowerShell script which will run one of the packages.

Open your PowerShell and navigate to the .\PackageDeployerPackages\ folder. Within that folder execute the import script, .\Import.ps1.

This will prompt you to select your connection type, on premises or online. Enter your full organization URL, ie. https://orgname.crm.dynamics.com, then enter your language LCID code. Then you will be prompted to select your package. You will want to select the starter portal you already have installed. Remember this package list and names differs a bit from the Adxstudio Installer website gallery list. Below is a map Adxstudio to Dynamics 365 portals.

Adxstudio Portals Website Gallery Templates Microsoft Dynamics 365 portals Templates
Basic Portal Starter/Custom Portal
Community Portal Community Portal
Company Portal Not Supported
Conference Portal Not Supported
Customer Portal Customer Self-Service Portal
Government Portal Not Supported
Partner Portal Partner Portal
Retail Portal Not Supported
Not Supported Employee Self-Service Portal

It is important to note that features in the portals have also changed. Community Portal with xRM Portals Community Edition and Dynamics 365 portals online no longer contains event management functionality. There will be other gaps such as this in other portals. Please ensure you validate using a portals comparison like available on adoxio.com or installing the latest portals in a clean instance.

Once you have selected your package the package deployer will start its process of importing solutions and then running the data transformation against the websites that return the site settings above.

When it is completed running you will be left with a combination of the Adxstudio solutions and the new Dynamics 365 portal ones from the Portals Source Code release. Here is an example of the combined solutions for the Basic/Starter/Custom Portal template.

You can now test the portal using the xRM Portals Community Edition code base against your instance and start to validate some of the custom configurations you put in place.

Once you have completed a quick validation the next step is to remove all the Adxstudio solutions based on their dependency tree usually last in is first out, so work your way down the list and delete each of them. Because the Dynamics 365 portals solutions are there the entities will remain in the system so none of your data should be removed either. Always best practice to be taking your backups at logical points of this process as well. With Dynamics 365 online this is a super easy process.

Note that if you have published web notification steps then you will need to unregister the SDK message steps where the event handler is “Adxstudio.Xrm.Plugins.Webnotifications”, otherwise you may run into issues removing some solutions.

Once you have removed all the Adxstudio solutions you should be left with just the Dynamics 365 ones. You can retest your functionality and move on to addressing any configuration and branding issues.

This process will have upgraded you to the Portal Source Code version solutions and you can utilize xRM Portals Community Edition has the code base for your portal and now deploy that to your web servers or to an Azure App Service. If you had any custom code that you need to continue to maintain then you should have moved it into this code base and made any necessary changes to continue its existing function.

Upgrading to Portal Source Code/xRM Portals Community Edition could be where you stop for now. When you are ready to go fully online you can continue with an upgrade to the online version of Dynamics 365 portals. In an upcoming post we will look at how you can do that upgrade from Portal Source Code version or xRM Portals Community Edition to the latest Microsoft Dynamics 365 portals online service.

If you have questions related to the upgrade please post a comments and I will try to include answers in future blog posts about the topic.