XrmToolbox Portal Records Mover as a Console Application

The Portal Records Mover is an excellent XrmToolbox plugin by Tanguy Touzard for anyone working on a Dynamics 365 Portals project.  If have not used this tool as part of your Portals deployment process, I suggest checking it out here: MscrmTools.PortalRecordsMover

Deploying Portals Configuration

With a Portals project comes the need to migrate your portal specific records to downstream environments, such as test, staging, and production.  For example, if you are using Web Forms, you might need to move the records for Web Site, Web Form, Web Form Steps, and any related Web Form Metadata, Web Templates, and Entity Forms.  Even with a simple Portals project, this quickly becomes a major undertaking just to ensure that environments update correctly.

The Portal Records Mover tool provides some excellent help in managing your records.  The tool is aware of the Portals solution Entity structure and provides the ability to export Portal specific records for re-import into another environment.

Usage is pretty straightforward: the plugin provides a list of the Portals specific records, such as Entity Form, Entity List, Web Form, Web Form Step, etc.  You provide a date filter for the records you would like to retrieve, such as records modified on or after a specific date.  Once the records are retrieved, you can download the to an Xml file for re-import into a different Portal.

The cool bit about this tool is that under the hood, it uses the UpsertRequest when importing the data into the target system. Here is the documentation on using Upsert: Use Upsert to insert or update a record.  Why does this matter?  Using the UpsertRequest, the SDK call will first check to see if the record exists.  If it does not, the call will create the record.  If it does exist, the record will simply be updated. When you are deploying Portal updates to downstream systems, this saves a LOT of hassle in avoiding unnecessary duplicates.

Automation!

We had been using the tool for a while on my current Portals project, but we starting moving to automated build and deployment. This meant the need to automate the Portal Records Mover form a command line. I asked Tanguy if he would permit my porting his code to a console application, and luckily he gave the thumbs up!  I cloned a copy of the Portal Records Mover plugin repository and began removing the UI elements, wrapping them with a console app.  My goal was to provide a console app with command line parameters that closely mimic the Portal Record Mover options, with the rest of the application remaining the same. Simply put, I wanted to keep the brains of the tool Tanguy built and just automate its execution.

Luckily, the plugin code is well organized and segmented such that I was able to preserve all of his business logic almost as is and wrap the calls in my console app. As stated, the new console application includes parameters that mimic the user interface options closely. I provide details on the command line options and and some example configurations with the code posted on GitHub. With the new console version of the Portal Records Mover, you can easily integrate this into your automated build and deployment process.

Some minor differences

I am providing usage notes on the Portal Records Mover Console in the GitHub repository, but I want to point out a few differences. Other than these deltas, the console application operates much like the XrmToolbox Portal Records Mover.

Date filters

I added an option around the date filters. In the console application, you can specify the created on or modified on filters as with the XrmToolbox plugin, or you can provide a number of days as a filter. For example, retrieve the records modified in the last 10 days. This aligns with our intent to periodically run builds where you want to choose only records that have changed since the last run. So if we ran nightly builds, I can retrieve all records modified in the last 1 day.

Immediate Import

An additional change is that you can export the records and immediately execute an import into a target environment.  In the XrmToolbox plugin, you can export the records to an XML file based on your current selection.  But to import into another environment, you have one additional step to change your connection. This is a minor bit of additional work, but because we are automating the process, we can import the retrieved records into a target environment in one run of the tool.

All files exported

The XrmToolbox plugin version will present the user with the list of records returned for each type for the selected Entities and date filters.  In the tabs for each Entity, the user has the option to check only those records they wish to be exported.  This is a really cool feature, but unfortunately we do not have the ability for this kind of selection with a console application.  I am looking into some options for additional filters for each selected Entity that may provide a bit more flexibility when exporting your records.

Saved Settings

This one is actually more of a similarity to the XrmToolbox plugin.  In the plugin, you have the option to save and load your current settings.  The command line options can be provided directly, or you can refer to a static XML configuration file that contains your parameters.  I like this as an option for dealing with multiple environments and my configuration XML is modeled after the saved values provided by the XrmToolbox plugin.

Take it for a spin!

You can download the code from the repository here: https://github.com/jamesnovak/PortalRecordsMoverConsole.  Check out the README.md for the command line options and general usage. I will provide more details as I continue working on the updates, such as Entity level filter options mentioned above.

Thanks to Tanguy for allowing me to leverage his existing work which has saved our project an enormous amount of time. I plan on keeping a close eye on the Portal Records Mover XrmToolbox plugin so I can keep things up to date with new features or fixes.

As always, comments, corrections, and suggestions are always welcome.  In this case, reporting any issues is definitely helpful.  Please let me know if you have any issues building the project, executing the app, or if you have suggested improvements.