Workspace Workflows: Global Names

What is a global name?

A “global name” is an identifier given to an operation, input or output that is assumed to be unique over an entire workflow. Consequently, a global name allows a particular input or output to be identified without having to know where it is in the workflow, or even which operation it belongs to. If you have done many of the Workspace tutorials, you’ll have come across “global names”. Maybe they can help in ways you haven’t thought of.

Global names help to identify key inputs and outputs

Global names are really useful: as they are globally unique, the values of inputs and outputs with global names can be changed or read using linked external applications. Sometimes you are looking to simplify things for the user, and global names help identify a few key inputs and perhaps outputs. Importantly, you can use global names to create custom user interfaces, custom widgets and custom applications.

Save your settings to file

But you are not always looking to simplify things. Often workflows are complex, and have many different input values that you want to control. When you have a lot of workflows settings, or want a robust way of saving and restoring system settings, you can use global name files.

Why create a settings file?

• Saving settings gives you a record of the settings you used.
• When you next need to run the workflow you can load a settings file to return to a previous known good set of parameters.
• You want to run the workflow from the command line, but not have to set lots of parameters: you can just set one, the settings filename

Use the same workflow with different settings

You can of course have multiple global names files for the same the workflow too. This saves time and errors. Moreover, if you consider a workflow to be a program then global names can be thought of as the command line arguments you feed it on a particular execution.

Some cases where that could be useful…

• If you run the same workflow but for totally different reasons, for example some days you look for all overdrawn accounts but other times you look for your largest depositors, then you may be able to use the same workflow, just use different global name files (one that looks for the lowest balances and one that looks for the highest.)
• Consider a Workspace workflow or application that access resources, for example remote servers (so different IP addresses), a SQL database (with different SQL queries) and even uses regular expressions to filter outputs, then you will possibly need to enter (or modify) different sets of these values every time you run the workflow or application.

The Global Names window

When working with global names, you will probably find the Workspace editor’s Global Names window helpful both for viewing and editing values. If you cannot see it, you may need to make it visible using the View menu, that is View->Docks…->Global Names

Compare your settings

Finally, if you want to compare two workflow settings files, then you can use the Workspace global name diff application (distributed as part of the Workspace package) to pinpoint any differences or errors. You can also use it to see what global names have been set.

Learn how you can use global names to run workflows from the command line, to link Workspace workflows to link custom user interfaces, and reliably save and restore complex workflow settings

• Running workflows from the command line
• Creating and using a custom user interface
• Saving and restoring workflow settings
• Comparing two workflow settings files

Running workflows from the command line

What you need to do:

• Choose which inputs you want the user to be able to change: assign a global name to each
• Start up a terminal window on your machine.
• Run your workflow through the workspace-batch application workspace-batch sample-batch.wsx If your workflow runs as-is in the workspace-editor, it will run without setting any extra parameters.
• Vary any of your chosen inputs using global name parameters

Running a workflow from the command line: an example

Now are going to look at how we might apply this to a workflow that reads in a multi-column data file, creates a chart and saves it to file.

Let’s see what we need to do to run it from the command line. This workflow has eleven operations, and about twenty unconnected inputs. We could add twenty global names if we wanted to, but most of them can be used as set in the workflow. Let’s just set global names for the inputs we want to vary: maybe they are the input filename, the output filename and the column to chart.

Since the workflow file itself has all the input values it needs, we could run the workflow without setting any parameters, and it would plot the area column and use plotsample.csv and outputimage.png as the input and output images (see the Global Names table in the figure above).

workspace-batch sample-batch.wsx

Here’s how to run it if we want to use the same input file, but plot the perimeter rather than area, and save it as perimeterchart.png

workspace-batch –globalName column perimeter –globalName outputFile perimeterchart.png sample-batch.wsx

For more details about running a workflow from the command line, see Batch Execution and for charting, see
Visualising data with Charts >

Creating and using a custom user interface

Create a custom interface and link it to a Workspace workflow

• Decide what inputs you want the user to be able to change and what outputs you want to see. Assign a global name to each
• Design your GUI (Workspace includes a GUI design tool). Include a widget for each of the workflow elements you’ve selected
• Link each of the workflow elements in turn to the GUI by dragging them over to the widget you’ve designed
• Save your interface (.ui) file and open it up from inside the Workspace editor
• You are ready to go. Execute the workflow.

Designing a custom interface: an example

Here’s an example of the process using a workflow similar to the one we looked at earlier. It plots one of the data columns
using a Chart widget, but doesn’t save anything to file.

Decide on your key inputs and outputs

As in the previous example, in the Workspace editor you can (amongst other things) change which column of data is plotted by changing the Column name input of the Get area column operation. We also want to use a chart widget to display the plotted data, so we need to identify the Chart output of the Create chart operation.

We are going to create our own graphical user interface (GUI) which has a single line edit widget to change the column name, the label “Column”  and a chart widget to show the result.

Assign them global names

This time we need to set just two global names: one to identify the Column name input, and the other the Chart output. Let’s call them column and chart

Design your GUI

Next open up QtDesigner from within the Workspace editor and create a new custom widget. QtDesigner is a graphical-user-interface design tool that is supplied with Workspace.

You’ll need a line editor widget for changing the column name, and a chart widget for display. Give the input a label.

Link your key inputs and outputs to your GUI

Link each of the workflow elements to the custom interface by dragging the element from the workflow to Qt Designer.
Now save the file and you’ll be able to open it up inside the Workspace editor.

Use the custom user interface you just created

Go back to your workflow inside the Workspace editor. Load the custom widget and start executing the workflow… That’s it! You can minimise the main workflow window if you want (but don’t close it)

For more information about custom interfaces, see Working With Display Widgets For more information about how developers can use this process to create custom widgets and applications, see Writing a Custom Widget and Creating a standalone application

Saving and restoring workflow settings

Using workflow settings files means that you can switch between sets of parameters easily and with a much lower likelihood of errors. Consequently, it helps make experiments repeatable, and is simple alternative to changing many variable settings individually. You should always edit global name values though the Workspace-editor: don’t edit the global names file directly. Try using the Global Names window.

The workflow below has multiple settings that will change depending on the database and file you want to look at.

There are different categories of inputs

• Values that you never want to change (so you don’t need to give them global names)
• Groups of values you want to store in a settings file
• Dynamic parameters that you want to change frequently (perhaps you’d like to specify the output filename separately)
• Sensitive parameters that you don’t want to save at all (maybe not your password).

For many applications you will want to use more than one of these categories.

Saving and loading settings

Prepare your workflow by setting global names on all the inputs and and outputs you want to change. After that, you can then save the global name values whenever you like, say before you run the workflow. Finally, use File->Export global names… to save them and File->Import global names… to reload them later on.

Running your workflow from the command line using a settings file

Here’s how you’d go about running workflow workspace-sample.wsx from the command line when you want to use the settings in file Melbourne_01sx_table03.wsg

workspace-batch –globalNameFile Melbourne_01sx_table03.wsg workspace-sample.wsx

You can read about using SQL databases with Workspace: see Basic SQL database and to learn about running a workflow from the command line, see Batch Execution

Comparing two workflow settings files

Once you start using global name settings, you’re going to want to compare the different versions, and that’s when you will find the Workspace global names diff tool helpful. It shows you what values you have set and highlights differences between settings files.  Look for it where you normally find the Workspace editor.

How it works

As an illustration, open the application, and load two files you want to compare as File A and File B. The example below shows two possible sets of settings exported from the global name settings file example above. By default, it will only show settings that have changed, but if you check the Show all global names box you can see everything. Any setting changes should be made through the Workspace editor

Workspace

For more information about the Workspace see User Documentation
As always, we would be really glad to hear from you if you have any feedback.