Astah Diagram Automation

Guided Teaching Style

Use a clear, stepwise teaching style: state the diagram goal and the relevant Astah API choice before acting, make one bounded change at a time, then explain the verification result and the next decision. Keep explanations concrete for UML learners: connect each created model element, relationship, lifeline, message, or combined fragment to its diagram role. Do not replace the required backup, transaction, and verification steps with explanation.

Core Method

Use Java programs with the Astah Java API to open a .asta project, start a transaction, create or delete model elements and diagram presentations, save the project, and run verifier programs. Do not edit .asta files as XML, JSON, or text; treat them as Astah project data.

Use this skill as a portable workflow. Paths must be discovered or configured in this order:

1. Explicit script parameters: -AstahApiJar, -AstahProJar, -ToolsDir.
2. Environment variables: ASTAH_API_JAR, ASTAH_PRO_JAR.
3. Local files under this skill: lib/astah-api.jar, lib/astah-pro.jar.
4. Legacy local fallback: E:\Program\astah-api.jar, E:\Program\astah-pro.jar.

Run scripts/check-astah-env.ps1 before the first tool run in a new environment.

Workflow

1. Locate target files:
   - Find .asta files with Get-ChildItem -Recurse -Filter *.asta -File.
   - Find reusable tools with rg -n "Usage:|createClassDiagram|createSequenceDiagram|accessor.open|accessor.save" asta_tools -g "*.java".

2. Inspect before modifying:
   - Use DumpAstah <project.asta> to print diagrams, classes, and presentation counts.
   - Use DumpDiagram for layout and presentation details when available.
   - Read references/tool-interface.md when choosing or documenting project-side Java tools.

3. Back up before write operations:
   - Prefer tools that already call a backup(Path file) method.
   - If adding a new writer, copy the .asta beside itself with a timestamp before writable open.

4. Write diagrams inside a transaction:
   - Open writable with accessor.open(projectPath, false, false, true).
   - Call TransactionManager.beginTransaction().
   - Create packages, classes, components, lifelines, messages, and presentations.
   - On success call TransactionManager.endTransaction() then accessor.save().
   - On failure call TransactionManager.abortTransaction() and rethrow.
   - Always call accessor.close() in finally.

5. Verify:
   - Re-run DumpAstah.
   - Run domain-specific Verify* tools when available.
   - Read references/pitfalls.md before debugging broken output or porting to a new machine.
   - Open the .asta in Astah if visual inspection is required.

Commands

Check a colleague's environment:

powershell -ExecutionPolicy Bypass -File .\scripts\check-astah-env.ps1

Run a tool with auto-discovered jars and tools:

powershell -ExecutionPolicy Bypass -File .\scripts\run-astah-tool.ps1 -Tool DumpAstah -Project ".\project.asta"

Run a project-specific tool:

powershell -ExecutionPolicy Bypass -File .\scripts\run-astah-tool.ps1 -Tool YourTool -Project ".\project.asta" -ToolsDir ".\asta_tools"

Run with explicit jar paths:

powershell -ExecutionPolicy Bypass -File .\scripts\run-astah-tool.ps1 -Tool DumpAstah -Project ".\project.asta" `
  -AstahApiJar "D:\Astah\astah-api.jar" `
  -AstahProJar "D:\Astah\astah-pro.jar"

API Patterns

Create or update a class diagram:

• Use ClassDiagramEditor.createClassDiagram(owner, name).
• Create model classes with BasicModelEditor.createClass(owner, name).
• Place nodes with ClassDiagramEditor.createNodePresentation(model, point) or the parent overload.
• Create relationships with BasicModelEditor.createDependency(...), then createLinkPresentation(...).

Create or update a sequence diagram:

• Use SequenceDiagramEditor.createSequenceDiagram(owner, name).
• Create base classes for lifelines, then createLifeline("", x) and set ((ILifeline)p.getModel()).setBase(baseClass).
• Set lifeline length with p.setProperty("lifeline_length", "900").
• Create messages with createMessage(label, source, target, y).
• Create native loop or opt frames with createCombinedFragment("", "loop" or "opt", point, width, height).

Create component or SoftBlock diagrams:

• Prefer public Astah API where it works.
• If public API coverage is insufficient for the installed Astah version, inspect local Create* or Inspect* tools before using reflection or internal commands.

Bundled References

• references/local-method.md: detailed Java/Astah workflow and code templates.
• references/tool-interface.md: expected Java tool roles, CLI contract, writer and reader contracts.
• references/pitfalls.md: common failure modes and safety rules.

Sharing Rules

To share this skill with a colleague, share the repository or the whole astah-diagram-automation folder. Do not include licensed Astah jars, private .asta files, or project-specific Java tools unless your team is allowed to share them.

For a complete runnable handoff, provide:

• This skill folder.
• Their own Astah installation or approved astah-api.jar and astah-pro.jar.
• Project-side asta_tools/*.java for specific generated diagrams. The bundled assets/asta_tools/DumpAstah.java is enough for a first read-only smoke test.
• The target .asta project only when it is allowed to be shared.