Skip to content

Import and export ​

You rarely start from nothing. umlimator.py import reads diagrams and infrastructure descriptions you already have into a model, and lists, line by line, whatever it could not read. umlimator.py export writes a model's BPMN back as BPMN XML.

Formats ​

SourceBecomesNeeds
Structurizr DSL (.dsl)a map: people, systems, containers and components, their relationships, and the workspace's views—
Structurizr JSON workspacetyped C4 viewsNode
C4-PlantUMLa map, from its element, relationship and boundary macros—
Mermaid flowchart or grapha map; with --typed, a flowchartNode for --typed
Mermaid C4Context, C4Container, C4Componenta map—
Mermaid classDiagrama UML class diagramNode
Mermaid sequenceDiagrama UML sequence diagramNode
Mermaid stateDiagrama UML state machine diagramNode
Mermaid requirementDiagrama SysML requirement diagramNode
Mermaid erDiagraman ER diagramNode
Mermaid mindmapa mindmapNode
DBML (.dbml)an ER diagramNode and @dbml/core, installed by you
BPMN XML (.bpmn)a BPMN diagramNode and bpmn-moddle, installed by you
docker compose config --format jsona map of services, depends_on and networks—
kubectl get … -o jsona map of workloads, Services and Ingresses—

@dbml/core and bpmn-moddle are never dependencies of umlimator: install them yourself when you need them.

Examples ​

bash
python3 umlimator.py import workspace.dsl --out model.json            # a diagram you have already, as a model
python3 umlimator.py import classes.mmd --out classes.json            # a Mermaid classDiagram, as a UML class diagram (needs Node)
python3 umlimator.py import checkout.mmd --out checkout.json          # a Mermaid sequenceDiagram, as a UML sequence diagram (needs Node)
python3 umlimator.py import order.mmd --out order.json                # a Mermaid stateDiagram, as a UML state machine diagram (needs Node)
python3 umlimator.py import needs.mmd --out needs.json                # a Mermaid requirementDiagram, as a SysML requirement diagram (needs Node)
python3 umlimator.py import schema.mmd --out schema.json              # a Mermaid erDiagram, as an ER diagram (needs Node)
python3 umlimator.py import returns.mmd --typed --out returns.json    # a Mermaid flowchart as a flowchart (without --typed, a map)
python3 umlimator.py import workspace.json --out c4.json              # a Structurizr JSON workspace, as typed C4 views (needs Node)
python3 umlimator.py import schema.dbml --out schema.json             # DBML, as an ER diagram (needs Node and @dbml/core, installed by you)
python3 umlimator.py import plan.mmd --out plan.json                  # a Mermaid mindmap, as a mindmap (needs Node)
python3 umlimator.py import order.bpmn --out order.json               # BPMN XML, as a BPMN diagram (needs Node and bpmn-moddle, installed by you)
docker compose config --format json > compose.json && python3 umlimator.py import compose.json --out model.json
kubectl get deploy,sts,svc,ing -A -o json > cluster.json && python3 umlimator.py import cluster.json --out model.json

How import reads a file ​

  • It tells the format from the content, then the extension; --format decides.
  • In a map, groups, boundaries, subgraphs, networks and namespaces become boxes. Structurizr's views stay views, a card opening the view below it.
  • The typed Mermaid readers draw no boxes for groups: a class diagram's namespaces become packages, and a flowchart's subgraphs (with --typed) and an erDiagram's are not read. The cards in them are, and each group left out is listed on stderr.
  • A Structurizr, C4-PlantUML or Mermaid C4 source's people are people (person, or user outside the system), and its phone apps phones. A Structurizr workspace's styles give its elements their shapes (shape Person, Cylinder, WebBrowser, ...), in Structurizr's own order; a shape the map has no counterpart for is listed in notImported.
  • Whatever the file holds that import doesn't read is listed on stderr with its line (in JSON, its path).

What each element becomes, and what is left out: docs/module-api.md § Import.

Export ​

bash
python3 umlimator.py export order.json --out order.bpmn   # a model's BPMN as BPMN XML, laid out (needs Node and bpmn-moddle)

export writes BPMN XML only. The Mermaid writers (class, sequence, state machine, requirement, entity-relationship, flowchart and mindmap) are internal to the module: they live in src/readers/, are used by the tests' round trips, and are not exported by the package or reachable from the command line.

For pictures and documents rather than source formats:

OutputHow
SVG, PNGmap.toSVG(), map.toPNG(), the page's Export menu, or umlimator.py stills
PDFumlimator.py pdf (Command line)
Animated PNG of a storyumlimator.py record
A self-contained pageumlimator.py render (The standalone page)