[ Previous: Comparing two Workspace workflows ] [ Up: Developer Tutorials ] [ Next: C++ For C Programmers ]

Introduction

The application workspace-merge is a three-way tool for merging two Workspace workflows derived from a common base workflow, The underlying differencing framework operates directly on the file xml code, but the application also displays all three workflows in the workspace format. It has a lot in common with out workflow comparison tool, and we strongly recommend you look at the workflow comparison tool tutorial before this Comparing two Workspace workflows .

Sample files used in this tutorial

Merge tool layout

There are four main layout components to the application:

The file name entry widgets, where you the select the two workflows that you want to compare: WorkflowA and WorkflowB (or Base and Modified). Usually you will want to compare two workflows with a common ancestor, or where one is a modified version of the other.
The Workflow Panels show the workflows graphically in tabs similar to those in the workflow editor (but with adjustments that highlight differences).
The Difference List Panel There are fours of these that highlight the differences between pairs of workflows
The Merge List Panel List of modifications (merges) to be applied to the base workflow

These are described in more detail later in the tutorial when we look at the tool

Layout

Creating modified workflows to compare

For the purposes of this tutorial, we are going to create two new workflows based on the welcome to workspace.wsx file we created in the diff tutorial. If you do not have this handy, then use the sample workflows Examples/WorkflowTools/welcome to workspace.wsx It is important that three modified files were all modifications to the same initial workflow file as the merge tool looks at the underlying operation ids. We will then look at how the merge tool treats the changes.

Add a note to the base workflow

Open the workspace editor
Load the workflow hello workspace.wsx
Right mouse click in empty space above the Log Text operation and select Create note

Create a note
Enter text "This logs a simple welcome message"

Add a message
Save the workflow as welcome to workspace note.wsx

Change an operation label

Reload the original workflow hello workspace.wsx
Right-mouse-click on the Strings operation and select Properties

Select properties
Change the label to Message By default, this will also change the data name to Message (see below)

Change the WorkspaceInput label to Message
Save this workflow as welcome to workspace message.wsx

Opening the merge tool and loading a project

Open the merge tool workspace-merge (see Starting the application)

Create a new project from the File menu

Creating a new project
Set the base and modified workflows to be the welcome to workspace.wsx, welcome to workspace tools.wsx and welcome to workspace note.wsx workflows we created earlier

Setting the base and modified workflows

The application will automatically attempt to create a merged workflow.

The merge tool automatically attempts to merge both sets of changes into the base workflow

What do the colours mean?

The merge tool is designed as a three-way merge tool where Workflow1 and Workflow 2 are both modifications of a common base workflow. The four workflow panels show the two modified workflows on the top row; with the original (Base) workflow on the bottom left. If the three workflows do not have a common ancestry in this way, then the tool will work in the same way, but you can expect the relationships to be very complicated! To make the colours easier to start, start by ensuring that the operation icons themselves are desaturated (this is a toolbar button toggle). The colours can then be understood as follows (whatever is true first applies).

Any element that is common to all three workflows will be greyscale
Any element existing in the base workflow will be shown in the base workflow colour (here, gold). If it is also in one of the modified workflows, it will be shown in that workflow in the base colour (gold).
If it has been added to or changed in just one of the workflows, it will be shown in that workflow, with the workflow’s colours.
1. Workflow 1 has colour lavender. If you look at its panel, you can see that two operations (Workspace and Tools) are different as well as a connection.
2. Workflow 2 has colour teal. If you look at its panel, you can see that it only has one difference, a note.
This follows through to the Proposed merge workflow panel shown on the bottom right. The new note is shown with teal decoration, while the changes brought in from Workflow 1 are shown in lavender.

For more details about the changes, open up at least one of the Difference List dock widgets View->Docks-> (see Looking at differences and merges) and click on the operation or connection you are interested in.

You can save the merged workflow by giving it a file name in the line edit under “Proposed merged workflow”

Overriding the Automated Merges

Open up the dock tool Merge (View->Docks->Merges). Each row of this table corresponds to something that will be merged into the base workflow. You can see that there are actually quite a few changes to be merged even in this simple example. You can stop changes from being applied automatically by clicking on the Action column of the item you want to block (see figure below) and changing it to Ignore. Try ignoring the note added operation added (top row). You will need to click on the Apply button to see the result Note that items are often linked: if you choose to Ignore adding the new Tools operation, then the new connection between Tools and Log Text won’t be made either. If this happens, there will be more details about it in the Log dock (see Looking at differences and merges).

The Merges dock widget lists the changes that will be applied

The merged workflow if you ignore adding the Tools operation

Now click Reset and try “ignoring” the note added (bottom row)

Dealing with rejections

Now we'll change workflow 2 to the welcome to workspace message.wsx workflow we created earlier using the line editor or browse button under the Workflow2 banner.

This time, the changes made to create the two modified workflows are incompatible, so the merge is rejected.

The merged workflow is rejected

If you look at the Merges panel you can see the problem changes. Both workflows have changed the label and dataname of the WorkspaceInput. If they had happened to have used the same name, it would be updated, but as it is they are in conflict and there is no way to tell the tool which one you want. What you can do is “ignore” the conflicting changes and make any others.

Clear the Log widget
Click on the Action column of each rejected item and change the action to Ignore
Click Apply

A modified merger is successful

Refer also to the entry Workflow merge in developer's tips and tricks