`ecflow`

The uw mode for realizing and validating ecFlow suite definitions.

uw ecflow --help

usage: uw ecflow [-h] [--version] ACTION ...

Handle ecflow suite definitions

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit

Positional arguments:
  ACTION
    realize
      Realize an ecFlow suite definition
    server
      Start an ecFlow server
    validate
      Validate an ecFlow YAML config

`realize`

In uw terminology, to realize a configuration file is to transform it from its raw form into its final, usable state. In the case of uw ecflow, that means transforming a structured UW YAML file into an ecFlow suite definition file (suite.def) and, optionally, a set of ecf scripts. The structured YAML language required by UW closely follows the concepts defined by ecFlow.

See ecFlow Workflows for more information about the structured UW YAML for ecFlow.

uw ecflow realize --help

usage: uw ecflow realize [-h] [--version] [--config-file PATH]
                         [--output-dir PATH] [--scripts-dir PATH] [--quiet]
                         [--verbose]

Realize an ecFlow suite definition

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --config-file PATH, -c PATH
      Path to UW YAML config file (default: read from stdin)
  --output-dir PATH
      Path to output directory for suite definition (default: write to stdout)
  --scripts-dir PATH
      Path to output directory for ecf scripts (default: no scripts are
      generated)
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

The examples in this section use a UW YAML file workflow.yaml with contents:

ecflow:
  suitedef:
    suite_workflow:
      family_data_prep:
        task_fetch:
          script:
            body: echo Fetching data...
            manual: This task fetches data.
        task_process:
          script:
            body: echo Processing data...
            manual: This task processes data.
          trigger: /workflow/data_prep/fetch == complete
      task_run_model:
        script:
          body: echo Running model...
          manual: This task runs the model.
        trigger: /workflow/data_prep == complete
      vars:
        WORKFLOW_VAR: production

To realize a UW YAML config file to stdout in ecFlow suite definition format:

uw ecflow realize --config-file workflow.yaml

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config
#5.18.0
suite workflow
  edit WORKFLOW_VAR 'production'
  family data_prep
    task fetch
    task process
      trigger /workflow/data_prep/fetch == complete
  endfamily
  task run_model
    trigger /workflow/data_prep == complete
endsuite
# enddef

Note that UW log messages are written to stderr so can be redirected separately from the suite-definition code.

To realize a UW YAML config file to the file suite.def in a specified directory:

rm -f suite.def
uw ecflow realize --config-file workflow.yaml --output-dir .
echo
cat suite.def

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config

#5.18.0
suite workflow
  edit WORKFLOW_VAR 'production'
  family data_prep
    task fetch
    task process
      trigger /workflow/data_prep/fetch == complete
  endfamily
  task run_model
    trigger /workflow/data_prep == complete
endsuite
# enddef

To read the UW YAML from stdin and write the suite definition to stdout:

cat workflow.yaml | uw ecflow realize

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config
#5.18.0
suite workflow
  edit WORKFLOW_VAR 'production'
  family data_prep
    task fetch
    task process
      trigger /workflow/data_prep/fetch == complete
  endfamily
  task run_model
    trigger /workflow/data_prep == complete
endsuite
# enddef

To also generate ecf scripts:
```
uw ecflow realize --config-file workflow.yaml --output-dir ./workflow_output --scripts-dir ./workflow_output
```
```
[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config
```
The --scripts-path option specifies the directory under which ecf scripts are written. Here, scripts are arranged in a directory hierarchy following ecFlow’s names for tasks, e.g. /workflow/data_prep/fetch for the task defined at UW YAML key path ecflow.suitedef.suite_workflow.family_data_prep.task_fetch. For the example above, the generated scripts are:
- workflow_output/workflow/data_prep/fetch.ecf:
```
#!/usr/bin/env bash

echo Fetching data...

%manual
This task fetches data.
%end
```
- workflow_output/workflow/data_prep/process.ecf:
```
#!/usr/bin/env bash

echo Processing data...

%manual
This task processes data.
%end
```
- workflow_output/workflow/run_model.ecf:
```
#!/usr/bin/env bash

echo Running model...

%manual
This task runs the model.
%end
```
Important

Task Naming Convention: Task keys must follow the pattern task_<name>. When ecf scripts are generated, the <name> portion becomes the script filename with a .ecf extension. See ecFlow Workflows for more information about the structured UW YAML for ecFlow.
Examples:
- task_fetch → fetch.ecf
- task_run_model → run_model.ecf
- task_process_output_files → process_output_files.ecf
Names for suites and families follow a corresponding naming convention.

`server`

uw ecflow server --help

usage: uw ecflow server [-h] [--version] [--config-file PATH] [--insecure]
                        [--port PORT] [--report] [--quiet] [--verbose]

Start an ecFlow server

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --config-file PATH, -c PATH
      Path to UW YAML config file (default: read from stdin)
  --insecure
      Start server without SSL security
  --port PORT
      TCP port for the ecFlow server (default: random from 1024-49151)
  --report
      Output server details (e.g. hostname, port) as JSON to stdout
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

To start a server on a random available port with SSL security:
```
uw ecflow server --config-file server.yaml
```

To start a server on a specific port:

uw ecflow server --config-file server.yaml --port 54321

To start a server using a named certificate triplet:
```
uw ecflow server --config-file server.yaml --port 8888
```
Where server.yaml contains:
```
ecflow:
  server:
    ECF_HOME: /path/to/run
    ECF_SSL: myhost.8888
```
ECF_SSL accepts true to enable SSL using the default certificate triplet (server.crt / server.key / dh2048.pem) in $HOME/.ecflowrc/ssl, or a <host>.<port> prefix string to select a named certificate triplet (<host>.<port>.crt / .key / .pem) from the same directory. The --port value must match the port in the prefix when using a named triplet. See ecFlow Workflows for full server YAML documentation.
To emit a JSON report of the server details to stdout:
```
uw ecflow server --config-file server.yaml --report
```
The --report switch prints the ecFlow connection variables, ready to be consumed by downstream tooling (e.g. merged into a UW YAML for uw ecflow realize):
```
{
  "ECF_HOME": "/path/to/run",
  "ECF_HOST": "server.hostname.com",
  "ECF_PORT": "8888",
  "ECF_SSL": "myhost.8888"
}
```
ECF_SSL is included only when SSL security is enabled (i.e. when --insecure is not given and ECF_SSL is not false in the config).

`validate`

uw ecflow validate --help

usage: uw ecflow validate [-h] [--version] [--config-file PATH] [--quiet]
                          [--verbose]

Validate an ecFlow YAML config

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --config-file PATH, -c PATH
      Path to UW YAML config file (default: read from stdin)
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

The examples in this section use the UW YAML file workflow.yaml shown above.

To validate a UW YAML config file:

uw ecflow validate --config-file workflow.yaml

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config

To validate a UW YAML config from stdin:

cat workflow.yaml | uw ecflow validate

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]     INFO Schema validation succeeded for ecFlow config

When the config is invalid:

In this example, the top-level ecflow: key is missing.

uw ecflow validate --config-file bad.yaml

[2025-01-02T03:04:05]     INFO Validating config against internal schema: ecflow
[2025-01-02T03:04:05]    ERROR 1 schema-validation error found in ecFlow config
[2025-01-02T03:04:05]    ERROR Error at top level:
[2025-01-02T03:04:05]    ERROR   'ecflow' is a required property
[2025-01-02T03:04:05]    ERROR YAML validation errors

Demonstration Workflow 

View or run a simple ecFlow demonstration workflow.

ecflow

realize

Examples

server

Examples

validate

Examples

Demonstration Workflow

`ecflow`

`realize`

`server`

`validate`

Demonstration Workflow 