Add steps#

Steps are the building blocks of a solution workflow. Each step represents a distinct phase in the solution’s process flow, typically with its own UI and functionality. You can add steps to extend functionality without modifying the solution structure.

When to add a step

  • Your solution workflow needs additional logical phases

  • You want to break a complex process into smaller parts

  • You’re extending an existing solution with new capabilities

Add a step#

You can add a step to your solution using either SAF CLI or Solutions Manager.

Add a step to the solution using SAF CLI:

  1. Run the following command:

    saf add-step <solution-name>

  2. When prompted, provide the following values, pressing Enter to select the default value or to validate non-default values provided.

    1. Enter the name for the step.

      Make sure it follows the rules described in Step naming conventions.

    2. Select a UI framework.

      Warning

      You must use the same UI framework for all steps in a solution. If you try to add a step with a different UI framework than the one used to create the solution, the command returns an error.

      You can add steps without a UI framework by selecting none for any solution, regardless of its UI framework.

    3. Select a step template (optional).

The new step is created and integrated into your solution. Files are created and modified as described in saf add-step output.

Add a step to the solution using Solutions Manager:

  1. Open Visual Studio Code.

  2. In the Activity Bar, click the Solutions Manager icon.

  3. In the Solutions Manager pane, expand the Customize Solution view.

    Solutions Manager Customize Solution view

  4. Under Add step, provide the following values:

    1. Select the solution where you want to add a step.

      You can either select an option from the list of available solutions or browse for the solution folder of a different one.

    2. Enter the name for the step.

      Make sure it follows the rules described in Step naming conventions.

    3. Select the UI framework.

      Warning

      You must use the same UI framework for all steps in a solution. If you try to add a step with a different UI framework than the one used to create the solution, the command returns an error.

      You can add steps without a UI framework by selecting none for any solution, regardless of its UI framework.

    4. Enter the namespace to use for the solution.

    5. Enter the target directory where the solution will be saved.

  5. Create the step.

    Click the Add step button. Alternatively, you can copy the command under Add step command and run it in the terminal.

When you open the solution, the new step will be visible in the left navigation panel.

See also

For more information on available command-line options, see saf add-step options.

Step naming conventions#

Make sure your step name follows these conventions:

  • A step name cannot be a path.

  • A step name cannot contain:

    • Forward-slash (/) or backward-slash (\) characters

    • Invalid characters: colons (:), semi-colons (;), asterisks (*), question marks (?), or angle quotations (<, >)

The saf add-step command#

The saf add-step command is used to add a new step to an existing solution. It integrates the step into the solution’s structure, creating necessary files and updating existing ones as described in the previous section.

saf add-step options#

The saf add-step command has multiple options. To see them all, run the following command:

saf add-step --help

The following saf add-step options are available:

Option

Description

--step-name

The name of the step to add to the solution.

--ui-framework [dash|none]

Type of solution UI.

--template <template-name>

The name of the step template to use.

For more information, see Use step templates.

Note

Setting these options disables their command prompt.

saf add-step output#

Adding a step generates new files and modifies existing files in the solution.

Generated files#

The following files are generated:

<solution-name>/
├───src
│   └───ansys
│       └───solutions
│           └───<solution_module>
│               ├───solution
│               │   │   my_minimal_step.py # (new)
│               └───ui
│                   └───pages
│                           my_minimal_page.py # (new)

Modified files#

The following files are modified accordingly:

<solution-name>/
├───src
│   └───ansys
│       └───solutions
│           └───<solution_module>
│               ├───solution
│               │   │   definition.py # (edited)
│               └───ui
│                   └───pages
│                           page.py # (edited)
  • definition.py
  • page.py
# Added a new import and new step to the class.
from ansys.solutions.<solution_module>.solution.my_minimal_step import MyMinimalStep

class Steps(StepsModel):

    my_minimal_step: MyMinimalStep

# Added a new step to the array.
page_list = [
    {
        "id": "my_minimal_page",
        "text": "My Minimal Step",
        "prefixIcon": "carbon:ibm-engineering-workflow-mgmt",
        "expanded": True,
    },
]

# This block is inserted under the function display_page(pathname, value):
elif value["index"] == "my_minimal_page":
    return my_minimal_page.layout(project.steps.my_minimal_step)

Use step templates#

SAF ships a collection of built-in step templates that generate ready-to-use solution steps. Instead of writing boilerplate code from scratch, you can scaffold common patterns (calculator, HPS job submission, product instance management) and then customize them to fit your use case.

Prerequisites#

Before using step templates, ensure you’ve met the following prerequisites:

Prerequisite

Description

SAF Templates

Version 4.0.1 or later.

Using previous versions of the ansys-saf-templates package might produce unexpected results or errors when attempting to add a step.

SAF CLI

Version 4.0.1 or later.

Shared Technology Components (STC)

Some templates require a deployment of Ansys HPC Platform Services (HPS).

Ansys products

Depending on the template you intend to use, the corresponding Ansys product must be installed and licensed on your machine (for example, AEDT, Mechanical, MAPDL, Fluent, Geometry).

Attention

Step templates are available in SAF CLI version 4.0.1 or later. If you are using an earlier version, you can still add a step to a solution, but you will need to implement the step logic and UI from scratch.

To manually install a newer version of the SAF Templates package, run the following command in the Python environment where SAF CLI is installed:

pip install ansys-saf-templates

Add a step from a template#

Add a new step from a template by running the saf add-step command with the --template option:

saf add-step <my_solution> --template <template_name>

If --template is omitted, the CLI interactively guides you through selecting a template and the rest of the required parameters. You can also pass all information as command-line arguments:

saf add-step <my_solution> --step-name <step_name> --ui-framework <ui_framework> --template <template_name>

List available templates#

You can list the available templates by running:

saf templates

This shows all the templates available in ansys-saf-templates, as well as any additional templates from installed plugins. For information on available templates, see Step template gallery.