JArchi Scripting

Create JavaScript scripts (.ajs files) for Archi, the open-source ArchiMate modeling tool. JArchi enables programmatic access to ArchiMate models for automation, reporting, and batch operations.

Core Concepts

Script Basics

JArchi scripts use JavaScript with a jQuery-like API. Scripts have .ajs extension and access the model through global variables:

// Global variables available in all scripts model // The current model (must be selected or loaded) selection // Currently selected objects in UI $(selector) // jQuery-like selector function (alias for jArchi())

Selectors

Query model objects using CSS-like selectors:

// By type (kebab-case ArchiMate types) $("business-actor") // All business actors $("application-component") // All application components $("serving-relationship") // All serving relationships

// By name $(".Customer Portal") // Objects named "Customer Portal"

// By ID $("#abc-123") // Object with specific ID

// Special selectors $("element") // All ArchiMate elements $("relationship") // All relationships $("view") // All views (ArchiMate, Canvas, Sketch) $("folder") // All folders $("concept") // All elements and relationships $("*") // Everything

Collection Methods

Collections support chaining and iteration:

// Traversal collection.children() // Direct children collection.parent() // Parent folder/container collection.find(selector) // Descendants matching selector

// Navigation (relationships) collection.rels() // All connected relationships collection.inRels() // Incoming relationships collection.outRels() // Outgoing relationships collection.sourceEnds() // Source concepts of relationships collection.targetEnds() // Target concepts of relationships

// Filtering collection.filter(selector) // Keep matching objects collection.not(selector) // Exclude matching objects collection.first() // First object only

// Iteration collection.each(function(obj) { /* process obj */ }); collection.size() // Count of objects

// Attributes collection.attr("name") // Get attribute collection.attr("name", "New Name") // Set attribute collection.prop("key") // Get property collection.prop("key", "value") // Set property

Creating Model Content

// Elements var actor = model.createElement("business-actor", "Customer"); var component = model.createElement("application-component", "API Gateway");

// Relationships var rel = model.createRelationship("serving-relationship", "", component, actor);

// Views var view = model.createArchimateView("Overview");

// Add elements to view var obj1 = view.add(actor, 100, 100, 120, 60); var obj2 = view.add(component, 300, 100, 120, 60);

// Add relationship to view view.add(rel, obj1, obj2);

// Folders var folder = $("folder.Business").first(); var subfolder = folder.createFolder("Processes");

Visual Styling

Set appearance of diagram objects:

// Colors (hex format) diagramObject.fillColor = "#dae8fc"; diagramObject.lineColor = "#6c8ebf"; diagramObject.fontColor = "#333333";

// Font diagramObject.fontSize = 12; diagramObject.fontStyle = "bold"; // normal, bold, italic, bolditalic

// Position and size diagramObject.bounds = {x: 100, y: 100, width: 120, height: 60};

// Other diagramObject.opacity = 200; // 0-255 diagramObject.labelExpression = "${name}\n${type}";

Console and Dialogs

// Console output console.log("Message"); console.error("Error message"); console.clear(); console.show();

// User dialogs window.alert("Information"); var confirmed = window.confirm("Proceed?"); var input = window.prompt("Enter name:", "Default"); var selection = window.promptSelection("Choose:", ["Option 1", "Option 2"]);

// File dialogs var filePath = window.promptOpenFile({title: "Open", filterExtensions: [".csv"]}); var savePath = window.promptSaveFile({title: "Save", filterExtensions: [".csv"]}); var dirPath = window.promptOpenDirectory({title: "Select Folder"});

File Operations

// Write file $.fs.writeFile("path/to/file.csv", content, "UTF8"); $.fs.writeFile("path/to/file.bin", base64Data, "BASE64");

// Include other scripts load(DIR + "lib/helpers.js");

// Special variables DIR // Directory containing current script FILE // Path to current script SCRIPTS_DIR // User's scripts directory

Exporting Views

// Render to file $.model.renderViewToFile(view, "diagram.png", "PNG"); $.model.renderViewToFile(view, "diagram.png", "PNG", {scale: 2, margin: 20}); $.model.renderViewToPDF(view, "diagram.pdf"); $.model.renderViewToSVG(view, "diagram.svg", true);

// Render to string/bytes var svgString = $.model.renderViewAsSVGString(view, true); var base64 = $.model.renderViewAsBase64(view, "PNG");

CLI Execution

Run scripts headlessly using Archi Command Line Interface.

Basic Syntax

Windows (PowerShell):

& "C:\Program Files\Archi\Archi.exe" -application com.archimatetool.commandline.app -consoleLog -nosplash --loadModel "model.archimate" ` --script.runScript "script.ajs"

Windows (CMD):

"C:\Program Files\Archi\Archi.exe" -application com.archimatetool.commandline.app ^ -consoleLog -nosplash ^ --loadModel "model.archimate" ^ --script.runScript "script.ajs"

Linux/macOS:

Archi -application com.archimatetool.commandline.app
-consoleLog -nosplash
--loadModel "model.archimate"
--script.runScript "script.ajs"

Common CLI Options

--loadModel "path/model.archimate" Load existing model --createEmptyModel Create blank model --script.runScript "script.ajs" Run jArchi script --saveModel "path/output.archimate" Save model after script --csv.export "path/output" Export to CSV --html.createReport "path/output" Generate HTML report --xmlexchange.export "path/output.xml" Export to Open Exchange XML

Script Arguments

Pass custom arguments to scripts:

& Archi.exe -application com.archimatetool.commandline.app -consoleLog -nosplash --loadModel "model.archimate" --script.runScript "script.ajs" ` --myArg "value" --anotherArg "value2"

Access in script:

var args = $.process.argv; args.forEach(function(arg) { console.log(arg); });

Linux Headless Mode

For servers without display:

xvfb-run Archi -application com.archimatetool.commandline.app
-consoleLog -nosplash --loadModel "model.archimate"
--script.runScript "script.ajs"

ArchiMate Types Reference

Element Types

Layer Types

Strategy resource , capability , course-of-action , value-stream

Business business-actor , business-role , business-process , business-function , business-service , business-object , contract , product

Application application-component , application-function , application-service , application-interface , data-object

Technology node , device , system-software , technology-service , artifact , communication-network , path

Physical equipment , facility , distribution-network , material

Motivation stakeholder , driver , goal , requirement , constraint , principle , outcome

Implementation work-package , deliverable , plateau , gap

Other location , grouping , junction

Relationship Types

composition-relationship , aggregation-relationship , assignment-relationship , realization-relationship , serving-relationship , access-relationship , influence-relationship , triggering-relationship , flow-relationship , specialization-relationship , association-relationship

Best Practices

Check model is set before operations:

if (!model.isSet()) { console.error("No model selected"); exit(); }

Use meaningful names when creating elements

Batch operations - collect changes, apply at end

Handle errors gracefully with try/catch

Log progress for long-running scripts

Use folders to organize created elements

Additional Resources

Reference Files

For detailed API documentation, consult:

• references/api-elements.md

• Element types, creation, properties

• references/api-collections.md

• Selectors, traversal, filtering

• references/api-views.md

• Views, visual objects, styling

• references/api-model.md

• Model operations, loading, saving

• references/api-utilities.md

• Console, dialogs, file I/O

• references/cli-reference.md

• Complete CLI options and automation

Example Scripts

Working examples in examples/ :

• query-elements.ajs

• Query and report on model elements

• create-view.ajs

• Create view with elements and relationships

• export-report.ajs

• Export model data to CSV

• batch-update.ajs

• Batch update element properties

• cli-automation.ps1

• PowerShell automation script

• cli-automation.sh

• Bash automation script