Stuart Mullinger

Using Converge

/ Home / Projects / Converge

Installing Converge

To transfer content between two different instances of Umbraco you will need to install Converge on both instances. The same package provides the API to tell other sites about the content on this instance, along with the Converge section in the back-office which allows you to update the current site.

The best way to install it is to use the NuGet package manager in Visual Studio, search for "StuartMullinger.Converge". For those who prefer the command line:

// For Umbraco V9:
PM> Install-Package StuartMullinger.Converge

// or
PM> Install-Package StuartMullinger.Converge8
PM> Install-Package StuartMullinger.Converge7

If using Umbraco 9, please check the Auto Build setting in Visual Studio.

Packages are also available on "our" which can be installed using the back-office of Umbraco.

Umbraco 7 Package

Umbraco 8 Package

I recommend using the NuGet installation if you are likely to want to add custom converters, as the Converge libraries will be properly referenced in the project.

API

I have now also created a separate package for earlier versions of Umbraco 7. This will allow the content to be read from versions 7.1.0 to 7.6.14 of Umbraco with the API installed. There is no back office functionality when the API is installed and no updates can be made. Content will need to be transferred to a website running Umbraco 7.7.0 or later with the full version of Converge installed.

PM> Install-Package StuartMullinger.Converge7Api

Comparing the Content on Two Sites

Once installed, a new "Converge" section will appear in the Umbraco back-office. On the site that you will eventually update, click on that section and then select "Merge from Remote". You will be asked to specify the remote site which you want to compare to the current (local) site along with login details.

When you select "Compare", Converge will use these details to connect to the specified site and extract all of the back-office details. It will then do the same for the local site, compare the two and present the results in a table.

The following back-office details will be compared:

  • Content
  • Media
  • Content Templates
  • Document Types
  • Media Types
  • Data Types
  • Templates
  • Dictionary Items
  • Macros

Each comparison can result in the following statuses:

Equal

A component was found on the local site that matches the remote one, and the two components are equal. Nothing will be updated and no "action" menu will be available.

Difference

A component was found on the local site that matches the remote one, but a difference was found between the two components. An "action" menu will be available, allowing the user to choose between "Merge" and "Ignore".

RemoteNotLocal

No component was found on the local site that matches the remote one. An "action" menu will be available, allowing the user to choose between "Merge" and "Ignore".

LocalNotRemote

A local component was found that does not match to a remote one. An "action" menu will be available, allowing the user to choose between "Remove" and "Ignore".

DocumentTypeDefinitionDifference

This status is very similar to Difference and will only be shown for Content and Media. A difference has been detected between the document types (or media types) on which the Content or Media is based. The Content or Media may also be different itself.

DocumentTypeDifference

This status will only be seen when using Umbraco 7 for Content and Media. It indicates that different document types (or media types) have been set. It is possible to update these in Umbraco 7. For Umbraco 8, it is not possible to update the document type, so the components will not be considered as a match. Instead, the same component will be listed twice: as RemoteNotLocal and again as LocalNotRemote.

You can also expand each component to see the comparison of the properties of the component.

Merging the Content

You can use the "action" menus to determine the actions to be taken for each component. At the top of each section there is also a menu to set the values for all of the components in that section. When you are happy with the actions that will be taken, select the "Merge" button at the bottom of the screen.

When the merge has completed, the statuses will be set to "Merged" or "ErrorMerging". If the latter, then hovering over the status will display further information.

This blog entry describes how I used this process to transfer content from an Umbraco 7 instance to an brand new Umbraco 8 installation.

Settings

User Settings

The User Settings are available to any user and are individual to them. They are shown as the first tab when "Settings" is selected.

Remote Fetch Method

Determines the method that is used to connect to the remote server. The default value is "Server Fetch", in which this server connects directly to the remote one. For this to work the remote server must be directly accessible from the current site's server.

Alternatively, "Browser Fetch" can be used when the current site's server cannot access the remote server, e.g. if it is on localhost or behind a firewall. The remote server will still need to be accessible from the current machine, that is the one that the browser is running on. For this to work, it must be also be allowed on the remote site (see "Allow Remote Access" below). Note, "Browser Fetch" is less secure as no login details are used.

Rather than use "Browser Fetch", I recommend the use of a service like https://ngrok.com/

Local Only Default Action

This setting determines the default action on the comparison table for a "LocalNotRemote" status. It can be set to "Remove" or "Ignore".

Remote Default Action

This setting determines the default action on the comparison table when the status is "RemoteNotLocal" or "Difference". It can be set to "Merge" or "Ignore".

Note that the default actions can be customised further by creating a DefaultActionSetter class (see below).

Show or Hide Sections

Each of the sections can be hidden by using the Show/Hide options in the User settings.

Configuration

The "Configuration" tab under "Settings" determines the site-wide settings across all users. It is only available to users that have access to the "Settings" section of Umbraco.

Allow Remote Access

Determines how the API is accessed, i.e. how another Converge instance can access the information on this site, if it is acting as the "remote" site.

  • Allow Server Fetch
    Only "Server Fetch" is allowed and the caller must supply login credentials to access the information on this site.
  • Allow Browser Fetch
    Both "Server Fetch" and "Browser Fetch" are allowed. The caller does not have to supply user credentials to access the information on this site.
  • Don't Allow
    No access is allowed to the information on this site.

Where the API package has been installed, whether to allow remote access is determined by an App Setting in the Web.config file. This can be set to "Server", "Browser" or "Disable".

<add key="converge-allow-remote" value="Server"/>

Media Source

By default, the Umbraco media files are stored locally in the project's file system. When this is the case the transfer of Media must also include the transfer of the file itself. It is also possible to configure Umbraco to store the media externally (e.g. in the cloud), in which case both instances can access the same file and there is no need to transfer it.

This option instructs Converge which storage mechanism is being used: "Local" or "Shared".

Merge File Content

Templates and Macros each have both a database element and a file element. Converge will compare and transfer both, but it is possible to ignore the file element (i.e. the .cshtml file that can be edited in Visual Studio).

Can be set to "Merge" or "Ignore".

Web Client Timeout

When Converge connects to the remote server it uses a Web Client. If the connection takes longer than a specified period (timeout) then it will fail. It is possible that larger sites may take a longer time to retrieve the information and you can increase (or decrease) the timeout here. Enter the number of seconds allowed.

Converters

A number of converters are included with Converge that will update the content when a comparison and merge is made between different versions of Umbraco. For example, in version 8.6.0 of Umbraco a new "Hide Anchor" field was added to the Multi URL Picker configuration. Converge contains a Data Type Converter that adds the new field if it does not exist, defaulting its value to False.

Under settings the following tabs contain switches that allow you to switch these converters on or off. If you add your own converters then they will also be listed here.

  • Content Converters
  • Document Type Converters
  • Data Type Converters

Default Action Setters

Default action setters allow you to refine the default value of the action menu for specific components. Again, a number are already included in Converge and they can be switched on or off in this tab. If you add your own default action setters then they will also be listed here.

Customising Converge

It is possible to enhance the operation of Converge by adding some C# classes to your code. For each type, methods are provided for you to include your new class by adding it in the ApplicationStarted event (Umbraco 7) or in a Composer (Umbraco 8). On doing so, a new switch will appear under Settings, allowing you to switch the operation on or off.

An example of creating a data type converter can be seen in this blog post.

All these interfaces and classes can be found under the Com.StuartMullinger.Converge.Converters namespace.

Content Converter

A content converter can be added to update a Content item, a Media item or a Content Template before it is compared and merged. A content converter must implement the IContentConverter interface and can be added using the static method AddContentConverter(), found in the ConvergeConverters class.

ConvergeConverters.AddContentConverter(new MyContentConverter());

Document Type Converter

A document type converter can be added to update a Document Type or a Media Type before it is compared and merged. It can also update content that uses the document type. A document type converter must implement the IDocumentTypeConverter interface and can be added using the static method AddDocumentTypeConverter(), found in the ConvergeConverters class.

ConvergeConverters.AddDocumentTypeConverter(new MyDocumentTypeConverter());

Data Type Converter

A data type converter can be added to update a Data Type before it is compared and merged. It can also update document type properties that are based on the data type and the matching content properties. A data type converter must implement the IDataTypeConverter interface and can be added using the static method AddDataTypeConverter(), found in the ConvergeConverters class.

ConvergeConverters.AddDataTypeConverter(new MyDataTypeConverter());

Default Action Setter

A default action setter can be used to set the default action menu value for merging components, overriding the User Settings. It can be used to target specific elements as required. A default action setter must implement the IDefaultActionSetter interface and can be added using the static method AddActionSetter(), found in the DefaultActionSetters class.

DefaultActionSetters.AddActionSetter(new MyDefaultActionSetter());

Data Type Configuration Serializer

From Umbraco 8 onwards, the configuration of a data type changed from being a list of pre-value strings to being an object. As part of its operation Converge needs to serialize and deserialize these objects. For all of the standard Umbraco property editors I have included code that does this, however if an external property editor has been included in your project then you will also need to add a serializer/deserializer for it. This will need to implement the IConfigurationSerializer interface and can be added using the static method AddSerializer(), found in the ConfigurationFactory class.

These classes and interfaces can be found in the Com.StuartMullinger.Converge.PropertyEditors namespace.

ConfigurationFactory.AddSerializer("MyPropertyEditorAlias", new MyConfigurationSerializer());