Proposal: Parameterized Canvas — a second view of the same workflow

[yangzhang75]

Summary

A workflow gets two views of the same instance. The regular canvas is for building and
editing it. The parameterized canvas ("P canvas") is a simplified view for people who just
want to run it with different property values.

The author ticks a "parameterize" checkbox on the operator properties worth asking about.
Those become the inputs on the P canvas. Everything else stays hidden.

The two views share one workflow instance, so a change made on either is a change to the
workflow, and both stay in sync.

The problem this replaces

In the design proposed in #7368, filling in a macro's form generates a workflow. That leaves
the cardinality between a macro and the workflows it produces undecided, and neither option
holds up.

One-to-one (1:1). A macro maps to a single generated workflow, so filling in the form
again has to overwrite the previous result. Two users cannot hold different parameter values
against the same macro, and one user cannot keep two configurations side by side.

One-to-many (1:N). Every fill produces another workflow. The workflow tab accumulates
near-identical copies of one pipeline, the ownership and lifecycle of each copy are
undefined, and a later fix to the macro does not propagate to any workflow already generated.

There is also more than one place to run the same workflow. The macro page has its own Run,
and so does the workflow it generates. Two different objects execute the same thing, and it
is not clear which executions belong where.

The P canvas removes both questions rather than answering them. Nothing is generated, so
there is no second entity for a workflow to be related to. Run does appear in both views, but
it is the same run on the same workflow, so every execution belongs to that one workflow.

The design

flowchart LR
  C["Regular canvas<br/>build and edit"] --> W["one workflow instance"]
  P["P canvas<br/>run with parameters"] --> W
  W --> E["execution"]

Loading

A workflow offers a P canvas once its author turns that on from the workflow tab, which is
also where it is opened from.

Edit mode

Edit mode is where the author decides what the user has to fill in. It is available to
anyone with write access. The author sets the page up in edit mode, then turns it off to see
exactly what everyone else will see. Both are the same page, so there is nothing to preview
separately and nothing that can fall out of step.

In edit mode the workflow appears and the author can click a step to open its property
panel. A "parameterize" checkbox sits next to each of that operator's properties. Ticking
one turns that property into an input the user fills in; leaving it unticked keeps the
property out of sight, at whatever value the author set. The author can then:

• rename an input by clicking its title, so that a property the schema calls fileName can
  be presented as "Input file"
• hide sub-fields that are not worth asking about, since one property is often several boxes
• add a line of help text under an input, if it needs explaining
• add an instruction for the page, written in Markdown
• choose which operators' results are shown after a run
• reorder the inputs by dragging

The help text and the instruction are both optional. An input with a clear name usually
needs neither.

All of this is stored inside the workflow itself: one field in the workflow JSON holding the
ticked properties and their names, and one flag on the workflow saying it offers a P canvas.
Nothing is kept anywhere else, so the setup travels with the workflow and there is no second
record that can fall out of sync. Clear those two and the workflow is an ordinary workflow
again, which means the rest of the system never has to know this feature exists.

What everyone else sees

The instruction, the parameter inputs, a Run button, and the results.

The workflow itself is optional and hidden by default. It sits behind a collapsed strip that
anyone can expand if they want to see what actually runs, but nobody has to look at a graph
to use the page.

Cloning

Cloning or duplicating a workflow carries the parameterize checkboxes with it. Someone handed
a parameterized workflow can clone it, open the P canvas straight away, and fill in their own
values without ever seeing the graph.

Staying in sync

The workflow is the ground truth. Filling in a box on the P canvas performs the same property
edit the regular canvas performs, so a change on either view appears on both, and Run starts
the same execution either way.

[mengw15]

I like this direction. With two views over the same workflow instance, nothing gets generated, so the cardinality question disappears.

Two details that could use some discussion: the name "P canvas", and the flask icon marking workflows in the workflow list. These are just small UX details though — I have no problem with the direction itself.

[parshimers]

This is a very good and natural idea. Kind of like a parameterized query or view, or a job that accepts parameters in Jenkins, or a Workflow in GHA that is manually triggered with parameters.

[chenlica]

Per our offline discussions, I like this design in general.

Notice that if a user fills a value for a parameter, this value becomes part of the workflow. There is no another abstract "view" layer that can store this filled value. As a result, the change will become immediately visible to other users accessing this workflow.

In addition, if a user A runs this workflow with one value for the parameter, another user B cannot run this workflow with a different value, since both users share the same workflow. If user B wants to run the workflow with a different value, they have to clone the workflow. This behavior is due to the fact that the system only allows one execution for each workflow. So it's not caused by this "p canvas" design.

[yangzhang75]

Two small proposals for this view.

Name: "form View", plainer than "Parameterized Canvas". Canvas is where you build the workflow; Run View is where you fill in the inputs and run it.

Icon: Ant Design's solution glyph, a form being filled in, a stock icon not used elsewhere in the app.