Solution projects API#

SAF GLOW Engine supports and provides persistence for an arbitrary set of solution instances called projects. A project consists of the project data and project files.

The contents of the project data are determined by the data schema in the solution definition. Once you’ve created a project, you can use GLOW’s Client API and REST API to manipulate its contents.

Important

Do not modify or delete projects manually by directly editing or removing the project data or files, as this may invalidate the state of the project or its contents. Make sure that you perform all project operations either from the Client or Solution UI (where applicable).

Create a project#

You can create a project either using the client or via the REST interface.

Create a project using the Python client#

The following example creates a project with My Solution as display_name.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
my_project = client.create_project(display_name="My Solution")

You can also provide an optional description for the project:

my_project = client.create_project(display_name="My Solution", description="A detailed description of the project")

Create a project using the REST API#

Create a project using the HTTP POST request to the /projects endpoint.

You can use the Open API UI (see Solution REST API) to invoke this POST operation as follows:

Expand the POST request section of Create Project.
Click Try it out.

Under Request body, enter the project display_name and optionally a description.

{
  "display_name": "my project",
  "description": "A detailed description of the project"
}

Click Execute.

Under Response body, the information of the created project is shown:

{
    "display_name": "test project",
    "description": "A detailed description of the project",
    "name": "projects/6638ce7177e87f72ac4bbab3",
    "date_created": "2024-01-01T01:02:03.000004",
    "date_modified": "2024-01-01T01:02:03.000004",
}

When a project is created using the REST API, a project is created in GLOW’s data repository and a project folder for its files is created by default in glow_appdata_directory.

Note

The response contains the project name (for example, projects/6638ce7177e87f72ac4bbab3) generated by GLOW. The project_id is an alphanumeric string at the end of a project’s name value. In the example above, the project_id is 6638ce7177e87f72ac4bbab3. This is a unique identifier, required in other requests to handle the project.

Note

display_name is not a unique identifier. SAF GLOW Engine allows you to create and import multiple projects with the same display_name.

Get a project#

You can retrieve an existing project using the client or via the REST interface.

Get a project using the Python client#

The following example retrieves the project with id 6638ce7177e87f72ac4bbab3.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
my_project = client.get_project(name="projects/6638ce7177e87f72ac4bbab3")

Once you retrieve a project, you can access its metadata properties:

# Access project properties
print(my_project.project_id)  # Output: "6638ce7177e87f72ac4bbab3"
print(my_project.project_name)  # Output: "projects/6638ce7177e87f72ac4bbab3"
print(my_project.project_display_name)  # Output: "E-Motor"
print(my_project.project_description)  # Output: "Updated motor design and thermal analysis"
print(my_project.date_created)  # Output: "2023-01-01T01:02:03.000004"
print(my_project.date_modified)  # Output: "2024-02-02T01:02:03.000004"

Get a project using the REST API#

Get a project using the GET request. In the OpenAPI UI:

Expand the GET section of Get Project.
Click Try it out.
Under Parameters, enter the project_id of an existing project.

Click Execute.

Under Response body, the information of the project is shown:

{
  "display_name": "Electric Motor",
  "description": "A detailed description of the project",
  "name": "projects/6638ce7177e87f72ac4bbab3",
  "date_created": "2023-01-01T01:02:03.000004",
  "date_modified": "2023-01-01T01:02:03.000004",
}

Import a project package#

You can import a project package (.safx file) into SAF using either the REST API or the Python client provided by GLOW, as demonstrated below.

Note

Each product instance is separated from the instance of the original project, enabling both projects (original and imported) to operate independently without any interference.

Warning

Importing a project will trigger the upgrade supported modifications as well as the applicable project migrations if the solution definition contains any.

Import a project using the Python client#

You can import a project package using the Python client, as shown in the following example. This example imports an existing .safx file into a project with the targeted display_name.

from pathlib import Path

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
safx_source = Path("D:/SAF/my_project.safx")
display_name = "my_project"
# Import the exported .safx project into a new project with display_name my_project
new_project = client.import_project(safx_path=safx_source, display_name=display_name)

Import a project using the REST API#

You can import a project package using the following REST API endpoint:

POST http://localhost:5432/projects:import

A .safx project file (safx_file) and the display_name of the new project must be specified.

The following example imports a project using curl:

curl -X 'POST' \
    'http://localhost:5432/projects:import' \
    -H 'accept: application/json' \
    -H 'Content-Type: multipart/form-data' \
    -F 'safx_file=@transaction.safx' \
    -F 'display_name=my_project'

The response contains the information of the created project:

{
  "display_name": "my_project",
  "name": "projects/6638ce7177e87f72ac4bbab3",
  "date_created": "2023-01-01T01:02:03.000004",
  "date_modified": "2023-01-01T01:02:03.000004",
}

Note

SAF GLOW Engine generates a new project_name for the project, discarding the one from the imported project.

Note

When importing a project, the description attribute from the original project is inherited. The description parameter is not supported during import and cannot be customized. It can be modified after the project is imported using the modify project properties API.

List projects#

You can list the projects corresponding to a particular Solution using the client or via the REST interface.

List projects of a Solution using the Python client#

The following example lists all the projects for solution ExampleSolution.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
all_projects = []
page_size = 100
# List the projects page by page until all projects are retrieved
response = client.list_projects(page_size=page_size)
all_projects.extend(response["projects"])
# If there are more projects to retrieve, the total number of pages is indicated in the response.
# Loop through the pages until all projects are retrieved.
for i in range(2, response["total_pages"] + 1):
    response = client.list_projects(page_size=page_size, page=i)
    all_projects.extend(response["projects"])

print(all_projects)

You can also sort projects with the optional order_by parameter. Each field can be followed by asc or desc. If no direction is provided for a field, the default is ascending order. Supported fields are display_name, description, date_created, date_modified, and name.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
# Sort by latest modification date first
response = client.list_projects(order_by="date_modified desc")
print(response["projects"])

List all projects of a Solution using the REST API#

List existing projects using the GET request. In the OpenAPI UI:

Expand the GET section of List Projects.
Click Try it out.
Optionally set order_by (for example, date_modified desc, display_name).

Click Execute.

Under Response body, a list of existing projects is shown:

{
  "projects":
    [
      {
        "display_name": "Electric Motor",
        "description": "Motor design and analysis",
        "name": "projects/6638ce7177e87f72ac4bbab3",
        "date_created": "2023-01-01T01:02:03.000004",
        "date_modified": "2023-01-01T01:02:03.000004"
      },
      {
        "display_name": "EM Thermal",
        "description": "Thermal analysis of motor",
        "name": "projects/6638ce7177e87f72ac4bbab4",
        "date_created": "2023-01-01T01:02:03.000004",
        "date_modified": "2023-01-01T01:02:03.000004"
      }
    ],
  "current_page": 1,
  "total_pages": 20,
  "page_size": 100,
  "total_projects": 2000
}

You can also call the endpoint directly with query parameters:

curl -X 'GET' \
  'http://127.0.0.1:5432/projects?page=1&page_size=100&order_by=date_modified%20desc,%20display_name' \
  -H 'accept: application/json'

Filter projects#

You can optionally filter the listed projects by providing a filter expression. The filter syntax follows the format <field> <operator> <value> [AND <field> <operator> <value>]....

Supported fields:

display_name: Only supports the = operator, which performs a case-insensitive contains match.
description: Only supports the = operator, which performs a case-insensitive contains match.
date_created: Supports =, !=, <, >, <=, >=. Values must be ISO 8601 datetime strings.
date_modified: Supports =, !=, <, >, <=, >=. Values must be ISO 8601 datetime strings.

Combining conditions:

Multiple conditions can be combined using the AND (OR is not supported, nor parentheses for grouping).

Filter projects using the Python client

The following examples demonstrate how to filter projects using the Python client.

Filter by display name (case-insensitive contains match):

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
response = client.list_projects(filter="display_name = Motor")

Filter by description (case-insensitive contains match):

response = client.list_projects(filter="description = thermal")

Filter by creation date range:

response = client.list_projects(filter="date_created >= 2024-01-01T00:00:00 AND date_created <= 2024-12-31T23:59:59")

Combine name and date filters:

response = client.list_projects(filter='display_name = "Electric Motor" AND date_modified >= 2024-06-01T00:00:00')

Filter projects using the REST API

You can pass the filter parameter as a query string. For example:

GET http://localhost:5432/projects?filter=display_name+%3D+Motor

Using curl:

curl -X 'GET' \
  'http://localhost:5432/projects?filter=display_name+%3D+Motor' \
  -H 'accept: application/json'

Note

Values containing spaces must be quoted in the filter expression (for example, display_name = "Electric Motor").

Modify project properties#

You can modify a project’s properties (display name and description) using the client or via the REST interface.

Modify project properties using the Python client#

The following example changes a project’s display name and description.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
my_project = client.get_project(name="projects/6638ce7177e87f72ac4bbab3")
my_project.modify_project(display_name="E-Motor", description="Updated motor design and thermal analysis")
print(my_project.project_display_name)  # Output: "E-Motor"
print(my_project.project_description)  # Output: "Updated motor design and thermal analysis"

You can modify only the display name:

my_project.modify_project(display_name="E-Motor New")

Or only the description:

my_project.modify_project(description="New description")

To clear the description, set it to an empty string:

my_project.modify_project(description="")

Modify project properties using the REST API#

Modify a project’s properties using the PATCH request. It automatically updates the date_modified field. In the OpenAPI UI:

Expand the PATCH section of Modify Project.
Click Try it out.
Under Parameters, enter the project_id of an existing project.

Under Request body, enter the properties to modify.

To modify the display name:

{
  "display_name": "E-Motor"
}

To modify the description:

{
  "description": "Updated motor design and thermal analysis"
}

To modify both properties:

{
  "display_name": "E-Motor",
  "description": "Updated motor design and thermal analysis"
}

Click Execute.

Under Response body, the updated information of the project is shown:

{
  "display_name": "E-Motor",
  "description": "Updated motor design and thermal analysis",
  "name": "projects/6638ce7177e87f72ac4bbab3",
  "date_created": "2023-01-01T01:02:03.000004",
  "date_modified": "2024-02-02T01:02:03.000004",
}

Delete a project#

You can delete a project using the client or via the REST interface.

Delete a project using the Python client#

The following examples show how to delete the project with id 6638ce7177e87f72ac4bbab3 either using the corresponding client or project object method.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
client.delete_project(name="projects/6638ce7177e87f72ac4bbab3")

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
my_project = client.get_project(name="projects/6638ce7177e87f72ac4bbab3")
my_project.delete()

Delete a project using the REST API#

Delete a project using the DELETE request. In the OpenAPI UI:

Expand the DELETE section.
Click Try it out.
Under Parameters, enter the project_id of an existing project.
Click Execute.

Both the project data and project folder are deleted.

Upgrade a project after modifying the solution definition#

You can upgrade a project using the client or via the REST interface.

Upgrade a project using the Python client#

The following examples show how to upgrade the project with id 6638ce7177e87f72ac4bbab3.

from ansys.saf.glow.client import Client
from ansys.solutions.example.solution.definition import ExampleSolution

client = Client(ExampleSolution, "http://localhost:5432")
client.upgrade_project(name="projects/6638ce7177e87f72ac4bbab3")

Upgrade a project using the REST API#

After modifying the solution definition, you may need to upgrade the existing projects before you continue using them. This can be done using the POST request. In the OpenAPI UI:

Expand the POST section.
Click Try it out.
Under Parameters, enter the project_id of an existing project.
Click Execute.

Note

Modifying a solution definition might invalidate existing projects and prevent them from loading properly.
Upgrading a project may render the state property of the fields obsolete, depending on the modifications.

Supported modifications#

Project upgrade optional:

These modifications do not trigger an error if the project is used before being upgraded.

Note

You are recommended to upgrade the project, nonetheless.

Modifying the solution’s display_name field
Modifying the solution’s version field (Only to be modified when introducing breaking changes)
Adding/removing transactions
Modifying the default value of a step field (The project value will not change to the new default value)
Modifying the validator of a step field: only allowed if the current field value passes the new validator.
Modifying the signature of a transaction (function parameters and download/upload fields).

Note

These modification will be applied regardless of the value of the environment variable GLOW_ENABLE_AUTOMATIC_PROJECT_MIGRATION.

Warning

The solution’s version field should only be modified (increased) if any of the other modifications represents a breaking change. Increasing the solution’s version field requires adding a migration transformation to the solution definition as specified in the project migration documentation.

Project upgrade required:

These modifications do trigger an error if the project is used before being upgraded.

Adding/removing step fields
Adding/removing steps
Modifying the type of a step field (only allowed if the old and new types are casteable—for example, from int to float)

Note

Renaming a step or a step field is equivalent to removing the old one and adding a new one. Therefore, old values are not retained, and the new step or step field is initialized with its default values.

Warning

These modification will only be applied if the environment variable GLOW_ENABLE_AUTOMATIC_PROJECT_MIGRATION is set to True. Otherwise, and error will be raised. Never set GLOW_ENABLE_AUTOMATIC_PROJECT_MIGRATION to True in a production environment, the automatic project migration should be used only for development.

Breaking changes#

These modification represent a breaking change:

Modifying the validator of a step field when the new one invalidates the current field value.
Modifying the type of a step field: if the current field value cannot be cast to the new type (for example, from a non-numeric str to int).

When modifications include breaking changes, it is mandatory to include a migration transformation in the solution definition. Otherwise, the project cannot be upgraded and becomes inoperable. Read the documentation on the project migration API to know how to define a project migration.

Note

Migrations are applied regardless of the value of GLOW_ENABLE_AUTOMATIC_PROJECT_MIGRATION.

Warning

It is mandatory to increase the solution’s version field when introducing breaking changes.

Project files location#

By default, the project folder for storing the project files is created in %APPDATA%/ansys/glow/SOLUTION_NAME/project_files.

You can change the location of the project files directory by setting the GLOW_PROJECT_FILES_DIRECTORY environment variable. For example, the following code sample causes SAF GLOW Engine to store the project files in D:/my_project_files/ directory.

$env:GLOW_PROJECT_FILES_DIRECTORY="D:/my_project_files"

Warning

Do not move or modify project files manually. Doing so may lead to data loss or unexpected behavior.

Solution projects API#

Create a project#

Create a project using the Python client#

Create a project using the REST API#

Get a project#

Get a project using the Python client#

Get a project using the REST API#

Export/share a project#

Export a project using the Python client#

Export a project using the REST API#

Import a project package#

Import a project using the Python client#

Import a project using the REST API#

List projects#

List projects of a Solution using the Python client#

List all projects of a Solution using the REST API#

Filter projects#

Modify project properties#

Modify project properties using the Python client#

Modify project properties using the REST API#

Delete a project#

Delete a project using the Python client#

Delete a project using the REST API#

Upgrade a project after modifying the solution definition#

Upgrade a project using the Python client#

Upgrade a project using the REST API#

Supported modifications#

Breaking changes#

Project files location#