Getting Started

Kotar Overview

Kotar is a browser-based engineering environment for working with SysML v2 and KerML models. It combines textual and graphical model authoring with IDE-style capabilities such as diagnostics, navigation, command-line tools, data handling, and model analysis.

This guide introduces the basic workflow for using Kotar.

For a complete description of available capabilities, see the [User Manual].

---

1. Open Kotar

Open the Kotar URL provided by your organization or administrator.

Depending on your deployment, authentication may be required before Kotar opens.

After startup, Kotar displays the main engineering workspace.

The interface follows the general layout of a modern development IDE. See the diagram below for a quick tour:

1. Workspace / File Explorer
2. Textual Model Editor
3. Graphical Model Editor
4. Helpful Tools
   • Problems panel
   • Output panel
   • Terminal
   • REPL
   • Version-control tools
   • Tables and data tools
   • Model repository tools
5. Model Browser

You can easily control the panels that are displayed with the quick layout buttons:

Figure 1: Kotar Overview Diagram

---

2. Create or Open a Workspace

A workspace is the primary working context in Kotar.

A workspace contains the files, models, scripts, data, and other engineering artifacts associated with a project or activity.

Depending on your environment, a workspace may be created from:

• a new project;
• an existing Git repository;
• a project retrieved from a remote SysML v2 service.

Figure 2: Kotar Workspace Diagram

A workspace might contain files such as:

project/
├── model/
│   ├── system.sysml
│   └── requirements.sysml
│
├── data/
│   └── requirements.csv
│
├── scripts/
│   └── transform.ts
│
└── analysis/
    └── analysis.py

The exact organization of the workspace is up to the project.

---

3. Editing/Viewing Your First Model

Use the File Explorer (see Figure 1) to locate a .sysml file. If you are starting a new model, create a new .sysml file in the workspace. Select the file to open it in the textual editor. Edit the SysML or paste the example below.

View your model in the Graphical Model Editor. Note: You can filter the graphical view by package.

Example SysML:

package Example {
 
    part def Vehicle;
 
    part vehicle : Vehicle;
 
}

Kotar analyzes SysML v2 model content as it is edited and provides language-aware functionality such as syntax and semantic analysis.

---

4. Edit the Model

Edit the SysML v2 text directly in the editor.

As you work, Kotar provides IDE-style assistance such as:

• syntax highlighting
• diagnostics
• code completion
• navigation
• model validation
• formatting
• linting and quick fixes

Example: quickly jump to the definition of a usage by right-click >> Go to Definition or using the keyboard shortcut (cmd F12).

---

5. Detecting and Resolving Model Problems

As you work, Kotar automatically detects problems in the model. Detected model problems are shown using familiar severity levels such as:

• Hint

• Warning

• Error

To see the problems in your model open the Problems panel by choosing the appropriate layout button (see figure 1) or by selecting the problem counter at the base of the page.

Problems may result from:

• syntax errors;
• semantic errors;
• validation rules;
• lint rules;
• other model-analysis checks. Selecting a problem navigates directly to the affected model element.

Example

The model is missing a ';' at the end of line 5. Selecting the problem in the Problems tab highlights the problem in the model.

---

6. Apply Quick Fixes

Some diagnostics and linting rules provide automatic corrections.

When a quick fix is available:

1. Hover over the affected model element or diagnostic to view the problem.
   • Alternatively, right-clicking on a problem in the Problems tab will offer quick fix options (if a quick fix is available).
2. Open the available quick-fix action.
3. Select the appropriate correction.

The example below shows the linter recognizing that usage names should be camel case.

Depending on the rule, Kotar may allow you to correct:

• one occurrence;
• all occurrences of that rule in the file;
• multiple automatically fixable lint problems.

---

7. Format the Model

Kotar includes formatting support for textual SysML v2. Formatting can normalize the textual representation of your model according to the formatting rules available in the workspace. Use formatting periodically to keep model files consistent and readable.

To format the model:

1. Right-click anywhere in the Textual Editor
2. Select Format Document

---

8. View the Model Graphically

Where supported, open the graphical model editor to inspect the model visually.

The textual and graphical editors operate on the same underlying semantic model, allowing users to work with whichever representation is most appropriate for the them and their current task. Changes made in one representation can are automatically reflected in the other.

Things to try:

1. Select different view type (Structure, Interconnection, etc...)
2. Filter the diagram to a given set of packages
3. Change the display style

Recommendation

Prefer named model elements when possible if a model will be edited interchangeably through graphical and textual representations.

Some operations involving unnamed elements or major textual restructuring may affect graphical identity or layout.

---

9. Save and Preserve Your Work

The browser version of Kotar stores workspace files in a browser-managed virtual filesystem. It also tracks and version controls the model through local git and a local Model Management System (OpenMBEE Flexo). This makes Kotar behave similarly to a desktop development environment, but browser storage should not be treated as the only durable backup of important engineering work. Projects that need to be preserved should also use an appropriate persistent mechanism. Kotar provides the following options but is not limited to:

• connecting a remote git repository;
• a remote SysML v2 Model Management System / Flexo service;

Important: Do not rely exclusively on browser-local storage for important project data.

Refer to the [User Manual] for steps to setup remote git and remote flexo.

---

10. Next Steps

Continue with the [User Manual] for detailed information about:

• textual SysML v2 modeling;
• graphical modeling;
• diagnostics and validation;
• linting and formatting;
• constraint and requirement analysis;
• interactive model evaluation;
• command-line tools;
• Git and version control;
• remote model repositories;
• tables and CSV data;
• data-to-model transformations;
• scripting and automation;
• additional engineering services.

---

Getting Help

If you encounter a problem:

1. Search existing GitHub Issues.
2. If necessary, submit a new issue using the appropriate issue form. When reporting problems, use minimal synthetic examples whenever possible.

Do not submit confidential, proprietary, customer-sensitive, export-controlled, classified, or credential information through public GitHub Issues.