Move Dynamics 365 Portal Configuration Data Using the XrmToolBox

Summary

  • There are challenges copying Dynamics 365 Portal Data from one instance to another due to the complexity of the entity structure.
  • Semi-official method of using the Configuration Data Mover has potential to leave gaps and data and other pitfalls.
  • The XrmToolBox Portal Data Mover has been recently updated and when used correctly is an easy-to-use method to copy portal configuration data.

Update

If you want to see this in action, check out my contribution to the CRM MVP YouTube Channel here.

Dynamics 365 Portal Configuration

Anyone that has worked with the Dynamics 365 Portal knows that the portal configuration data is stored in a series of portal-specific entities in Dynamics 365 such as websites, web pages, web templates, entity lists, entity forms, content snippets, etc.  This provides a high level of configuration options when building a website that needs to expose Dynamics 365 data to external stakeholders.  The downside is that the portal metadata stored as Dynamics 365 records means that it is not solution aware and it is difficult to transfer the portal configuration from one system to another, for example, from a development or test portal to a production portal.

Dynamics 365 Configuration Data Mover

The “semi-official” (although described as unsupported) way to move Portal configuration data is via the Configuration Data Migration tool.  The process is outlined in this community blog posting.

There are issues and the tool is not designed specifically for Dynamics 365 Portals but rather Dynamics 365 configuration data in general (such as the unified service desk configurations).

In my experience, I have found the following issues:

  • Missing relationships between records, which will cause portal errors and navigation issues.
  • Duplicate Web Pages if you forget to shut off the Portal Web Page plug-ins.
  • Missing web file attachments.
  • Portal Data Updates are typically an “all or nothing” process, meaning you cannot just move specific web pages or other elements but must move everything.  This creates a lot of overhead to update a few specific components.
portalmoving
Moving Portal Data should not be like this.

All of these issues can be worked around, but they are tedious and time-consuming.

If you are using older (Adxstudio) portals, there is the Website Copy Utility or the Adxstudio ALM Toolkit.  However, these tools are no longer supported and the ALM Toolkit is no longer available download, and also does not work for Dynamics 365 v9.  Other options are copying/pasting or using other data migration tools.

XrmToolBox To The Rescue!

Tanguy Touzard (@TanguyTOUZARD) has recently updated his Portal Records Mover tool as part of the XrmToolBox.  The tool has a few issues when it was first released, but after recent updates it now becomes an easy and viable tool for moving full Portals or even just specific Portal components.

I have configured a portal on my “source” Dynamics 365 environment.  This could be a separate dev instance or a completely different tenant.  Note that you only get one portal license if there are at least 5 Plan 1 user licenses.  For DEV/TEST portals you will need to additional subscriptions.

1.sourceportal
Source Portal

On my source portal, I have added a few web pages, entity lists and entity forms and some custom web links.  I have also configured the authentication to be email only.

I can see the portal data in Dynamics 365 either via the “Portal” section, but with the recent v9 release, there is a new Dynamics 365 Portals App.  See a good review of new Portal features are outlined by here and also information on the new inline editors here.  Thanks to Nicholas Hayduk (@Engineered_Code) and Colin Vermander (@_koolin) for these great blog posts.

2. portalApp
Portal App

Navigating in the Portal App we will see our Custom Website.

3. sourceportal
ReadyPortal on our Source Dynamics 365 instance

Before you can move the portal configuration data, you will need to make sure that you deploy any of your customizations/solutions that are in any way related to the portal to the destination systems.  Please read the information on the Microsoft Docs site on how to manage and move solutions.

4. sourceportal
Ensure Dynamics 365 Solutions are moved first

You will also need the managed Portal solutions installed on the destination Dynamics 365 system, click here to learn how.  If you should install the same “type” of Portal (e.g. Custom) as your source system, it will be overwritten.  If you have multiple portals you should make sure the website GUIDs are unique.  You may need another portal subscription license as there is only one license supplied per tenant with 5 plan 1 users.

You should make sure that the default, out of the box Portal is working before copying the new Portal over.

5. destinationportal
Destination, Out of the Box Portal

Run the XrmToolBox, make sure you have the latest build.  Locate and run the Portal Records Mover plug-in.

5. xrmtoolbox
XrmToolBox with Portal Records Mover

You will want to connect to your SOURCE Dynamics 365 instance.  When the tool opens, there are a lot of options and it is important to follow the order to be successful.

  1. Choose the Portal in source that you want to export (move)
  2. Choose only active records (optional, but keeps the portal data clean)
  3. Choose Load Items
  4. Deselect Invitation (causes an error and not necessary to copy) also Page Notifications (deprecated feature and seems to cause an error) and Notes (this will capture ALL notes in your Dynamics 365 system, which we don’t need).  Note that by choosing Web Files, the associated attachments will come over with the data.
  5. Retrieve the Records
  6. Save Settings for the Next time.
6. xrmtoolbox
Portal Data Mover

Note that you can go into each record type and deselect particular records that you might not want to migrate.  For instance, some site settings or content snippets may point to specific URLs or settings that are specific to environments.  Note that the columns displayed for each record come from the “Quick Find” views in Dynamics 365 and you can modify them to show other column configurations.

7. deselectxrmtoolbox
Remove specific portal records (optional)

Click on the “Export Records” to export the data to an XML data file.

8. exportdata
Exporting

Once exported, I would recommend the file be saved to a source control system (VSTS, Git, etc).

The next step is to disconnect the Portal Records Mover from the source system and connect it to the destination system.

Once loaded, connect to the Portal Records Mover plug-in again and this time choose Import Records.

9. importdata
Saving the file (consider adding to source control)

You will get a message about importing web pages and to deactivate plugin steps.  THIS IS HIGHLY RECOMMENDED or you may end up with duplicate web pages as the plug-ins will create child web pages for multi-language features of the portal.

10. plugins
Highly recommend deactivating Plug-ins

The process will begin to import the portal data.

11. import
Importing Data

After the records have been imported, the Portal Mover tool will create the various relationships between the records.  This is a key step to ensure the portal continues to work on the destination system.

12. import2
Updating Relationships

After a few moments, the process should complete.  If there are any errors, you will have a log and can investigate the issues.

13. import2

On the destination Dynamics 365 system, you should see your Portal.

14. destinationD365
Portal Transferred

Navigate to the Dynamics 365 Admin Center and in the Applications area, click to manage the Portal.  If you have multiple Portals, you may need to select the particular portal you want to be visible.

15. PortalAdmin
Ensuring Bindings

It is also a good idea to restart the Portal in order to clean out any cached items, etc.

16. PortalAdminRestart
Restarting Portal

After the Portal has restarted, navigate to the destination portal URL.  Depending on the browser you used, you may still see caching issues, but the base functionality should be successfully transferred over.

17. NewPortal
Some delayed Caching

After a few cache refreshes (or choosing a different browser) you should see your portal successfully migrated.

18. NewPortal
Portal Transferred!

Going forward, if you create any new Portal components on the source system, you can use the Portal Records Mover to move just those new components.

Make sure you choose a date (ideally the day after you did your portal move) and the Portal Records Mover will grab just the update/new Portal records.

19. PortalUpdates
Going forward, just the updates.

You can follow the same steps to update your portal.

Summary

The XrmToolBox is an ideal method for migrating and updating Portal data from a source system to a destination system (DEV to PROD).  Ideally, I would like to see a few new features (a command line driven version for continuous integration) however this currently is a very easy method to migrate and update Portal configuration data on a regular basis.

UPDATE:  I posted this less than an hour ago and was made aware that a command line version of this tool exists!  Portal Records Mover Console by James Novak  Sometimes you just need to ask for stuff!

Thanks again to Tanguy Touzard for this awesome tool!

Nick Doelman is Microsoft Business Applications MVP and has been recently awarded for the second time.  Nick will be presenting at D365UG Summit in Phoenix in October.

5 thoughts on “Move Dynamics 365 Portal Configuration Data Using the XrmToolBox

  1. Great post 🙂

    I made a quite large migration from sandbox to production using XrmToolBox.
    I followed your “guide” and it worked flawlessly.

    I have used the “Configuration Data Migration tool” earlier on the same project, and must say that the Portal Records Mover will be the preferred tool for future migrations – much easier to use and not so complex.

    /Jacob

    Liked by 1 person

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 )

Google+ photo

You are commenting using your Google+ 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