### Start PostgreSQL Instance with Docker

Source: https://doc.mbse-syson.org/syson/v2025.10.0/installation-guide/how-tos/install/ecosystem_only

Starts a PostgreSQL database instance using Docker. It maps the host port 5433 to the container port 5432 and sets environment variables for the database user, password, and name. This is the recommended method for local development and testing.

```bash
docker run -p 5433:5432 --name syson-postgres \
                            -e POSTGRES_USER=dbuser \
                            -e POSTGRES_PASSWORD=dbpwd \
                            -e POSTGRES_DB=syson-db \
                            -d postgres
```

```bash
docker run -p 5433:5432 --name syson-postgres -e POSTGRES_USER=dbuser -e POSTGRES_PASSWORD=dbpwd -e POSTGRES_DB=syson-db -d postgres
```

--------------------------------

### Start SysON Application with Production Configuration

Source: https://doc.mbse-syson.org/syson/v2025.10.0/installation-guide/how-tos/install/production_deploy

Command to run the SysON JAR file with database connection details and SSL configuration for a production environment. This command assumes a PostgreSQL database and requires the path to the SysON JAR, database credentials, and keystore information.

```bash
java -jar path/to/your/syson-application-YEAR.MONTH.0.jar \
  --spring.datasource.url=jdbc:postgresql://databaseHost:5433/databaseName \
  --spring.datasource.username=databaseUsername \
  --spring.datasource.password=databasePassword \
    \
  --server.ssl.key-store=path/to/your/keystore.p12 \
  --server.ssl.key-store-password=keyStorePassword \
  --server.ssl.key-store-type=PKCS12 \
  --server.ssl.key-alias=server \
  --server.ssl.key-password=privateKeyPassword \
    \
  --server.port=443
```

--------------------------------

### Start SysON Application with PostgreSQL

Source: https://doc.mbse-syson.org/syson/v2025.10.0/installation-guide/how-tos/install/ecosystem_only

Launches the SysON application by executing its JAR file. It configures the application to connect to a PostgreSQL database running on localhost:5433 with specified credentials. Ensure the PostgreSQL instance is running before executing this command.

```bash
java -jar path\to\your\syson-application-YEAR.MONTH.0.jar \
          --spring.datasource.url=jdbc:postgresql://localhost:5433/syson-db \
          --spring.datasource.username=dbuser \
          --spring.datasource.password=dbpwd
```

--------------------------------

### API Setup and Configuration

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/api/api-cookbook

Instructions and Python code for setting up your environment to interact with the SysML v2 API, including installing necessary libraries and configuring API access.

```APIDOC
## Setup Instructions

This section guides you through the necessary steps to prepare your environment for interacting with the SysML v2 API using Python.

### 1. Install Required Python Libraries

Ensure you have the following Python libraries installed. These are essential for making HTTP requests and handling data:

*   `requests`: For making HTTP requests to the SysML v2 API.
*   `pandas`: For organizing and manipulating data.

To install these libraries, run the following command in your terminal:

```bash
pip install requests pandas
```

### 2. Configure SysML v2 API Access

To connect to the SysON API, you need to configure the base URL of your API server. The `init_sysmlv2_api` function in the `init_api.py` script handles this. By default, it uses `http://localhost:8080/api/rest`. 

**Important:** Replace `http://localhost:8080` with the actual URL of your API server if it is hosted elsewhere.

**`init_api.py`**

```python
import argparse

def init_sysmlv2_api():
    host =  "http://localhost:8080/api/rest" # Replace with your actual API host URL
    return host

def parse_arguments():
    # Parse command-line arguments
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "project_id",
        type=str,
        help="The project ID.",
    )
    parser.add_argument(
        "element_id",
        type=str,
        nargs="?",  # This makes element_id optional
        help="The element ID (optional).",
    )
    return parser.parse_args()
```

**Explanation:**

*   **`init_sysmlv2_api()`**: Defines the base host URL for the SysML v2 API server. Remember to update this to your specific API endpoint.
*   **`parse_arguments()`**: Sets up argument parsing for command-line usage, expecting a `project_id` and an optional `element_id`.

### 3. Test Code Snippets

After configuring the API access, you can proceed to test the provided code snippets (recipes) in the subsequent sections.
```

--------------------------------

### Implicit Specialization Name Export Example (Before and After)

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Compares the textual export of objects referenced by an implicit Specialization before and after improvements. The 'Before' example shows a qualified name, while the 'After' example uses a simpler, direct name for the 'start' ActionUsage.

```SysON SysML
action def ActionDef1 {
    action a2;
    first Actions::Action::start then a2;
}
```

```SysON SysML
action def ActionDef1 {
    action a2;
    first start then a2;
}
```

--------------------------------

### SysON Transition Usage Label Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Provides an example of how TransitionUsage labels are displayed in the General View diagram, including the 'accepter' information. This clarifies the conditions or events that trigger a state transition.

```SysON
item def TurnOn;
state def OnOff2 {
    private import SI.*;
    private import ScalarValues.*;
    port commPort;
    attribute x : Real;
    state off;
    state on;
    state idle;
    transition off_on
        first off
        accept TurnOn via commPort
        then on;
    transition on_off
        first on
        accept after 5 [min]
        then off;
    transition on_idle
        first on
        if x > 0.0
        then idle;
}
```

--------------------------------

### Import TransitionUsage with Implicit Source Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Shows the textual import of TransitionUsage with implicit source handling. The example demonstrates how the source of outgoing TransitionUsages from a DecisionNode is now correctly resolved.

```SysON SysML
action a0 {
    private import ScalarValues::*;
    action a1;
    action a2;
    action a3;
    action a4;

    attribute attr1 : Real;
    first a0 then d1;
    decide d1;
        if x >= 2 then a1; // Source is d1
        if x >= 1 and x < 2 then a3; // Source is d1
        else a4; // Source is d1
}
```

--------------------------------

### SysML v2 Textual Import Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Demonstrates the textual import of a SysML v2 action definition with implicit source property for SuccessionAsUsage. This example shows how to define an action with sequential steps and implicit source handling, which is now supported for creating valid semantic models.

```SysML v2
action def ActionDef1 {
    action a2;
    action a3;
    first start;
    then a2;
    then a3;
}

```

--------------------------------

### Configure SysON JAR for HTTPS (Manual Install)

Source: https://doc.mbse-syson.org/syson/v2025.10.0/installation-guide/how-tos/https

Specifies the command-line arguments required to launch the SysON JAR file with SSL enabled. This is used when SysON is installed manually, requiring the keystore to be placed alongside the application JAR.

```bash
--server.ssl.key-store=./keystore.jks \
--server.ssl.key-store-password=PASSWORD_USED_IN_STEP_1 \
--server.ssl.key-store-type=JKS \
--server.ssl.key-alias=myalias \
--server.ssl.key-password=PASSWORD_USED_IN_STEP_1
```

--------------------------------

### Export TransitionUsage Textual Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Demonstrates the textual export of TransitionUsage owned by ActionUsage and ActionDefinition. This includes handling conditional transitions using 'if' and 'succession' keywords.

```SysON SysML
action def A1 {
    private import ScalarValues::Integer;
    attribute x : Integer;
    action a1;
    action a2;
    first a1 if x == 1 then a2;
    succession s1 first a1 if x > 1 & x < 2 then a2;
    succession s2 first a1 if x > 2 & x < 3 then a2;
}
```

--------------------------------

### SysON Requirement Syntax Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

This snippet demonstrates the syntax for defining requirements with attributes and constraints in SysON. It shows how to link an attribute to a physical quantity and set a constraint on it.

```SysON
requirement weight{
    attribute actualWeight :> ISQ::mass;
    require constraint {actualWeight <= 0.25 [lb]}
}
```

--------------------------------

### Export SuccessionAsUsage Textual Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Illustrates the textual export of SuccessionAsUsage, highlighting how the _name_ is properly handled. This ensures accurate representation of named SuccessionAsUsage when exporting models.

```SysON SysML
action def ActionDef1 {
    action a1;
    action a2;
    succession s1 first a1 then a2;
}
```

--------------------------------

### Import TransitionUsage with Guards Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Illustrates the textual import of TransitionUsage, specifically handling guards with OperatorExpressions. This allows for more complex conditional transitions in the model.

```SysON SysML
action a0 {
    attribute attr1 : Real;
    succession S first start if x < 0.0 then done;
}
```

--------------------------------

### SysON ViewUsage Textual Export Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Demonstrates the textual representation for exporting a ViewUsage in SysON. This includes specifying the view name and the elements to be exposed, along with the rendering type for the diagram.

```SysON
view rearAxleAssemblyDiagram {
    expose rearAxleAssembly;
    expose rearAxleAssembly::rearAxle;
    expose rearAxleAssembly::differential;
    render asTreeDiagram;
}
```

--------------------------------

### Import SuccessionAsUsage Textual Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Demonstrates the textual import of SuccessionAsUsage, showcasing how a new target action is defined directly after the 'then' keyword. This improves the creation of semantic models from SysML files.

```SysON SysML
action def ActionDef1 {
    first start;
    then action a1;
    then action a2;
}
```

--------------------------------

### Export DecisionNode Textual Example

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

Shows the textual export of DecisionNode. This example includes different conditions with 'if' and 'else' clauses, demonstrating how branching logic is represented.

```SysON SysML
action def A1 {
    action a1;
    action a2;
    action a3;
    attribute x : ScalarValues::Real;
    decide decision1;
    if x >= 2.1 then a1;
    if x >= 1.1 and x < 2.1 then a2;
    else a3;
}
```

--------------------------------

### Get Projects

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/api/api-cookbook

This recipe demonstrates how to retrieve a list of all available projects from the SysON API using a Python script. It sends a GET request to the projects endpoint and processes the response to display project names and IDs.

```APIDOC
## Get Projects Recipe

This recipe shows how to fetch and display all projects available on the SysON server using Python.

### Description

This script utilizes the `requests` library to send a `GET` request to the SysON API's projects endpoint. The response, typically in JSON format, is parsed to extract the name and ID of each project, which are then printed to the console.

### Method

`GET`

### Endpoint

`/api/projects` (This is a common convention; the exact endpoint may vary and should be confirmed with your API documentation or by inspecting the `host` variable from `init_sysmlv2_api`)

### Parameters

This endpoint typically does not require path or query parameters for fetching all projects.

### Request Example

```python
import requests

# Assuming init_sysmlv2_api() is defined as in the setup section
api_host = init_sysmlv2_api()
projects_endpoint = f"{api_host}/projects"

response = requests.get(projects_endpoint)

if response.status_code == 200:
    projects = response.json()
    print("Available Projects:")
    for project in projects:
        print(f"- Name: {project['name']}, ID: {project['id']}")
else:
    print(f"Error fetching projects: {response.status_code}")
    print(response.text)
```

### Response

#### Success Response (200)

A JSON array where each object represents a project and contains at least `name` and `id` fields.

- **`name`** (string) - The name of the project.
- **`id`** (string) - The unique identifier for the project.

#### Response Example

```json
[
  {
    "id": "project-123",
    "name": "Example Project Alpha",
    "description": "This is the first example project."
  },
  {
    "id": "project-456",
    "name": "Beta Test Initiative",
    "description": "A project for beta testing new features."
  }
]
```
```

--------------------------------

### SysON Model Definition for Flow Usage

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/release-notes/release-notes

This code snippet demonstrates a SysON model definition including part and port definitions, showcasing the declaration and usage of flows between elements. It highlights how to define parts, ports, and their associated items, as well as how to establish flow connections.

```SysON
part def P1Def {
    port po1 : PortDef1;
}
port def PortDef1 {
    out item item1 : P2Def;
}
part def P2Def;
part def P3Def {
    in item item2 : P3Def;
}
part p1 {
    part p2 : P1Def;
    part p3 : P3Def;
    flow from p2.po1.item1 to p3.item2;
    flow f1 from p2.po1.item1 to p3.item2;
}
```

--------------------------------

### Command-line Interface for SysML v2 Import Script

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/api/api-cookbook

This section details how to execute the Python script from the command line. It outlines the required arguments, including the API URL, the path to the SysML v2 file, the project ID, and the namespace element ID. Examples are provided for running the script with default and specific values.

```bash
python new_objects_from_text.py url-of-syson-server file-path-of-sysmlv2-file your-project-id your-namespace-elementId
```

```bash
python new_objects_from_text.py http://localhost:8080 /Users/myUserFolder/myFolder/mySysMLv2File.sysml 76bb3f29-17d1-465a-a2ca-a331978c36f3 2c0ddeb4-b9fe-478e-951e-0ca312013a5b
```

--------------------------------

### GET /api/rest/projects/{projectId}/branches

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/_attachments/sirius-web-openapi

Retrieves a list of all branches associated with a specific project. This endpoint allows you to view the branching history of your project.

```APIDOC
## GET /api/rest/projects/{projectId}/branches

### Description
Retrieves a list of all branches associated with a specific project. This endpoint allows you to view the branching history of your project.

### Method
GET

### Endpoint
/api/rest/projects/{projectId}/branches

#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **branches** (array) - An array of Branch objects, where each object represents a branch.
  - **Branch Object**: 
    - **id** (string) - The unique identifier of the branch.
    - **name** (string) - The name of the branch.
    - **commitId** (string) - The identifier of the commit associated with the branch.

#### Response Example
```json
[
  {
    "id": "branch-123",
    "name": "main",
    "commitId": "commit-abc"
  },
  {
    "id": "branch-456",
    "name": "develop",
    "commitId": "commit-def"
  }
]
```
```

--------------------------------

### Get Commit Change by ID

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/_attachments/sirius-web-openapi

Retrieves a specific change within a commit of a project. The change ID refers to the DataVersion that was modified in the commit.

```APIDOC
## GET /api/rest/projects/{projectId}/commits/{commitId}/changes/{changeId}

### Description
Get the change with the given id (changeId) in the given commit of the given project. The changeId is the id of the DataVersion that changed in the commit.

### Method
GET

### Endpoint
/api/rest/projects/{projectId}/commits/{commitId}/changes/{changeId}

#### Path Parameters
- **projectId** (string) - Required - The ID of the project.
- **commitId** (string) - Required - The UUID of the commit.
- **changeId** (string) - Required - The UUID of the change (DataVersion).

#### Response
##### Success Response (200)
- **DataVersion** (*object*) - The DataVersion representing the change.

##### Response Example
{
  "example": "{\"@id\": \"some-uuid\", \"@type\": \"DataVersion\", ...}"
}
```

--------------------------------

### Define Action Flow Elements with SysML

Source: https://doc.mbse-syson.org/syson/v2025.10.0/user-manual/hands-on/tutorials/flashlight

Defines the structure and interfaces for actions within an action flow. This code snippet specifies input and output items for actions like 'connectDCPwr', 'generateLight', and 'directLight', along with their nested action definitions.

```sysml
in item onOffCmd;
out item lightOut;
action connectDCPwr {
  	in item onOffCmd;
  	in item dcPwrIn;
  	out item dcPwrOut;
}
action generateLight{
  	in item dcPwrIn;
  	out item light;
}
action directLight{
  	in item lightIn;
  	out item lightOut;
}
```

--------------------------------

### GET /projects/{projectId}/commits

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/api/api-cookbook

Fetches the commits associated with a specific project. SysON returns a single branch with a single commit.

```APIDOC
## GET /projects/{projectId}/commits

### Description
Fetches the commit(s) associated with a specific project. SysON typically returns a single branch with a single commit.

### Method
GET

### Endpoint
/projects/{projectId}/commits

#### Path Parameters
- **projectId** (string) - Required - The ID of the project for which to fetch commits.

### Response
#### Success Response (200)
- **@id** (string) - The ID of the commit.

#### Response Example
```json
[
  {
    "@id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
]
```

#### Error Response (e.g., 404)
- **message** (string) - Description of the error.
- **code** (integer) - Error code.
```

--------------------------------

### Project Management API

Source: https://doc.mbse-syson.org/syson/v2025.10.0/developer-guide/_attachments/sirius-web-openapi

Endpoints for retrieving, creating, updating, and deleting projects.

```APIDOC
## GET /api/rest/projects/{projectId}

### Description
Retrieves the project details for a given project ID.

### Method
GET

### Endpoint
/api/rest/projects/{projectId}

#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **Project** (object) - Details of the project.

#### Response Example
{
  "example": "Project Object"
}

## PUT /api/rest/projects/{projectId}

### Description
Updates an existing project identified by its project ID. You can modify the project's name, description, or branch.

### Method
PUT

### Endpoint
/api/rest/projects/{projectId}

#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project to update.

#### Query Parameters
- **name** (string) - Optional - The new name for the project.
- **description** (string) - Optional - The new description for the project.
- **branch** (object) - Optional - The new branch information for the project.

### Response
#### Success Response (200)
- **Project** (object) - The updated project details.

#### Response Example
{
  "example": "Updated Project Object"
}

## DELETE /api/rest/projects/{projectId}

### Description
Deletes a project identified by its project ID.

### Method
DELETE

### Endpoint
/api/rest/projects/{projectId}

#### Path Parameters
- **projectId** (string) - Required - The unique identifier of the project to delete.

### Response
#### Success Response (204)
No content returned upon successful deletion.

#### Success Response (200)
- **Project** (object) - Details of the deleted project (may vary).

#### Response Example
{
  "example": "Project Object (for 200 response)"
}

## GET /api/rest/projects

### Description
Retrieves a list of all projects. Supports pagination.

### Method
GET

### Endpoint
/api/rest/projects

#### Query Parameters
- **page[size]** (integer) - Optional - The number of projects to return per page.
- **page[after]** (string) - Optional - Cursor for fetching projects after a specific point.
- **page[before]** (string) - Optional - Cursor for fetching projects before a specific point.

### Response
#### Success Response (200)
- **Array of Projects** (array) - A list of project objects.

#### Response Example
{
  "example": "[Project Object 1, Project Object 2, ...]"
}

## POST /api/rest/projects

### Description
Creates a new project with a specified name and an optional description.

### Method
POST

### Endpoint
/api/rest/projects

#### Query Parameters
- **name** (string) - Required - The name of the new project.
- **description** (string) - Optional - A description for the new project.

### Response
#### Success Response (201)
- **Project** (object) - The newly created project details.

#### Response Example
{
  "example": "New Project Object"
}
```