The Customer Engagement Application, formerly Microsoft Portals (and before that, ADXStudio Portals) is a Software-As-Service (SAS) web application run by Microsoft in the Cloud. It utilizes Microsoft CRM as the persistence layer for business data and application metadata. The latter defines the web application’s look, feel, behavior, and restrictions. Deployment of such Portals in version-controlled scenarios may present substantial challenges that prevent efficient testing of the target environments and make it problematic to roll back any deployed changes. In today’s blog, we will review the issues, available tools, and options to solve the task, as well as detail the methodology of achieving positive results.

Let’s start by discussing the challenges. Typical Portal deployment consists of three steps:

  1. Deployment of Portal solutions into the target CRM
  2. Deployment of business customizations related to the Portal (entities, forms, views, option sets)
  3. Transfer of the data stored in Portal-related entities

In the typical scenario, Microsoft provides step #1 by installing a new Portal into the target CRM instance. Once this is done, Microsoft also populates Portal configuration entities with sample data and makes a Portal available for modification. This approach assumes a single production environment and does not imply any development anywhere other than the target CRM. Such development may involve business customizations to the CRM objects, as well as modification and expansion of the Portal configuration data.

In the development workflow, where any business customizations are done in DEV environment and then ported to the target PROD or QA CRM, Step #2 above is managed consistently and presents no challenge. However, in case when both source and target CRM environments are bound with appropriate SAS Portal applications, any development related to the source Portal represents data that requires transfer to the target CRM, presenting the following challenges:

  • Both source and target CRMs may have Portals with the same name and any data transfer may create collision and confusion in the names of the data elements
  • Portal-dependent child records in both CRMs may have the same unique identifiers (GUIDs) – in those cases when one environment was procured as the clone of another and any data transfer from the source to the target will respect the update and insert operations but not deletion
  • In case of existing target Portal data, there will be no option to roll back the deployment in case of any issues
  • There will be no option to create a new instance of Portal record in the target CRM when the record with matching GUID exists (true for any dependent child records, as well)

Now, let’s discuss our options. Presently, there are only two tools available to transfer Portal data:

  • XRMToolbox plugin for Portal transfer – this uses proprietary data encoding format and inconsistent data schema with several compatibility issues; it allows for updating only existing Portal records in the target environment. When the target Portal is not selected and the GUIDs of the source and target data sets match, it produces unusable results. Also, this tool has issues with transferring M:M-related data, which makes it out-of-scope for Portal deployment.
  • CRM Configuration Migration Tool – provided by CRM SDK – is a universal tool that may properly handle linked data transfers and M:M relationship migration in several iterations. This tool exports data according to the selected schema (which can be easily built for the current version of the Portal) and imports it as is. In those cases when GUIDs in the source and target match, the update is executed. There are extensive options for updates but there is no way to force it to create new records or delete obsolete ones. This is the only viable tool for our purposes, so we will see how it can be used to attain our objective.

Next, let’s examine our solution. The happy path for Portal data deployment must follow this sequence of events:

  1. In the target environment, the Portal record is renamed for archival purposes and to avoid name collision with the new Portal.
  2. The source data is extracted and stored into a file.
  3. In the source data file, all GUIDs identifying Portal records are replaced with the new ones to avoid collision with any of the target entities.
  4. The modified source data is imported to the target CRM – the new Portal record and dependent data set is created.
  5. In the target environment, the Portal SAS application is switched from the archived Portal record to the newly imported one.
  6. If testing of the new Portal is failing, the SAS application may be switched back to the archived Portal record.

Step #3 is a simple regular expression replacement of an existing found GUID. For example:


However, we must not forget that many unique record identifiers may be referenced multiple times within the data source file (linked entities), and such repeating GUIDs must be replaced with the same new GUID as the first one met. A further complication is related to the fact that we want to replace only GUIDs defined as record IDs in the data file, not the GUIDs that are referenced only: this is because many records refer to the entities outside the scope of contents of the Portal schema.

The solution is a simple command-line tool developed internally as a universal Reg-ex replacer with default patterns searching for record IDs, building a dictionary for those mapping them to the new GUIDs, then replacing all GUIDs in the file according to the dictionary. Those GUIDs not in the dictionary are not replaced.

This tool had produced a data file that, when imported, creates all brand-new target Portal entities and all brand-new dependent entities, while any of the imported entities linked to existing data outside of the Portal schema stay properly linked.

Since the new record set is created in the target environment, there is no issue with deleting obsolete configuration records: those stay linked to the archived versions of configurations and will be deleted automatically when the old Portal records are purged.

The only insubstantial complication in the suggested deployment process is related to the contacts assigned with the web roles. We are not porting or updating the contacts during deployment. We cannot assume that the contacts in the target environment will match those from the source. So, the web role assignments will be lost if we attempt to transfer them. For the purpose of clean data transition, it is recommended to drop all web role assignments in the source environment prior to exporting the Portal data. Those assignments may be backed-up before and restored in the source later to maintain the ability to unit-test in DEV.

In summary, with a simple command-line tool developed internally, we can use the standard CRM Configuration Migration application to transfer the Portal data from the source environment to the target in such a way that the new Portal record and dependent child records are created, making it available for SAS application to switch to. At the same time, the previous versions of the Portal records in the target environment are not destroyed or overwritten, thus making it possible to roll back the SAS assignation to any previous state of release.

A special note: with the slight modification of the default search-replace regular expressions, it is possible to use our tool to condition the data file extracted by XRMToolbox plugin for the Portals. While the data transfer experiment was successful, it is still not recommended to use because of the internal issues found within this plugin, as well as its inability to migrate M:M relationships properly.

Don’t forget to subscribe to our blog for more!

Happy D365’ing!