Fixing issues with migrating Adxstudio/CRM Portal v8 using Configuration Migration tool

The Configuration Migration tool does a pretty good job at migrating Adxstudio/CRM Portal configuration in v7. There are some changes in Portal v8 however that are causing issues with this tool. This is true at least in the case for OnPrem (Community Edition). For Online, I have not tested but suspect that the behaviour would be the same.

Issue #1 – Value of Partial URL field of the Home Page of your website can only be /. Any other value will lead to issues in your Portal.

The import log produces the above error when processing the adx_webpage entity. In Portal v8 there is a new validation that checks the Partial URL of web pages that the code determines to be a homepage. The code determines a web page as a homepage when it does not have a value in the Parent Page field.

As the Parent Page field is a reference field to the same entity (i.e. adx_webpage), I suspect the Configuration Migration tool first saves the record without a value for this field, and then fixes it up in a 2nd pass. Creating the web page without a Parent Page however causes the validation to see it as a homepage, and hence the Partial URL fails the validation.

This validation occurs in a plugin. To workaround this issue we need to disable the following plugin steps prior to running the import:

  1. Plugin assembly: Adxstudio.Xrm.Plugins
    • Plugin: Adxstudio.Xrm.Plugins.MultiLanguage.WebPageValidationPlugin
      1. Step: Adxstudio.Xrm.Plugins.MultiLanguage.WebPageValidationPlugin: Update of adx_webpage
      2. Step: Adxstudio.Xrm.Plugins.MultiLanguage.WebPageValidationPlugin: Create of adx_webpage

Issue #2 – Unexpected exception from plug-in (Execute): Adxstudio.Xrm.Plugins.MultiLanguage.WebPageUpdatePlugin: System.NullReferenceException: Object reference not set to an instance of an object

The “Object reference not set to an instance of an object” is probably the bane of all developers as it is often quite hard to pinpoint the root cause without debugging. Unfortunately this is the case in this scenario, and I don’t quite know the root cause of this issue. You can however workaround it by disabling the following plugin step prior to running the import:

  1. Plugin assembly: Adxstudio.Xrm.Plugins
    • Plugin: Adxstudio.Xrm.Plugins.MultiLanguage.WebPageUpdatePlugin
      1. Step: Adxstudio.Xrm.Plugins.MultiLanguage.WebPageUpdatePlugin: Update of adx_webpage

Issue #3 – Duplicate web pages

One of the changes in Portal v8 is the introduction of localised web pages. When you create a web page (Portal refers to this as a Root page), a separate localised web page is automatically created for the corresponding root page and is linked to it. So if you create a web page called Dashboard for example, a second web page would be automatically created for you. This page, also named Dashboard by default, would hold the localised content of the Dashboard page you explicitly created.

The localised page is created by a plugin, which means that you’d end up with duplicate web pages when importing data via the Configuration Migration tool. This is because the migration tool would import both the root page and the localised page, and the plugin would trigger on the creation of the root page, which in turns would create a duplicate localised page.

To workaround this issue we need to disable the following plugin step prior to running the import:

  1. Plugin assembly: Adxstudio.Xrm.Plugins
    • Plugin: Adxstudio.Xrm.Plugins.MultiLanguage.WebPagePlugin
      1. Step: Adxstudio.Xrm.Plugins.MultiLanguage.WebPagePlugin: Create of adx_webpage

(Potential) Issue #4

OK, this is not one that I have actually encountered, but one that I just thought about while describing issue #3 above.

When the localised web page is automatically created, it has the same name as the root page by default. The Configuration Migration tool however uses the primary name field of an entity to determine uniqueness while importing if no duplicate detection (uniqueness) condition is specified for that entity. I wonder if this could lead to the migration tool applying updates to incorrect records during the import?

In our implementation we always append the language name to the name of localised web pages, e.g. Dashboard is the root page and Dashboard (English) is the localised page. We therefore have not encountered this issue, but it is something that we should check.


So in summary…

When migrating configuration for Portal v8 you should disable four plugin steps prior to the import (and remember to enable them again afterward).

I would suggest always append the language name to the name of localised web pages to avoid confusion for yourself, and possibly also for the Configuration Migration tool.


About Bernado

Based in Australia, I am a freelance SharePoint and Dynamics CRM developer. I love developing innovative solutions that address business and everyday problems. Feel free to contact me if you think I can help you with your SharePoint or CRM implementation.
This entry was posted in CRM, CRM Portal. Bookmark the permalink.

4 Responses to Fixing issues with migrating Adxstudio/CRM Portal v8 using Configuration Migration tool

  1. Alan Mervitz says:

    Hi Bernado,

    These steps can be simplified by using the following two options on the web page entity in the schema creation step of the configuration migration tool:

    1. Disable plugins on the web page entity, I generally think it’s beneficial to disable plugins on all entities to avoid side effects by pluduring import. See steps 12 and 13 on for details.

    2. In the same page linked to, step 12 shows that you can choose which fields to compare against during import for testing uniqueness. To avoid the name clashing on web page, set adx_webpageid as the field to compare. I usually set every entity to use their primary id field to ensure uniqueness, rather than relying on the default behaviour of matching on primary name field which is often not the desired or expected behaviour of a data import.

    • Bernado says:

      Thanks Alan.

      I am aware of the option to disable plugins in the migration tool, but didn’t want to use it at the time as I wasn’t sure if CRM Portal has any automated process behind the scene for web pages that should not be disabled. Now that I am a bit more familiar/comfortable with this product, I will be using this option to save time.

      By the way, we find that sometime the migration tool does not import the web form metadata properly. We do have uniqueness rules setup on this entity. We sometime have to do the import twice for it to bring in all web form metadata. Have you seen this before?

      • Alan Mervitz says:

        I haven’t seen that problem on importing web form metadata before, but failed imports can occur if the entity is dependent on another one. You may be errors in the import log file that give some clues as to why the first import fails. If it’s a dependency related issue, you could adjust the order of the entities in the schema xml file in a text editor and have web form metadata after whichever other one it’s dependent on, so that during the import it’s imported afterwards instead of before.

      • Bernado says:

        Thanks Alan. I thought the migration tool was suppose to take care of the dependency issue – but perhaps it does not get it perfect all the times. I will try your suggestion of modifying the schema file :).

Leave a Reply

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

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

Facebook photo

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

Connecting to %s