Loading the suite

The next step is to load the suite definition to the ecflow_server, and thus inform the server about the suite structure and components. As part of loading the suite definition, the ecflow_server performs several validation steps, and only if the validation is successful will the suite definition be accepted.

There are several options to load the suite definition to the ecflow_server. If a suite definition file, such as test.def, was manually created then the CLI ecflow_client provides the --load command. If the suite definition was programmatically generated, e.g. by a Python script using the Python API, the same script can load the suite definition file.

Note

Choose only one of two methods below to avoid errors associated with loading suite definition twice.

Load the test.def using the command line interface ecflow_client:

cd $HOME/course
ecflow_client --load test.def

The suite definition will be validated and loaded into the ecflow_server. If the validation fails, the suite is not loaded.

As seen previously, the Python API can be used to generate the suite definition file. This file can be loaded into the server as described earlier using the the Python API, as done with the CLI ecflow_client. The following code snippet shows how to load the suite definition file test.def into the server using the Python API.

Listing 9 $HOME/course/client.py

#!/usr/bin/env python3

import pathlib
from ecflow import Client

if __name__ == '__main__':

    base = pathlib.Path.home() / "course"

    try:
        ci = Client()

        print("[1] Load suite definition in 'test.def' into the server")
        ci.load(str(base / "test.def"))
        # line above reads suite definition from disk and loads into the server

    except RuntimeError as e:
        print("Failed:", e)

When the script is executed, the suite definition will be validated and loaded into the ecflow_server. If the validation fails, the suite is not loaded.

Notice that, when using the Python API, the suite definition is generated in memory and can be directly loaded into the server. However it is highly recommended to effectively save the suite definition to a file before loading it into the server, and thus separate the following steps:

the generation of the suite definition,
loading the suite definition into the server.

Listing 10 Example of how to load the in-memory definition into the server

defs = ... # create the suite definition in memory

try:
   ci = Client()
   print("[1] Load the in memory definition(defs) into the server")
   ci.load(defs)           # load the in memory python definition(def) into server

except RuntimeError as e:
   print("Failed:",e)

What to do

Load the suite definition file using the CLI ecflow_client
(Optional) Create the $HOME/course/client.py script and suite definition file.
Inspect the ecflow_server log file, and check that the suite definition was successfully loaded.

Warning

The same suite definition cannot be loaded multiple times. If a suite test already exists on the server, it can be deleted before loading the suite definition again, using the --delete command:

ecflow_client --delete /test

# find more about the --delete command with: ecflow_client --help delete

Alternatively, the --replace command can be used to re-load part or all of the suite, as as follows:

ecflow_client --replace /test test.def        # replace the suite test
ecflow_client --replace /test/t1 test.def     # replace just task t1

# find more about the --replace command with: ecflow_client --help replace