Recently the Product Group released a migration guide to move from Adxstudio v7 Portals to Portal Capabilities for Dynamics 365.  That announcement with a link to the guide can be found here.  On the heels of that announcement I wanted to share my experience with doing an in-place upgrade of ADX 7.x to Dynamics Portals 8.x.  The guide itself covers several migration options including reimplementation both self-hosted or Microsoft hosted as well as an in-place upgrade both self-hosted or Microsoft hosted.  I won’t go through the details of the process since it is very well covered in the guide, but I’ll point out some of the findings as a result of going through the process.

Cleanup Prior to Upgrading

It is worthwhile to do a little housekeeping prior to starting the upgrade process.  You may have artifacts that are no longer being used and this would be a good opportunity to address those items.  The upgrade process will “split” each of the existing web pages into 2 pages – a root page and a localized content page.  The issue that arises is that even inactive web pages will get split and will result in an inactive root page with an active content page.  This will result in unexplained “404 not found” errors on the upgraded portal and potentially navigation links that are normally not visible due to Access Control Rules being now visible.  If there are inactive web pages that can’t be removed prior to the upgrade, an advanced find can be used post upgrade to find inactive root pages that have an active content page.  Those content pages should also be deactivated.

Images that had a space in the partial URL were no longer rendered after the upgrade, so it may be worth while to search through the child files and update the partial URLs so there are no spaces prior to the upgrade process.  Remember to update the related link to the file wherever it is being used.

Uninstalling ADX Solutions

Having ADX 7.x solutions deployed alongside Dynamics Portal 8.x solutions is not supported (and would not work anyway for the most part) so part of the upgrade process will include uninstalling the ADX solutions.  Depending on what ADX portal package was originally deployed as well as what productivity packs were also deployed, it’s possible to have 20+ ADX solutions in Dynamics 365.  As you can imagine removing these with all the interdependencies can become quite challenging.  Fortunately there are 2 utilities that can help.

Determining Installation Order

FetchXML can be used to retrieve the installation order of the ADX solutions.  Ordering the results in descending order of the installedon field will yield the correct uninstall order of the ADX solutions.  Use the FetchXML statement below, replacing “orgname”, and “x” for the version numbers to reflect your organization to retrieve the ordered list. (I’ll give credit to the below information from here)

https://[orgname].crm[x].dynamics.com/api/data/v8.[x]/solutions?fetchXml=<fetch mapping='logical'><entity name='solution'><attribute name='installedon'/><attribute name='friendlyname'/><order attribute='installedon' descending='true'/><link-entity name='publisher' to='publisherid'><attribute name='customizationprefix'/><filter type="and"><filter type="or"><condition attribute='customizationprefix' operator='eq' value='adx' /><condition attribute='customizationprefix' operator='eq' value='msa' /></filter></filter></link-entity></entity></fetch>

Finding Dependencies

There may still be situations where a lingering dependency is blocking the solution from being removed (e.g. maybe an ADX field is being used in a workflow, etc.).  The Dependency Checker tool is useful for identifying the exact dependency (or dependencies) that needs to be addressed in order to remove the solution.  Use the following URL below replacing the “organization url” to reflect your organization and the “objectid” of the solution attempting to be removed.  You can use the list of solutions from the above FetchXML statement to get the object id of the solutions.

https//<organization url>/tools/dependency/dependencyviewdialog.aspx?objectid={b6d13943-0612-4e12-b878-8d7137ab5b07}&objecttype=7100&operationtype=dependenciesforuninstall

FetchXML in Liquid Templates

As part of tightening up security on the portal, executing FetchXML now requires entity permissions on any entity that is part of the fetch statement.  At least the Read privilege needs to exist on the entity.  No errors will result after the upgrade as an indication, the fetch will result in no records so the liquid template will not work as expected (e.g. – if there is logic looping through results, etc.).

SMS for Two-Factor Authentication

Twilio support (and SMS in general) has been dropped with Dynamics Portals.  The Product Group is moving more towards external authentication/identity providers and this may be the opportunity to start investigating that path if your application is leveraging local authentication with 2FA enabled.  Email is still an option for sending the security code.

Web Templates - new reference to Website Record

Web Templates are a common way to store JavaScript functions as well as Liquid Template code.  Web Templates now have a reference to a Web Site record.  This will initially be missing after the upgrade has completed which results in “not found” errors anywhere the web templates are being referenced.  Simply updating the Web Template records lookup to the Web Site record will resolve this.

CSS Class Differences

There are a few changes to the CSS classes that are being used throughout the Portal.  Sub-grids is an example that comes to mind immediately.  Depending on how much custom theming was done to the original portal, it may be necessary to make changes to your CSS to reflect the differences in the upgraded portal.  If you entries in the various Custom CSS areas, now may be a good opportunity to consolidate those into a single file and use that as a child file of the root page.

“Failed” Portal Provisioning

When I went through the last step of provisioning the portal against my Dynamics 365 instance the provisioning did not actually fail with an error, it just never seemed to complete and the portal itself would display the “getting things ready” page.  I’m fortunate enough to have access to the product group and we were able to determine what was happening.  This is touched on in the migration guide, but I’ll offer some insight below.

At two stages of the upgrade process you will be deploying portals solutions to your Dynamics 365 instance.  The first time this is done to upgrade your existing portals artifacts to their 8.x counterparts.  The last time this is done is to provision the Dynamics portal against your Dynamics 365 instance (which will most likely further upgrade any already installed portal 8.x solutions and possibly deploy some new ones).  As you are choosing the portal package to deploy in each of these steps, you should be consistent with the original ADX portal type that was deployed.  This is important because the package that was originally chosen when first configuring the ADX portal will dictate what the ID is of your Website record and when you do the final upgrade step of provisioning the Dynamics portal against your instance if the GUID of the package chosen during provisioning does not match the ID of the existing Website record, the provisioning process will always appear to be still provisioning.

The provisioning process should create a record under Settings –> Portals –> Settings named PackageImportComplete.  The value for this record needs to match the ID of the portal package you selected to provision.  If the Website Copy tool was used against the ADX portal, it’s possible that the object of your Website record will not match one of the standard IDs.  This (having a non-standard Website id) may or may not impact the creation of the PackageImportComplete record.  If the PackageImportComplete record is missing you will need to create it and set the proper value based on the portal package that was selected.  If the record does exist and the value does not contain the proper value based on the portal package selected, update the record with the correct value.  The portal package values are: