Edit online

Integrating the File Merge Tool with a CMS

Oxygen XML Web Author provides a file merge tool that is offered as an API for CMS integrations.

The Merge Tool is a useful feature for cases where multiple users work with the same file in parallel because it can be used to resolve conflicts when committing changes to a repository. Also it can be used to compare current unsaved changes with the document stored in the CMS.

Use-cases

  • A CMS often keeps track of multiple versions of a file. For example, if a new legal requirement has to be addressed in the documentation, all the versions of the file have to be updated. One option is to make the change to the oldest version and merge those changes in the other versions.
  • If a CMS supports a review workflow, the copy of the file that is sent for review can be changed in the CMS for other reasons. On the other hand, the review workflow also results in some updates to the file. At the end, these updates need to be merged in the version on the CMS.
  • In other systems (such as Git), different users can edit the same file in parallel. When they finish editing, they have to merge the changes.

Integration Approach

To launch the Web Author Merge tool, it must be started with the following URL parameters:

url

The OXY-URL of one of the files to be merged. This is the merge target. It will be loaded in the left part of the merge tool, will be editable and will contain the merged version of the file.

diffUrl

The OXY-URL of the other file to be merged.

diffType

Use merge for the value to allow merging. If this parameter is not specified, the left editor won't be editable, thus the tool will work as a read-only diff tool.

diffBaseUrl

The OXY-URL of the base file used for the 3-way merge process. Usually, a file version where the two versions diverged (the common ancestor). If this parameter is not specified, the tool will perform a 2-way diff and will not be able to detect conflicts.

leftEditorLabel

Use this URL parameter to customize the label for the left editor. By default, the label presents the file name.

rightEditorLabel

Use this URL parameter to customize the label for the right editor. By default, the label presents the file name.

Keep in mind that the above parameters have to be set as URL parameters and note that there are others that can be used to configure various aspects of the editor.

An example of a merge URL can be found on our public demo web page: Compare Files sample.

After the user finishes the merge, the merged content will be in the left-side pane. To get the merged content, you can use JavaScript code from a plugin as follows:

/** @type {sync.api.Editor} */
var editor = ...;
editor.getContent((err, content) => {
  if (!err) {
    // Save the content of the editor
  }
});