ResInsight/README-experimental-workflow-ui.md

Using the experimental Workflow UI

The Workflow UI adds a Workflows node to the ResInsight project tree. It requires a Python environment containing rips, taskmaestro, and the workflow package.

These instructions assume ResInsight is already installed and working. Python 3.12 or newer and Git are required.

1. Create the Python environment

Choose a permanent location for the environment and workflow files:

mkdir -p ~/resinsight-workflows
python3 -m venv ~/resinsight-workflows/.venv
source ~/resinsight-workflows/.venv/bin/activate
python -m pip install --upgrade pip

Install rips from the Python directory supplied with ResInsight:

python -m pip install -e /path/to/ResInsight/Python

For a source checkout, use /path/to/ResInsight/GrpcInterface/Python instead.

Clone and install the example workflows. This also installs taskmaestro:

git clone https://github.com/OPM/taskmaestro-resinsight.git \
    ~/resinsight-workflows/taskmaestro-resinsight
python -m pip install -e ~/resinsight-workflows/taskmaestro-resinsight

The Workflow UI requires taskmaestro 0.4.x (0.4.0 or newer, below 0.5) and taskmaestro-resinsight 0.3.0 or newer. Check the installed versions:

python -m pip show taskmaestro taskmaestro-resinsight | grep -E "^(Name|Version)"

If taskmaestro is older, upgrade it from Git:

python -m pip install --upgrade "git+https://github.com/OPM/taskmaestro.git@main"

2. Register the workflows

Workflows that installed packages register, such as resinsight.completions, appear automatically in the Installed folder under Workflows. They are read-only, but they can be run and duplicated.

ResInsight also discovers workflow folders in ~/.taskmaestro/workflows. To use the example folders from taskmaestro-resinsight directly, link them in:

mkdir -p ~/.taskmaestro/workflows
for workflow in ~/resinsight-workflows/taskmaestro-resinsight/workflows/*/; do
    ln -sfn "$(realpath "$workflow")" \
        ~/.taskmaestro/workflows/"$(basename "$workflow")"
done

Workflows you create in ResInsight are saved to this folder by default.

3. Configure ResInsight

Open Edit → Preferences and set:

1. Scripting → Python Executable Location to the absolute path printed by:

   realpath ~/resinsight-workflows/.venv/bin/python
   

2. Scripting → Enable Python Script Server to on.

3. System → Experimental Features → Workflows to on.

Restart ResInsight. The Workflows node should now appear in the project tree. Select a workflow job, provide its inputs, and click Run.

4. Create and edit workflows

Selecting a workflow opens the workflow editor in a tab next to the 3D views. It shows the workflow graph, a palette of all installed tasks on the right, and a status line with validation results. Right-click the graph background for Undo, Redo, Save, Save As, and Duplicate as Editable.

• New workflow: right-click Workflows and choose New Workflow.
• Copy a workflow: choose Duplicate as Editable on any workflow, including installed ones.
• Add a task: drag it from the palette onto the graph, double-click it in the palette, or right-click the graph and use Add Task. Tasks that need a ResInsight connection are connected to a connect task automatically.
• Connect tasks: drag from an output port (right side of a task) to an input port (left side). While dragging, valid targets are green; invalid ones are grey and show the reason as a tooltip.
• Config inputs: every required input that is not connected becomes a config input, shown in the property view when the task is selected. Optional inputs can be turned on under Optional Inputs in the task's context menu.
• Collect outputs: an input that takes a list or a dict (ring around the port) accepts several connections. Each connection is labelled with its position or key. Right-click a connection to Rename Key or Move Earlier/Later.
• Map over items: right-click a task and choose Map Over to run it once per item of a mapping. Choose the inputs that receive the key and the value of each item. The items are entered in the property view, either as JSON or by selecting cases, well paths or views. Remove Map undoes it.
• Rename, Set as Result Task, Delete: right-click a task or connection. F2 renames and Del deletes the selection. Ctrl+Z and Ctrl+Y undo and redo.

The workflow is validated with taskmaestro shortly after each edit. Problems are shown as badges on the tasks and in the status line. A workflow that fails validation can still be run after confirming.

Running a workflow with unsaved edits runs the edited version from a temporary folder. The files on disk are not changed until you save.

Saving

Save (Ctrl+S) writes workflow.yaml and input.yaml to the workflow folder. Save As saves to a new folder. Note that:

• The first save keeps the original as workflow.yaml.bak.
• The YAML is rewritten. The comment block at the top of workflow.yaml is kept; other comments are lost.
• input.yaml gets the values of the workflow's first job (Default). Selected cases, well paths, and views are not saved.
• Folders outside ~/.taskmaestro/workflows are not found when ResInsight starts or rescans.

Use Rescan Workflows on the Workflows node after changing workflow folders or installing packages. ResInsight asks before closing or rescanning when there are unsaved edits.

Workflows that use nested workflows open read-only, and the status line explains why. They can still be run.

Troubleshooting

• No Workflows node: Enable the experimental feature and restart ResInsight.
• The Workflows node is empty: Check that each directory under ~/.taskmaestro/workflows contains workflow.yaml, then use Rescan Workflows.
• The task palette is empty or the Installed folder is missing: The task catalog failed to load. Hover over Task catalog not available in the palette to see why. Check that taskmaestro and the task packages are installed in the configured Python environment.
• A Python module cannot be found: Confirm that Python Executable Location points to the virtual environment created above.
• Workflows fail to load with a message about the taskmaestro version: Upgrade taskmaestro as described above.
• The workflow cannot connect: Enable Python Script Server and restart ResInsight.