Project: Merge - Merge Tutorial

As of 2016-01-20 Project: Merge is officially a discontinued product
and we are therefore no longer selling new licences.

Existing licences and installations of Project: Merge will continue to work,
and most of this website will continue to exist.

We do, however, have a new website at osocorporation.com where you can find information
about the successor to Project: Merge, Oso XML Merge.

All accounts for this website have been migrated over to the new site, and you should be able to
view and edit your existing licences as before - as well as upgrade them to Oso XML Merge licences.

Contents

5 - Tutorials

1 - Merging Two XML Files

Books1.xml
<?xml version="1.0"?>
<catalogue>
  <book id="bk101">
    <author>Gambardella, Matthew</author>
    <title>XML Developer's Guide</title>
    <genre>Computer</genre>
    <price>44.95</price>
  </book>
  <book id="bk102">
    <author>Ralls, Kim</author>
    <title>Midnight Rain</title>
    <genre>Fantasy</genre>
    <price>5.95</price>
  </book>
</catalogue>

Books2.xml
<?xml version="1.0"?>
<catalogue>
   <book id="bk106">
      <author>Randall, Cynthia</author>
      <title>Lover Birds</title>
      <genre>Romance</genre>
      <price>4.95</price>
   </book>
   <book id="bk107">
      <author>Thurman, Paula</author>
      <title>Splish Splash</title>
      <genre>Romance</genre>
      <price>4.95</price>
   </book>
</catalogue>

This tutorial shows you how to merge two simple XML files into one. It leads you through loading your XML files, creating a new format specification, seeing the first merge results, and then improving those results by modifying element properties in the format specification.

To follow this tutorial you will need the two sample XML files listed on the right. You can download each of these files through the following links: Books1.xml and Books2.xml. Save both of these files to your computer and launch Project: Merge through the shortcut on the Windows Start Menu.

When launched directly from the Start Menu, Project: Merge will display the Open Dialog and prompt you to select the XML files you wish to open and what kind of operation you wish to perform on them. The open dialog with the correct options selected.

The open dialog with the correct options selected.

Operation Type

For the purposes of this tutorial you should select the XML File Merge option.

Base File

Because this tutorial is merging two XML files, you should ensure the Use a Common Base File option is unchecked.

Left and Right Files

Click on the ... buttons next to the Left File and Right File edit boxes to browse and select the XML files you downloaded earlier.

Clicking OK will instruct Project: Merge to load the files. You should see a progress bar briefly before being shown the following dialog box: The dialog box asking you to create a new format specification.

The dialog box asking you to create a new format specification.

Project: Merge uses a format specification to help define which parts of an XML file it should use to help identify and track other parts of the file. If you look at the XML files being used in this tutorial, for example, each book element has an id attribute which uniquely identifies each book in the file. Through the format specification we will create, Project: Merge will know to use the id attribute to identify each book element.

It should be noted that you cannot compare or merge any XML files without a format specification. Click Yes to begin creating a new format specification for these XML files. You will be shown the Create Format Specification Dialog:

The Create Format Specification dialog box showing the initial settings for the new format specification for this tutorial.

Specification Name

Give the format specification the name Books. Specification names are for your reference only, so we recommend you are as clear as possible when naming your file specifications.

Filename Wildcards

Project: Merge matches format specifications to XML files through the name of the root element in the file. If several format specifications match the root element, Project: Merge will use the filename wildcards specified here to determine which format specification is to be used. For the purposes of this tutorial, we will leave this empty. You can always change these settings later through the Preferences Dialog.

Once you have selected the appropriate options, clicking OK will instruct Project: Merge to create the new format specification and continue loading the files. When it has finished, you should be presented with the result of the merge which should look similar to the following:

At first glance this doesn't look very promising. While both files have been processed and merged, the results are far from perfect. Each book in each file has been literally merged with its counterpart, so each now has two authors, two titles, etc. It gets worse when you look at the id attributes. As each book was merged Project: Merge discovered the id attributes and decided they conflicted with each other (as indicated by the light-red background behind them).

Fortunately, we're not finished yet.

If you take a moment to look at the overview pane down the left side of the Project: Merge window you can see very clearly where Project: Merge has decided to select parts from the left file (Books1.xml - marked in blue) and the right file (Books2.xml - marked in green). You can also see where the conflicted portions are (marked in red) and where the two files are identical (the blank areas between the differences). You can quickly navigate to anywhere in the results by simply clicking in the overview pane. When you have finished looking at the current merge results, scroll back to the top of the window.

We will now attempt to improve the results of this merge. As mentioned above, the XML files used for this tutorial contain lists of books where each book has a unique identifier - the id attribute. We can instruct Project: Merge to use these id attributes to identify each book in the file. By doing this we will be able to drastically improve the results of the merge.

Right click over the book element or any of its attributes and select 'book' Properties.... You will be presented with the preferences dialog with the panel for the book element selected as shown below:

The Element Properties panel allows you to control how Project: Merge identifies elements. Project: Merge can use the attributes of an element, child elements, or character data to identify different elements within an XML file. When you create a new format specification, by default, Project: Merge do not attempt to uniquely identify any elements beyond comparing matching element tags.

For this example, we want to use id attributes to uniquely identify book elements:

Order of Children

First off, we inform Project: Merge that the order of child elements for books is unimportant. Whether the title of a book appears before the author's name in the file or not doesn't change the meaning of the data.

Identified by

We want books to be identified by Attribute(s), so select that option. A list of known attributes for books will appear below. There is only one entry, id, and it should be selected.

Clicking OK will save our changes to the format specification and instruct Project: Merge to reload the current XML files using the updated format specification.

Finally we have merge results that are looking a lot better. With the changes to the properties for the book element, Project: Merge now understands that a book with an id of 'bk101' is different to a book with an id of 'bk106'. The two input files have been correctly merged into a single output file.

All that remains to be done now is to save the results of the merge. This is achieved either by selecting Save from the File menu, or by clicking the save button on the toolbar. (Project: Merge will also prompt you to save the merged results if you haven't already done so when exiting.)