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.


13 thoughts on “Upgrade Adxstudio Portals v7.x to xRM Portals Community Edition

  1. Hey Colin, thanks for this post.
    I went through the steps and was able to migrate an Adxstudio v7.0.0025 portal to the online portal.
    Few notes:
    I found that I had to update all the entity forms, entity lists and web templates “website” look-up as that was blank after the update (as you know, v7 didn’t have website look-ups on these entities).
    I had to remove all the Adxstudio v7 solutions before deploying the online portal. It would not deploy otherwise and I got a stern message about it.
    When I deployed the online portal, I just named it the same as my original Adxstudio website and it added an appropriate binding, not sure if I had to that.
    I know you are planning to write another post for these last steps… anything else I should be aware of? Everything else including logins and permissions seemed to work.


    1. Hi, Nick sorry for the delay, traveling a lot for the holidays but back in the office chair finally. Yes everything you mentioned is correct for the web site lookup. You don’t have to populate this in all cases but some components will complain if you do not. As for going all the way to online, there is a restriction on a portal server being connected with any of the ADX based solutions still existing in the instance, they have a check for some unique identifiers on those solutions which will prevent it from working.

      Other than that no there is not much more to be aware of as long as you are doing a completely out of box portal. If you have customized or done major configurations then definitely check those over prior to releasing the new version of the site as there maybe changes between v7 and online portals that aren’t even documented.



  2. Hi Colin, thanks for the post.

    My client is using Dynamics 365 with an on premise ADX v7.0.0025 but using the Government Portal. On the plus side they are not using any of the functionality specific to that portal as far as I can tell. It is a pretty simple portal running off custom entities mostly.
    I am thinking that we should use the Starter/Custom Portal and with some luck (…and testing) that will work out. Do you have an alternative approach?

    Thanks, Steve


    1. Hi Steve, that process should work yes. Note though that NONE of the ADX custom entities related to the government solution will come over to the online version so you can’t have any dependencies on items like adx_servicerequest or others.


  3. Hi Colin,

    Thanks for the nice post!!!
    I have one query here, actually we have customised the ADX Master Portal solution to a huge extent like added the many ascx page inside control and calling from web form steps, added custom new pages and even modified the Login Controller and Account Controller like files also and many more things.
    Can you please suggest in this scenarios how can I upgrade to CRM Portals as I have read that in the latest document released by Microsoft that we can upgrade to CRM Portal only when we have unaltered the ADX master portal source code(mentioned in prerequisites).

    Please suggest.



  4. Hello Colin,

    I know it’s a bit offtopic maybe, but is it possible to install the Community Edition in a new CRM instance and then move all the solutions (and then data) from another CRM instance with the old Adxstudio portal?
    If yes, do you know how or can you point me out a guide?

    Any suggestion is very appreciated.



  5. Hi Colin,

    Do you know if is it possible to install the Community portal in another instance of the CRM and then import all the solutions of the old CRM instance (with adx studio) to the new one without doing the update of the old one first?

    (I am asking because I am trying to do so, I have installed the Community portal in the CRM but the solution import from the old one to the new one does not work for me, I get multiple “missing components” errors regarding adx stuff.)



  6. Hi Colin,

    Thanks for the above post. It is very helpful, I have managed to move from Adxstudio v7 to Xrm portals community edition from the steps (All this has been for CRM online v9.0).
    I was wondering do we need to uninstall all the old adxstudio solutions, is it really required? The reason I am asking is because we are using the Case access entity to give relevant case access permissions to the users. If I remove the Adx_PortalDependencies solution (which consist of case access entity) the case access entity will be removed from the org. Is there any alternative?
    Please suggest me if there is anything.


    1. It isn’t required to run community edition but it is recommended. You will need to do it to move to online eventually as well. You will need to move to the new standard of case access permissions which is based on entity permissions instead of an entity itself.


  7. Thanks for the depth of this post. I’m preparing to move from Adxstudio 7.0 to community edition. The dynamics solution is Dynamics 365, the latest update. Is there any advice on how to move the data owned by the contacts – the solution allows portal users to create and upload records into a custom entity. It also uses the invoice entity to track payments. We are developing the “new” portal in a sandbox and need to move and retain record ownership in production in respect to the logins and (plan to copy sandbox to production once data migration is complete).


    1. You will need to look into data migration tools and the feature sets they have to maintain record ownership, they should support it as the SDK provides the mechanism to do that. I would strongly suggest looking at KingswaySoft SSIS adapter, very powerful, fast, and excellent pricing.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s