Exchanging SysML v2 Models

Overview

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 projects exchange models with other SysML v2 tools as files. The Import and Export page (Model → Import and Export) does both:

• Import reads .sysml files, a .zip of .sysml files, or a SysML v2 JSON file. It shows a preview of what changes, then applies it to this project as one undo step, or creates a new SysML v2 project.
• Export writes the whole model or one package as SysML v2 text (.sysml) or as SysML v2 JSON (.json).

You can also create a project straight from files: on Manage Projects, click Project Files ▾ → Import SysML v2 Files….

Concepts

File formats

KerML files (.kerml) are not imported yet.

Ids and matching

Every element in a SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 project has an id. The two formats keep it differently:

• JSON keeps ids. An element imported again from JSON matches the element with the same id.
• Text does not hold ids. When .sysml text is imported into a project, Holarch matches top-level packages by name, and the elements inside them by their names. Ids are kept where elements match.

Export notes this under the export controls: "Element ids are kept in JSON. The text keeps the model; ids are matched by name when it is imported again."

Folders become packages

In a zip archive, each folder becomes a package that holds its files and subfolders. A file powertrain/engine.sysml inside the archive is read as if it were written inside package powertrain { … }. Files at the top of the archive are read as they are. Folders and files are read in name order.

What the preview compares

The preview has one row per top-level package (or, for a new project, per top-level element). Each row has a result:

How to use it

When and why

Use Import and Export when a model moves between Holarch and another SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams. v2 tool, or between Holarch projects:

• Start a Holarch project from a model written elsewhere.
• Bring in a package another team maintains, such as a component library, and update it when they send a new version.
• Hand a package to a supplier or to a tool that reads SysML v2 text or JSON.
• Keep .sysml files in your own version control next to the Holarch project.

Import files into this project

1. Open Model → Import and Export.
2. Under Import, choose Into this project.
3. Drop the files on the drop zone, or click it and choose them.

   You see "Reading the files…", then the preview: the number of top-level packages and files, any problems, and a table with Import, Package, Elements and Result.

4. Read the problems list, if there is one. It names each file and line that does not parse and each file that was skipped.
5. Untick any package you do not want to import. To replace a package that conflicts by name, tick it.
6. Click Import N Packages.

   The toast reads "Imported N packages." The page says "Imported N packages (M elements). Undo reverts the import in one step." Click Open Text to see them.

Import files into a new project

1. Open Model → Import and Export and choose Into a new SysML v2 project.
2. Drop or choose the files.

   The preview lists the top-level elements, all ticked.

3. Untick any you do not want, and edit the Project name. It defaults to the name of the single file, or the first package.
4. Click Create Project.

   The new project opens in the Editor.

From Manage Projects, Project Files ▾ → Import SysML v2 Files… does the same in one step. If parts of the files cannot be read, it asks first: "N problems found: parts of the files are left out. Create the project with the rest? To see the problems first, open a SysML v2 project and use Import and Export." Click Create Project to continue.

Update a package from a new version

1. Export or receive the new version as .sysml files or JSON.
2. Import it Into this project.

   The package shows Changed, with the number of elements added, changed and removed.

3. Click Import 1 Package.

   Elements that match keep their ids, so the links to them (requirements links, risks, view layouts, comments) stay. Elements that are no longer in the file move to the Trash.

Export the model or a package

1. Open Model → Import and Export.
2. Under Export, choose what to export: The whole model, or a package by its qualified name.
3. Choose the format: SysML v2 text (.sysml; a .zip for several packages) or SysML v2 JSON (.json).
4. Click Export.

   One file downloads, or a zip when the export holds several files. The toast reads "Exported <file>." or "Exported N files as a zip."

To export one package quickly, use the Browser: the row menu of a package has Export as .sysml and Export as JSON.

Pull from and push to a repository

Connect the project to one branch of a SysML v2 model repository to read its latest commit and to send your changes back.

1. Open Model → Import and Export and find the Repository section.
2. Enter the Repository address (the https address of its Systems Modeling API) and, if the repository needs one, the Access token.
3. Click Load Projects, then choose the Project and the Branch. To start a new repository project from this model, click New Repository Project instead.
4. Click Pull…. Holarch reads the branch's latest commit and lists each difference: New, Changed, Removed or Conflict. You see "Up to date: no changes in the repository." when there is nothing to pull.
5. Untick the differences you do not want, then click Apply Pull. The pull is one undo step.
6. After you change the model, click Push. Your changes since the last synced commit go to the branch as one new commit. You see, for example, "Pushed 3 changed as commit 1a2b3c4d."

A Conflict is an element changed both here and in the repository since the last sync. An unticked conflict keeps this project's version.

Worked example: the Hybrid Car demo

Create the demo first: on Manage Projects, click Project Files ▾ → New Demo Project → Hybrid Car (SysML v2).

1. Open Model → Import and Export. Under Export, choose The whole model and SysML v2 text, then click Export.

   A zip downloads with one file per top-level package, such as Vehicles.sysml, VehicleRequirements.sysml, VehicleBehavior.sysml and VehicleViews.sysml.

2. Open VehicleRequirements.sysml in a text editor. Change attribute maxCurbMass : MassValue = 1650 [kg]; to 1600 [kg] and save.
3. Back on Import and Export, choose Into this project and drop VehicleRequirements.sysml.

   The preview shows VehicleRequirements as Changed, with the number of changed elements. The other packages are not in the file, so they are not listed.

4. Click Import 1 Package.

   The value changes in the model. The requirement Sedan Mass (VR-1.1) names maxCurbMass, so its links become suspect (see Requirements and Verification in SysML v2 Projects). Press ⌘Z / Ctrl+Z to undo the import.

5. To start a second project from the same files, choose Into a new SysML v2 project, drop the zip and click Create Project.

Tips and good practice

• Use JSON to move a model between SysML v2 tools when ids matter, for example when the other tool keeps links by id. Use text when people read or review the files.
• Keep one top-level package per file. Export writes files that way, and a later import then matches package by package.
• Import a package from another team into its own top-level package. Updates then touch only that package.
• Check the problems list before you import. Members that do not parse are left out.

Common mistakes

• A package shows Conflict: "A package named X with other ids exists." The project has a package of that name that was not imported from this JSON. Tick the row to replace it (the old package moves to the Trash), or import into a new project.
• "The import holds two top-level packages named X; only the first is imported." Two files declare the same top-level package. Merge them into one file, or rename one.
• Elements are missing after the import. A member that does not parse is left out: "This member does not parse and is left out." Fix the line the problems list names, then import again.
• A JSON import is refused. Import one SysML v2 JSON file at a time, without .sysml files.

How it connects to other features

• Editor: imported packages open there; exported files are the text you see there.
• Undo and Trash: an import into this project is one undo step; elements it removes or replaces go to the Trash.
• Change control: values and documentation that change through an import make requirement links suspect, like any other edit.
• Holarch project files: Export this project… on Manage Projects saves the whole Holarch project, with risks, documents and other Holarch data. .sysml and JSON hold only the model.
• Conversion: to move a model between LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. and SysML v2, make a converted copy (see Converting Between LML and SysML v2).

The Import and Export page

Import

Elements outside any package in .sysml text are listed together in one row, Outside packages.

When the model changes while a preview is open (another tab, a collaborator, or Undo), the preview is computed again.

Export

Text export writes one file per top-level package, named after it (Vehicles.sysml). Elements outside packages go into Outside packages.sysml. JSON export writes one file named after the project or the package.

Repository

The Repository section links the project to one branch of a repository that offers the Systems Modeling API.

• Repository address: the https address of the repository's API. Holarch connects only to https addresses on public hosts; site administrators can limit the hosts and ports.
• Access token: stored encrypted for your account and this project, and sent only to that address. It is never shown again; leave the field empty to keep the stored token.
• Load Projects, Project and Branch: choose where to sync. New Repository Project creates a project in the repository for this model.
• Pull…, Apply Pull: read the latest commit, review the differences and apply them as one undo step. Holarch compares against the commit it synced last, so it can tell your changes from the repository's.
• Push: send the changes since the last synced commit as one commit. "Nothing to push: the model matches the last synced commit." means there is nothing new.
• Settings… changes the connection. Disconnect removes the stored token and the sync state; the model stays.
• Repository operations need the editor role. Viewers cannot pull or push.
• Pushes are refused for projects with regulated-data markings.

How files are read

• Files are checked before anything is read: their sizes, counts, nesting and text lengths.
• In a zip, hidden files and __MACOSX folders are ignored. Links, files outside .sysml, and a second copy of the same path are skipped, and the problems list says why.
• Text must be UTF-8. A byte-order mark is allowed.
• Each imported element is checked before it is written. An element that is refused takes its owned members with it; the problems list counts them.
• In JSON, an element kind Holarch does not support is left out, and its members move to its owner.

Messages

Limits

• Repository replies are capped at 64 MB for a whole pull, and each repository operation stops after 120 seconds.
• Each account can run at most 300 repository operations per hour.
• KerML (.kerml) files are not imported yet.
• Holarch data next to the model (requirement status, risks, budgets, simulator settings, view layouts) is not part of .sysml or JSON files. Use Export this project… on Manage Projects to keep it.

Related pages

• The Text Editor and Browser
• Converting Between LML and SysML v2
• Getting Started with SysML v2 Projects
• Import and Export for LMLLifecycle Modeling Language An open modeling language with a small set of classes and relationships that covers a system's whole lifecycle. Holarch models are LML models. projects and Holarch project files.

SysMLSystems Modeling Language A graphical modeling language for systems engineering, based on UML, with block, activity, state machine and parametric diagrams.® and OMGObject Management Group The standards body that maintains UML, SysML, UAF and XMI.® are registered trademarks of Object Management Group, Inc. in the United States and other countries.