Workflow analysis

The workspace-analyse tool is an application that gives, for a given loaded workflow:

A report on the workflow listing an operation and connection count, list of linked external workflows, a list of the plugins used and an operation count for each, and various warnings such as the use of deprecated operations
A pie-chart showing the distribution of its operations between the plugins it uses and
A tree showing what external workflows are used (limited to plugins available in your installation)

Workflow analysis

Starting the application

The workflow analysis application is shipped as part of a regular Workspace installation package. You can find it as Workspace analyse in your start menu. Enter a filename and press Analyse. You can also access it inside workspace-editor from the Tools menu (Open Analyse tool). It automatically inserts the current workflow if there is one loaded into the editor, but you need to click on Analyse in order to generate a report.

Workflow comparison

The application workspace-diff is a differencing tool for comparing two Workspace workflows, presenting differences visually so that they are easy to find and comprehend. It is most valuable when used to compare a base file with a modified version of it. The underlying differencing framework operates directly on the file xml code, but the application also displays both workflows in the workspace format so that you can connect the differences to the operations in a familiar format.

The Workflow Comparison Application

Looking at differences

The differences are presented in the Difference List window. Here is an example.

Difference List

Notes:

The differences are presented as a list, one item for each modified operation. Some more trivial items are hidden by default.
If the operation only exists in one workflow it will be shown as a single top-level row with a solid colour. Gold if it is only in the Base workflow. Purple, if it is only in the modified workflow. Any connections to its outputs will be shown as child rows.
If the operation is present in both but has been changed in some way, then the row will be striped gold/purple and the details given in child rows.
In the example above,
- Item 1 is an operation present in both workflows (hence striped), but a new connection (1.1) has been made in the modified workflow (hence purple).
- Item 2 is hidden by default as it is only an operation move. Click on the Show Operation moves checkbox if you want to see these.
- Item 3 is an operation that has been added in the modified workflow, and a new connection (3.1) made to it.
- Item 4 is an operation that has been removed in the modified workflow, as well as a connection (4.1) that has been removed.
- Item 5 is the root workspace, naturally present in both workflows. It shows that a Note has been moved and a plugin updated.
If your workflows contain nested workflows, you can opt to group the differences by nested workflow. (Select Group differences by nested workspace from the View menu) Note that the tool will not pick up every detail: some things are hard to show in a useful way, a lot of differences are trivial and would only serve as clutter, and others have not yet made it to the tool.

What will it pick up?

The workflow comparison tool looks for changes in:

Operations (addition/removal, labels, positions, types etc)
Connections (addition/removal, disabling, anchors etc)
Inputs/outputs (setting or changing values, addition/removal when done via the editor)
Notes (addition/removal, change of text or position)
Scheduling features
Plugins (addition/removal, change in version)

Starting the application

The workflow comparison application is shipped as part of a regular Workspace installation package. You can find it as Workspace diff in your start menu. It can also be run from the command line and integrated into applications that support external diff applications. For an example of such integration, see Configuring TortoiseSVN under Windows

Loading files

The comparison tool expects a base and a modified file. You can

Load these directly from the File selection dialogs
Load these through a project file. (A project file can be useful if you think you will want to compare the same files more than once. To create a project file, first load your files directly then chose Save from the File menu)

Command line parameters

The Workflow Comparison tool can also be run from the command line

Workflow comparison parameters

Workflow merge

The application workspace-merge is a three-way merge tool for comparing and automatically combining Workspace workflows. Like the comparison tool, it presents differences visually so that they are easy to find and comprehend. It is most valuable when used to compare a base file with two different modified versions of it. The underlying differencing framework operates directly on the file xml code, but the application also displays the workflows in the workspace format so that you can connect the differences to the operations in a familiar format. If the differences are mutually compatible, it will attempt to automatically apply both sets of changes to the designated base file to produce a new workflow which you can save.

Merging two workflows

Looking at differences and merges

Merges	Shows a list of the merges that will be applied (plus the option to reject or ignore them individually)
Difference List (B-1)	Shows differences between the base workflow and workflow1
Difference List (B-2)	Shows differences between the base workflow and workflow2
Merged Difference List	Shows differences between the base workflow and the final merged workflow
Difference List (1-2)	Shows differences between the workflow1 and workflow2
Log	Log window

Looking at the merged elements

The following is an example of a large workflow with lots of nested workflows. The base workflow is missing several connections. Workflow 1 is a copy of the base but has had two explanatory notes added. Workflow 2 has had the missing connections added, but an operation and note have been removed from the root workspace. In the figure below you can see the original two modified workflows as well as their respective comparisons to the base . The differences have been grouped by nested workspace, so that it is easier to understand where they are.

Two workflows with differences inside nested workflows

Difference List (B – 1) shows the differences picked up between the base and Workflow 1. There are just two: a note has been added to the Workspace Executables nested workflow and another to the Documentation workflow. You can navigate to either workflow by clicking on the workflow name. Difference List (B – 2) shows the differences picked up between the base and Workflow 2. There are more of these, so just some have been expanded. The solid colour of item 1.1 means that the note is only present in one workflow, and it is gold to signify that it is present in the base (only). Item 12.1 shows one of the connections that has been added to Workflow 2 and you can see attribute changes an input array at item 20.1 (a new array element has been added to hold the new connection). As the two modified workflows did not have any conflicting modifications, the automatic merge was successful. You can see the result in the figure below.

Merging two workflows with differences inside nested workflows

The merged workflow has the annotations, the new connections as well as the removed note. The auto-merge algorithm assumes that anything that has changed is wanted, and currently the user cannot choose a subset of these. The Merges window show the changes that were made: if you click on a row, it will trigger the matching differences to be selected in the difference trees and workspace widgets. Note that connections changed from one input array index to another are shown as pairs of connections added and removed.

What will it pick up?

The differencing engine is the same as used by the comparison tool, so the same set of differences will be displayed. However, not all differences can be automatically merged into a new workflow. In general, if something is added/removed/changed in only one of the workflows, or identically in both workflows, and it can be practically merged, it will be. You can see what the result of an automatically merged workflow would be in the Merged Difference List and Merged Elements dock windows. Note there is currently no way for the user to influence result other than automatically rejecting merges that it would otherwise effect.

Starting the application

The workflow merge application is shipped as part of a regular Workspace installation package. You can find it as Workspace merge in your start menu. It can also be run from the command line and integrated into applications that support external diff applications. For an example of such integration, see Configuring TortoiseSVN under Windows

Saving the merge workflow

If you specify a file name under Proposed merged workflow then a successful auto-merge will create or overwrite this file. If this has not been set when the merge is run, then set it and then run Apply merge from either the Actions menu or the toolbar button.

Configuration

Workflow panel user interface corresponds to the workspace editor's User Interface settings
Startup whether to automatically load plugins
External applications set an external differencing tool
Colours change the default colour scheme
Default merge settings set control of how the various detected differences are treated.

Command line parameters

The Workflow Merge tool can also be run from the command line

Workflow merge parameters

Workflow global name comparison

What is a global name file and how do you get one?

A global name file is an XML-based file that can be created from any Workspace workflow which has had global names assigned. It stores the current values of all the global names and can be reloaded later to overwrite the then-current values. To create a global name file, load your workflow into the workspace editor and select Export global names from the File menu.

Global name comparison

Looking at differences

The figure above shows differences between two global name files that were produced by exporting global names from the same workflow at different times. As in the workspace-diff and workspace-merge tools, a solid colour indicates an entry only in one file, and a striped entry indicates an entry that is in both files but has a different value. Global names can stand for single values or more complex ones, even entire operations. In the Global name column, entries in black are global names, whereas entries in grey are other identifiers such as input names. Items can have both global names and identifiers. If you check the Show Identical items box, then all the global names will be shown, even if they have the same values in each file.

Check the 'Show Identical items' box to see all the values

Entries in columns FileA and FileB ay have icons: these indicate the type of element that the global name is attached to. It may be a simple scalar input that can be edited directly, or something more complicated. More complicated types are indicated with an icon as shown in the figure below.

Input type icons, from left to right: (a) a complex input (b) an input array (c) an output (d) an operation

Here, an element associated with a global name had changed (NikonZ_SetConfig). It was a complex element, with multiple sub-elements associated with the same global name. It is striped to indicate that both files included that global name. The File Format global name was set in both files, it was different in each file. High ISO noise reduction had a value only in File A.

Editing values

You can use the globals diff tool as an editor, whether you have one or two files loaded. Check the ShowIdentical Items box so that you can see all the itms (not just those that are different in the two files). Entries can be changed by:

Double-click on a value to change it

double-clicking on the item you want to change (if it is a simple input) or
moving the value (or values) from one side to the other using the context menu. If the item is not a single input value (for example it's an entire operation or complex input element) you will be prompted to confirm which subitems you want transferred

Copying a simple input

Copying a complex input

Comfirm the entries you want to copy over

if the values are strings, you can bring up a string comparison widget (helpful for long strings such as scripts)

Choose String comparison from the context menu

The string comparison widget

Changing the default editors

As the global name files don't record datatypes, the application infers the data types to be int, uint, double or color based on any values that are set. The default is to assume the value is a string and should be edited with a line edit (or text editor if it is long).

You can see and change the inferred data types and chosen editor widgets if you check the Show editors box. In the case below, the datatype was inferred to be an integer. You can change to a bool or string if you prefer: note that editor changes are not saved when you close or save the file.

Double click on an Editor column to change the data type or widget used

Saving your work

When you change the values, three things happen:

The background colours change to reflect the current differences beween the files
An asterix is placed next to the FileA or FileB labels next to the input filenames

An asterix shows that the file has changed
The Save File menu item will be enabled

Save your changes

Starting the application

The global variable comparison application is shipped as part of a regular Workspace installation package. You can find it as Workspace global name diff in your start menu. It can also be run from the command line and integrated into applications that support external diff applications. For an example of such integration, see Configuring TortoiseSVN under Windows

Command line parameters

The global names comparison tool can also be run from the command line

Global names diff parameters

Workflow validation

Introduction

workspace-analyse-batch is a console command that looks for overt problems in loading or running workflows. Use this to check for warnings or errors generated when the workflow is run as-is. By default, it swallows most the of the log contents and sends a summarised display of the generated log output to the console output. Optionally, you can specify a log file and then all log messages generated will be saved there.

For information about running a Workspace application from a command line and setting up the system path, please refer to the general guidelines given in Running the workflow from the command line .

Open up a terminal window on your machine.
- Under Windows, do this by clicking Start, Run, then typing in cmd and clicking run.
- Under Linux, load up your favourite terminal app. You probably already have one open.
- On the Mac, launch the Terminal application from the Applications / Utilities folder in the dock.
Enter the command
```
workspace-analyse-batch --help
```
You will see something like the following output displayed. Note that there are other options available common to all workpsace console applications that I have not shown here. Note that you must give a directory or file name. If you give a directory name it will run the validator over all workflow files in the directory.

Usage: workspace-analyse-batch [OPTIONS] [directoryName]

 --help                         Show help summary
 --version                      Show version information
 --no plugins                   Don't load plug-ins
 --no-user-plugins              Only load the default plugins that ship with Workspace
 --no-settings                  Don't load user settings
 --no-rendering-plugin          Don't load the rendering plugin
 --config [filename]            Specify configuration filename
 --recursive                    Search recursively
 --logFile [filename]           Log full output to file
 --resave-workflows             Resave all workflows
 --run-workflows                Run workflows
 --staticAnalyse                Run static analyse on the specified workflows instead of running them
 --dependencyComponent [component] Print dependencies of the workflow. Works with --staticAnalyse only
 --nameFilters [*.wsx;*.xml]    Name filters separted by ";" (default *.wsx)
 --workflowTimeout [10000]      Workflow timeout (ms)
 --autoAddConfigEntries         Automatically add a workflow configuration entry if it doesn't already exist
 --showRepeatedEntries          Show repeated log messages generated within the same workflow
 --listPlugins                  Print plugin versions

What the parameters mean

recursive Runs the analyser over all files in subdirectories as well.
logFile Writes all log output to the given file name (not just warnings and errors)
resave-workflows Resaves all workflows to file. This is useful if any of the workflows contain old operations that have been directly replaced in the current workspace code. When a workflow contains deprecated operations, a warning log message is generated. If there is a directly replacement available, then if the workflow is saved to file the replacement operation will be saved with it and the warning log message no longer generated.
run-workflows By default, the validator will load but not run workflows, and report any warnings and log mesages generated. Set the run-workflows parameter if you want to look at logs generated by running the workflow as well. Use this in conjunction with the workflowTimeout parameter
workflowTimeout If you set the run-workflows parameter, the workflow may take a long time to run. By default, each workflow will be aborted after 10s. To change this, set the workspaceTimeout entry to the time period you want (in ms)
nameFilters By default, the analyser identifies Workspace workflows as files with the suffix .wsx If your directory(ies) contain workflows with other suffixes, you can specify how you want a workflow identified by add the nameFilters parameter. Separate lists of suffixes with a semicolon (";")
autoAddConfigEntries Sometimes the validator will generate errors that you would like it to ignore. You can instruct the analyser to ignore a particular error string for a particular workflow by creating a workflow-analyse.config file in the workflow's directory, and adding an audited_logs entry for the workflow. If you set the autoAddConfigEntries parameter, a stub entry will be automatically created for every workflow analysed, and a workflow-analyse.config file will be automatically created if it does not already exist. See The workflow-analyse.config file for more information.
\ showRepeatedEntries Usually you only want to see an error or warning message once for a given workflow, set this to true to show every instance of a message

The workflow-analyse.config file

Before the workspace-analyse-batch tool loads a workflow, it checks first to see if there is a file called workflow-analyse.config in the workflow's directory, and if so, whether there is a workflow entry corresponding to the workflow in question, and if so, whether there are any audited_logs defined. Whenever a log message is generated, it is first checked against any audited log entries - if it matches an entry, the log message is discarded.

The workflow-analyse.config file

This is used to tell the analyser that a given log message is expected, or OK, and to ignore it. Audited logs must be explicitly set by manually editing the workflow-analyse.config file and creating a log entry. To simplify this process, if you set the autoAddConfig parameter, workflow-analyse.config files will be automatically created with a stub entry for each workflow encountered. (So you can run workspace-analyse-batch once to generate stub entries, add any log entries you want the analyser to ignore, and then run it again)

Configuring TortoiseSVN under Windows

The workflow comparison, workflow merge and global names tools can all be run from the command line, and therefore integrated into applications that support export external diff and merge programs. One such program is TortoiseSVN, and here are instructions on how to integrate the workspace tools into this.

Make sure you have TortoiseSVN installed
Locate your installed workspace executables: workspace-diff workspace-merge and workspace-globals-diff. If you have a Windows machine, the default installation will have these in c:/Program Files/csiro.au/workspace/bin
TortoiseSVN integrates itself into Windows explorer context menu. Open Windows Explorer, right-click on any file, and select TortoiseSVN->Settings
Select DiffViewer

Integrating workspace-diff and workspace-globals-diff into TortoiseSVN

To integrate the diff tools as the default for .wsx and .wsg files respectively, click on the Advanced button and add workspace as the default program with parameters as shown below

Integrating the comparison tools into TortoiseSVN

Integrating workspace-merge into TortoiseSVN

To integrate the merge tool as the default for .wsx files, click on the Merge Tool, and then the Advance button and add workspace-merge as the default program with parameters as shown below

Integrating the workflow merge tool into TortoiseSVN