Workflow as a Tool

This tutorial is the second in series of three tutorials that provide a general practical introduction to pSeven. It discusses certain features that can be used to customize the workflow interface in Run. Such customization allows to prepare a workflow for users who focus on performing studies and analyzing results and may be not experienced in workflow editing.

Note

This tutorial continues the Simple Workflow tutorial and requires the workflow created there.

Before You Begin

This tutorial requires an existing prjTutorials project. If you have not created this project yet, see Tutorial Project first. You will also need the workflow created in the Simple Workflow tutorial.

  • Open the prjTutorials project.
  • Open wfSimpleWorkflow (SimpleWorkflow.p7wf).
  • Select File ‣ Save Workflow As... to create a copy of the workflow. Save the workflow as wfSimpleWorkflowTool.
  • Verify that you are editing wfSimpleWorkflowTool and continue with the tutorial.

Task

Taking the toy workflow from the Simple Workflow tutorial as an example, assume it was a first step in the following task:

Create a workflow that generates random experimental designs. The user must be able to set sample dimension, the number of points to generate, and value range. The user may be unfamiliar with workflow editing and block configuration.

The current workflow does not suffice because:

  • Matrix dimensions are fixed (in Size). To change sample dimension or the number of points, you have to reconfigure the Size block.
  • Similarly, the value range is fixed in RandGen configuration and you have to reconfigure the block to change settings.

This is too much handwork for such a simple task. The solution requires several changes to workflow structure (blocks and links) and configuration (Run settings).

Solution

In order to resolve the issues noted above, this tutorial suggests the following improvements:

  • Instead of using constants, add a workflow input and link it to RandGen input ports. The user can then specify the number of rows and columns in Run instead of configuring the Size block in Edit.
  • To show results in Run immediately, add a workflow output and link it to RandGen.value.
  • Add value range settings in RandGen to workflow parameters. Again, the user can change parameters in Run without switching to Edit.

As a result, the workflow will become a simple tool with a custom Run interface which can be used even by a person with no experience in workflow editing.

Workflow Inputs and Outputs

In fact, every workflow is contained inside a special block. This block has no editable name; in various configuration dialogs it is shown as <root>, and in Edit you can only see its “bounds” labeled [In] and [Out].

Aside from the above aspects, the workflow root is just a Composite block which you can find in the block library. In particular, this root block can have input and output ports (root ports) which serve two purposes:

  1. Root ports enable using a workflow as a block. This advanced feature is intended for creating complex workflows and custom components, and is discussed in more details in the Workflow as a Block tutorial.
  2. In Run, root ports are shown as workflow inputs and outputs.

Thus, to make the settings for the sample dimension and the number of points available to the user, you can add root inputs and link them to RandGen. The Size block will no longer be needed.

There are two possible ways:

  1. Add root ports and create links manually.
  2. Use the uplink function to add all required ports and links automatically.

Let us compare these two methods using uplinks first.

../_images/page_tutorials_workflow_configuration_01_uplink.png
  • Remove the Size block (select it and hit Delete on your keyboard). The link from Size to RandGen is removed automatically.
  • Select RandGen and click b_uplink on the edit toolbar 1 to open the Uplink dialog 2.
  • Select two ports: cols and rows (hold Ctrl or Shift for multiselection). Do not select value yet.
  • Click b_uplink_connect to uplink the selected ports.
  • The dialog will show two new workflow inputs 3 that are going to be created. Their names are generated automatically, but you can change them right here if you wish (to edit, double-click the name, or hover it and click b_editval). As a side note, this makes it possible to specify the same name in the Uplinked to column. Such configuration is allowed and will result in adding a one-to-many connection.
  • Accept default names and click b_ok to apply changes.

Note

The above instructions describe uplinking a specific block, but you can bring up the Uplink dialog without selecting a block first. In this case, it will show all blocks and ports, allowing you to uplink many blocks at once. Since a full list of ports may be very long, the Uplink dialog provides a filter which accepts partial block and port names. You can see that selecting RandGen before opening the Uplink dialog in fact simply filtered the list automatically by the block name: “RandGen/” in the filter means “show all ports of the RandGen block” (the forward slash is used as a block/port name separator).

Uplinking created a new link in the workflow.

../_images/page_tutorials_workflow_configuration_02_newuplink.png

The sources of this link 1 are new input ports automatically added to the workflow root block. These ports are shown in Run as workflow inputs. To see them in Edit, double-click any of the workflow boundaries 2 to open the root block configuration.

../_images/page_tutorials_workflow_configuration_03_rootconf1.png

Switch to the Ports tab 1 and note there are two inputs. Their types 2 and descriptions 3 are copied from uplinked ports. Both of them are editable; such edits do not change properties of uplinked ports (RandGen.cols and RandGen.rows), because they apply to the root block configuration.

Note

To avoid confusion: port names and descriptions in the root block configuration are intended for workflow designers. Workflow inputs and outputs shown in Run have additional descriptions and can be assigned aliases, much like port monitors. It is recommended to use port descriptions in the root block configuration for technical details, such as the location of uplinked port. Then, to customize workflow’s Run interface, you can override “technical” port names and descriptions in workflow configuration (see further for an example).

While on the Ports tab, note that you can add (and remove) ports here. This is the manual method of adding workflow inputs and outputs which was mentioned above. Let us now use it to add a workflow output.

  • Click b_blconf_add in the Outputs pane.
../_images/page_tutorials_workflow_configuration_04_addoutput.png
  • Specify:
    • Name: value (to automatically match with RandGen.value when linking).
    • Description: any text, can be empty or include a developer-style comment. In the final workflow this description will not be shown in Run (see the above note on root port descriptions).
    • Type: select RealMatrix by ticking the appropriate box. Note that this is required since the default type is RealScalar which will not accept a matrix generated by RandGen.
    • Leave other settings default.

Back in the configuration dialog you can see that the value output is added.

../_images/page_tutorials_workflow_configuration_05_rootconf2.png

Click b_ok to finalize configuration. Note that this time the link from RandGen.value is not created automatically. Now you should manually add this link to send the block output to the workflow output.

../_images/page_tutorials_workflow_configuration_06_outlink.png

After adding the output link, switch to Run to see the effect of the latest changes.

../_images/page_tutorials_workflow_configuration_07_run_io.png

Verify that links 1 and 2 exist, and workflow inputs 3 and output 4 now appear on side panes. Note that the monitor for RandGen.value 5 created earlier is no longer needed: this port is now uplinked to a workflow output, and all workflow inputs and outputs are monitored automatically. You can safely disable this monitor in Run or even remove it in workflow configuration so that it does not distract users.

Finally, you can make the names and descriptions shown in the Inputs and Outputs panes more relevant. To edit them, open workflow configuration b_runconf and take a look at input and output details on the General tab.

../_images/page_tutorials_workflow_configuration_08_io_conf.png

Similar to monitoring, you can set aliases 1 and descriptions 2 which are then shown in Run instead of port details.

  • Edit aliases and descriptions as you wish.
  • Optional: switch to the Monitoring tab and remove existing monitor.
  • Click b_ok to apply changes.

Note the changes in the Inputs pane, for example.

../_images/page_tutorials_workflow_configuration_09_wfin.png

Now when you run the workflow, it reads values entered here and sends them from root input ports to RandGen inputs, starting the block.

Let us summarize how the sample size input works, for example:

  • RandGen has rows input. This port is required to start and it sets the number of matrix rows.
  • To make this setting available to the user, RandGen.rows is uplinked to the root port rows. It makes the Run input appear.
  • The root port name is somewhat irrelevant for the end task (sample generation). To explain its role, it is assigned an alias (“Sample Size”) in workflow configuration b_runconf. Also, the default port description is replaced with a better one.
  • Now the user has an understandable control which sets the sample size.

Now you can note that there are a couple of warnings in the Issues pane.

../_images/page_tutorials_workflow_configuration_10_wfin_issues.png

These warnings appear because pSeven sees that workflow inputs are not specified. To resolve these issues, you can add input defaults by assigning values to the root input ports. Note that defaults also give a user a hint about expected inputs, which is another reason to add them.

  • Switch back to Edit and open the root block configuration.
  • Switch to the Ports tab.
  • Specify port values in the Inputs pane (make sure they are valid).
../_images/page_tutorials_workflow_configuration_11_wfin_defaults.png

A value on port is used when there is no other data source (such as a link connected to the port).

../_images/page_tutorials_workflow_configuration_12_rundefaults.png

Note

Values can also be assigned to ports of other blocks, not only to the root block. Related example can be found in the Results and Reports tutorial (section Port Values).

Save the workflow and try running it without specifying inputs.

../_images/page_tutorials_workflow_configuration_13_defrun.png

The workflow runs, accepting defaults 1, and generates a 2x10 matrix 2 which you can now view in Run thanks to the added workflow output (to open the matrix viewer, double-click the output value and click the details button 3).

Parameters

Parameters are used to make some block options and ports accessible from Run. With parameters, you can:

  • Give the user in Run a simple control over selected block options — for example, some options that are changed frequently. Parameters can be changed quickly without opening block configuration. We are going to use this feature to add workflow parameters that set the range of values in the generated sample.
  • Send values to ports directly without uplinking them to workflow inputs.
  • Set the same value to many options at once. Parameters have aliases, and if two or more options use the same alias, specifying its value sets all these options.
  • Similarly, send the same value to many ports. As an example, this can be useful if there are two blocks which require the same input constants.

The range of sample values is set by the high and low options in RandGen (the lower and upper value bound).

  • Switch back to Edit and open RandGen configuration.
../_images/page_tutorials_workflow_configuration_14_randgen_params.png
  • Switch to the Options tab.
  • Select the high and low options in the Parameter column.
  • Click b_ok to apply settings and close the configuration dialog.

New parameters now appear in the Configuration tab in Run.

../_images/page_tutorials_workflow_configuration_15_runparams1.png

You can change parameter aliases and descriptions in workflow configuration b_runconf on the Parameters tab. Note that you can also add parameters from here (click b_blconf_add on the toolbar to see available ports and options).

../_images/page_tutorials_workflow_configuration_16_param_conf.png

Details you input in workflow configuration are now shown in Run instead of original option names and descriptions.

../_images/page_tutorials_workflow_configuration_17_runparams2.png

Note that the configuration shows some default values (displayed in gray italics). These defaults are option values specified in block configuration. You can try changing option values in RandGen to see how it affects the parameter default shown in Run.

Option parameters work in the following way:

  • If a parameter value is not specified in Run, the workflow accepts option value from the block.
  • If a parameter is specified, its value overrides the option value from block configuration.

Note that changing parameter values has no effect on option values in block configuration which you see in Edit. Parameters are run settings, related option values work as defaults.

Introducing parameters in a workflow provides another advantage: you can create preset combinations of parameter values.

../_images/page_tutorials_workflow_configuration_18_preset1.png

Currently the workflow has only one default preset 1. Let us keep it default indeed (do not specify parameter values) and add another preset with a different value range.

  • Click b_preset_new on the context menu 2 and input the name for a new preset. For example: range: [-1, 1].
  • This action creates a new preset with empty values and automatically makes it active. Specify parameter values for this preset (-1.0 and 1.0) to make them agree with the preset’s name.
../_images/page_tutorials_workflow_configuration_19_preset2.png

Note that the lower bound value 1 is in bold, indicating that it is different from the option value in RandGen configuration. Compare it to the upper bound one 2 displayed in plain font: this value is specified by the preset, but it is the same as the option value set by the block. So both values are shown in a different font as compared to the default gray italics.

Presets can be switched quickly, allowing to change between different workflow setups. Moreover, the workflow user can manage presets (add, rename, duplicate, remove) using the context menu.

Note

Presets are not saved until you save the workflow. They are a part of the workflow’s configuration, so there is no specific function to save presets.

Conclusion

Finally there is workflow which provides a customized Run interface with main settings.

../_images/page_tutorials_workflow_configuration_21_custom_run.png

The next important improvement would be configuring a report that processes workflow results. The Results and Reports tutorial provides an example of such a report and continues using the workflow from this tutorial to generate test data.

Note that it is strongly recommended to complete the Results and Reports tutorial because it is the main introduction to Analyze.