archimatetool/archi-scripting-plugin

jArchi - Scripting for Archi: ArchiMate Modelling Tool

Archi Scripting Plug-in

What is this?

This is an extension to Archi that allows scripting of tasks using the JavaScript language.

Read official announcement for more information about binary distribution and license.

How to use it

Binaries will be made available separately.

Roadmap

There is no formal roadmap for the moment, development is done through sprints that try to gradually improve the overall value of this plugin. The Focus is currently on user experience.

Contributing code to Archi and Plug-ins

Please see How can I contribute code to Archi? for general guidance on how to contribute code to Archi and its plug-ins.

Archi

Archi® is a free, open source, cross-platform tool and editor to create ArchiMate models.

The Archi® modelling tool is targeted toward all levels of Enterprise Architects and Modellers. It provides a low cost to entry solution to users who may be making their first steps in the ArchiMate modelling language, or who are looking for a free, cross-platform ArchiMate modelling tool for their company or institution and wish to engage with the language within a TOGAF® or other Enterprise Architecture framework.

ArchiMate® is an open and independent Enterprise Architecture modelling language that supports the description, analysis and visualization of architecture within and across business domains. ArchiMate is one of the open standards hosted by The Open Group and is fully aligned with TOGAF®.

The Archi website is here: https://www.archimatetool.com

archi-scripting-plugin's Issues

Attributes for DiagramModelComponentProxy are inconsistent

Hi,

While working with a colleague, I nooticed that:

• Most attributes for DiagramModelComponentProxy are accessible only through attr() on a collection and not directly through getters/setters
• Most attributes for DiagramModelComponentProxy have hyphen in they names, making it impossible to create getters/setters

I guess we should rework this for final version

Should .delete() on a relationship object remove it from the model?

I thought .delete() on a relationship would remove it from the model, not just from the view? Or have I missed something?

selection.filter("application-function").rels("composition-relationship").each(function(obj) {
	console.log('Deleting relation: ', obj.name);
	obj.delete();
});

Version of jArchi, Operating System

MacOS 10.14.4
Archi 4.4.0
jArchi version 0.4.4.201903221626

Expected Behaviour

.delete() to delete a relationship from the model

Actual Behaviour

.delete() removes the relationship from the view, but remains in the model.

Steps to Reproduce the Behaviour

1. Unzip and open the sample model
2. Grab the script from attached or cut and paste from the note on the diagram.
3. Select any application function and run the script.

DeletingRelationships.archimate.zip

test.ajs.zip

tie the scripting into being adapter for EMF

Request: tie the scripting into being adapter for EMF ... so when things like add, remove, changes happen one can tie scripting code into it

no remove

There seems to be no way to remove anything from the model... at least it is not documented

Allow Jarchi scripts to trigger menu actions

It would be great to have a possibility to start Archi UI menu actions via a Jarchi script without having indepth knowledge of the underlying Archi java software architecture. Maybe it is possible to extend the current Jarchi DOM with Archi UI menu functions.

$(view).each

to get to the elements in view one used $(view).each(function(concept){...});

but this does not work with Folders

.concept is wrong it is .archimateConcept

.concept is wrong it is .archimateConcept needs to fix in documentation

Setting the opacity of Application-Interface elements does not work

Version of jArchi, Operating System

Archi 4.3 on windows 10

Expected Behaviour

I have below script that (among others) should set the opacity of an Application-Interface element,

    element.fontSize  = "10";
    element.fontColor = "#545556";
    element.fontName  = "Arial Narrow";    
    element.opacity = "0";  

Actual Behaviour

When I run this code, all element appearance attributes are set according to the script except from the opacity attribute which is not set according to script.

Steps to Reproduce the Behaviour (with attached test files/script)

1. Create interface element in a view
2. give it a background color and a line color (all colors except white are fine).
3. run my script snippet and see that the interface element does not receive the expected opacity setting

'selection' is empty when no views are opened but script invoked from context menu

Version of jArchi, Operating System

Archi 4.4.0 & jArchi 0.4.4 (latest codebase)
Archi 4.3.3 & jArchi 0.4.3

Expected Behaviour

selection should reflect curent selection

Actual Behaviour

selection is empty when no views are opened

Steps to Reproduce the Behaviour (with attached test files/script)

1. Create a new empty model. This will also create and open a Default View
2. Run this simple script: console.log(selection) from the context menu on DefaultView in the model tree: it works and displays [archimate-diagram-model: Default View]
3. Close Default Viewand retry the same script from the context menu on DefaultView in the model tree: it simply displays []

completeness and consistency of element-type in jArch

Version of jArchi, Operating System

Expected Behaviour

Actual Behaviour

Steps to Reproduce the Behaviour (with attached test files/script)

Images for Wiki

model.addRelationship is not in jArchi documentation

model.addRelationship is not in jArchi documentation

add to menu

would be nice in archi to be able to put a script in the menus

Support creating new views and visual components

We have not yet implemented adding/creating new views and diagram components.

Views
ArchiMate objects (using an existing element and with a new element)
ArchiMate connections (using an existing relationship and with a new relationship )
Notes
Groups
Other Connections
Canvas and Sketch components

• What is the best API for these?
• Which proxy or util classes should own the add/create methods? (For example, one can add an object to a View and also as a child of another object)

add in specific syntax and examples for visual objects

the visual object attributes... like fillColor... what is the syntax here for giving a value...

needs to be in documentation and perhaps an example...

Add DOM functions (API)

Model manipulation requires a good knowledge of Archi internal API. This is quite easy when working solely with the model concepts, but can become hard when dealing with views.

Some helper functions could help:

• ListOfElements getElementsInView(v View)
• ListOfRelationships getRelationshipsInView(v View)
• ListOfConcepts getConceptsInView(v View)

Those are only examples, we might try to design a good API that could be completed over time.

diagram-model-connection a relationship or an Element

is diagram-model-connection a relationship or an Element... suggestion... in the tables in documentation... separate those things that are created with addRelationship.. and those with addElement

Write to File and Open in Browser example script error

Version of jArchi, Operating System

• jArchi 0.4.3.201902121146,
• Archi 4.3.3 (201902121114),
• MAC OS X 10.13.6 (17G5019)

Expected Behaviour

Browser opens without script errors

Actual Behaviour

Browser does not open with...

Script Error at: javax.script.ScriptException, javax.script.ScriptException: TypeError: Browser.newInstance is not a function in /Users/XXXXX/Library/Application Support/Archi4/scripts/examples/Write to File and Open in Browser.ajs at line number 31

Steps to Reproduce the Behaviour (with attached test files/script)

1. Install com.archimatetool.script_0.4.3.201902121146.zip
2. Run Write to File and Open in Browser example script

Performance of Arcjimate

Version of jArchi, Operating System

Expected Behaviour

Actual Behaviour

Steps to Reproduce the Behaviour (with attached test files/script)

Diagram component class type selectors are not implemented

In the wiki we say that these visual class types are supported:

diagram-model-note 
diagram-model-group 
diagram-model-connection
diagram-model-image
diagram-model-reference
sketch-model-sticky
sketch-model-actor
canvas-model-block
canvas-model-sticky
canvas-model-image

Using any of these to select or filter a collection does not currently work. This is because SelectorFilterFactory does not check if these types are instances of IDiagramModelComponent. Currently, the only type instanceof checks are on:

IArchimateConcept
IDiagramModel
IFolder

We need to add IDiagramModelComponent to these for this to work.

no way to create new folder

there seems to be no way to add in a new folder... needs to be added into the types one can instantiate

Feature Request: Extend jArchi interface to allow access to 'Archi preferences'

Do you think it would be useful to be able to access the Archi preferences from jArchi?

$("preferences").find("preference name").get() ??? .list . .set ???

There are a few in particular I think could be useful: The grid sizing and default object size would be useful for any script that wanted to do layout adjustment and not be hard coded.

(I'm working on a script that can "grid layout" a series of concepts to create dashboards - capability maps or Plateau to Work Package views for example)

Obviously, not high priority.

.find() does not work as expected for diagram objects

Hi,

It seems that when working on diagram objects, .find() almost always return a bad value (or zero). .children() works as expected though.

The main difference between both is that .children() relies on class specific implimentation while .find() is hard coded to use getEObject().eAllContents() which doesn't seem to work for diagram objects.

getType() returns camel case class type instead of kebab-case

Presently calling getType on an object returns the type class as camel case:

var type = $('business-role').first().type;
console.log(type);

returns "BusinessRole"

So, if we wanted to test a type against a string we have to use camel case instead of kebab-case.

Should we return type as kebab-case?

view has Visual Objects

the documentation should state that views return Visual Objects rather than the concepts

Add command line support

The script plugin should use the new command line API and make it possible to run a script, either on the full model or on a selection.

This last part (run a script on a selection) requires us to define a simple way to select concepts or views (is name enough knowing that several concepts or views can have the same name?).

which types can be created...

model.addElement('archimate-diagram-model','');

does not work... this brings up which things you can create and which you can't... needs to be in the documentation...

I do think that it should be called createElement rather than addElement

Add function to duplicate a view

Please, as this can be done with the Gui.

Allow JArchi to read/update the "Access Type" property on Access relationships.

Allow JArchi to read/update the "Access Type" property on Access relationships.

Which object methods should be public?

These are currently public methods:

ArchimateConceptProxy#inRels()
ArchimateConceptProxy#outRels()
ArchimateConceptProxy#objectRefs()
ArchimateConceptProxy#viewRefs()

DiagramModelProxy#objectRefs()
DiagramModelProxy#viewRefs()

Should they remain public or only accessed via EObjectProxyCollection?

.archimateConcept does not work for Relationships

if one does

$("view").each(function(view){
var grouping_name = view.name + "__grouping";
var theGrouping = $("grouping." + grouping_name).first();

if ( theGrouping == null ) {
theGrouping = model.addElement("grouping",view.name + "__grouping");
}

$(view).find('concept').each(function(child){
window.alert(child.type);
model.addRelationship('aggregation-relationship','',theGrouping,child.archimateConcept);
});

});

when It hits a relationship it fails....

Allow JArchi to read/update the "Strength" property on Influence relationships

Implement get/set Strength on Influence relationships

Relationship isLegal

need the ability to see if a relationship is legal perhaps before you try to build it...

so

isLegal(relationship,source-type,target-type)

Re-organise wiki

The wiki API page is getting rather long. Suggest breaking it up into sections.

Agree? Disagree? Suggestions?

model.addElement

model.addElement in not in the jArchi documentation

addRelationship will not work with a Relationship

there are multiple relationships to relationships.... any relationship can be a source or target to a (association) relationship to an Element (but not a relationships to relationship)...

also Product, Grouping, and Location can have aggregation and composition to a relationship.... but that does not work,... and it is not documented this way either...

suggestion rename is() to isType()

suggestion rename is() to isType()... is() can be misleading...

model has diagram information as well

model has concepts in it as well as Visual Objects... there ought to be a way we can get only the model elements without the Visual Objects

Feature Request: Diagram 'button' to execute a script

TL;DR - Allow 'scripts' objects to be dropped onto a view/diagram, which creates a 'button' that when clicked, executes the script.

It could be useful to have 'buttons' (or a series of buttons) that can be linked to scripts to allow, for example, different 'colour-view' scripts to be executed - a use case that I tend to use a lot.

I would imaging that:

• The button would be a 'drawing only' object. It would not be a part of the Archimate concepts or relations
• You'd probably would not want it printed/exported to PDF & PNG etc
• It would have properties for 'name', 'script', some styling
• It could even have 'properties' that could be passed to the script to provide a form of individual context (i.e. different buttons run the same script with different parameters)
• The script could be 'dragged and dropped' onto the canvas (like views can be) to create the button.

Export to Excel

Several use-cases require the creation of an Excel file with multiple sheets (so CSV in not an option). We should find a make to make this possible.

This could be done through a JAVA or JS lib. My personal opinion on this is that JS lib is better and that we should just provide POC code.

FWIW, here are links to known JS libs:

• https://github.com/SheetJS/js-xlsx (used by alasql to read from/write to excel files, maybe to big/complicated)
• https://www.codeproject.com/Articles/1197349/Excel-files-in-Javascript-the-simple-way (seems a lightweight solution, allow only creation)

Feature Request: enable access to relationship bendpoints on visual objects

Feature request - enable access to relationship bendpoints on visual objects.

use case: I have a set of relationships - typically serving/served-by - where I'd like to swap the sourceEnd and targetEnd. That's easy enough to do,

however...

I've also manually routed the relationship on one or more views. Using the script doesn't touch the bendpoints, so the original relationship that traversed sourceEnd->bend1->bend2->targetEnd, now begins at the former targetEnd, but still traverses bend1->bend2 on its way to the former sourceEnd. This kinks the relationship visualization in unexpected and unwelcome ways.

I'd like to be able to reset the sequence of bendpoints so that the relationship's visual representation is preserved.

Console is not updated on long running operations

Because running a script is run on the main thread, the Console view is not updated until the script finishes. This is noticeable on long running operations.

We can't run the script asynchronously or yield to the Display thread (Display.getCurrent().readAndDispatch();) because the user could edit the model that is being processed while the script is running.

Updating the console asynchronously doesn't work either.

Interesting to note that when running Archi and a script from Eclipse, System.out.println(string) messages are displayed asynchronously in Eclipse.

The problem is how to update the Console View UI without allowing the user to interact with the UI when the script is running. As long as the model being processed is open in the UI we can't let the user edit it while a script is running.

BUG - Don't show hidden (dotted) folders & files in Script Manager browser

Version of jArchi, Operating System

Archi 4.3.1
OSX 10.14.2 (Mojave)

Expected Behaviour

Folders and files that are usually hidden by the operating system (i.e. with dotted names) are shown in the Script Manager browser

Actual Behaviour

If, for example, you use git to co-ordinate your scripts across teams and laptops, you will see a ".git" folder in the Script Manager. The .git folder should not be seen.

(Impact minor)

Note:
Behaviour only tested on OSX, not on Windows based. (If I get a chance, I'll update this ticket with the Windows behaviour)

Steps to Reproduce the Behaviour (with attached test files/script)

1. Point Script Manager folder to a folder that had a .git folder
2. Open Script Manager browser
3. Observe the (usually hidden) .git folder in the tree

model, view, folders

so there are the following

model - ArchiMateModel
view - ArchiMateDiagramModel
folder - Folder

there is no documentation on how one gets its parts.... children does not work... there is nothing in the documentation about how to get to all of the parts

Invoke script through context menu

For the moment the plugin works only using the whooe model as a starting point. Several use cases (eg. extract information for a set of views) require a way to run a script with a kind of "selection".

I suggest we add a way to select concepts and views on the model tree and run a script from a context menu. This selection could then be made available to script through a pre-defined exposed variable (list of EObject or something similar).

Add mergeInto() function

Add new methods:

ArchimateConceptProxy#mergeInto(newElementProxy, deleteOld);
ArchimateConceptProxy#mergeInto(newElementProxy);

The "old" element gets deleted and its properties are "merged" (ie. added) to the newElementProxy.
The second method would then simply call mergeInto(newElementProxy, false)

Documentation should be appended to newElementProxy's documentation too.

• Add ArchimateElementProxy#mergeInto(ArchimateElementProxy newElementProxy) method that uses the passed proxy element instead of creating a new one. Care should be taken so that changes on newElementProxy properties are tracked in commands.
• Refactor ArchimateElementProxy#setType to create a newElementProxy and call mergeInto()
• Now this should allow to merge a concept into another.
• It could then be possible to further refactor by creating DiagramModelComponentProxy#setConcept(ArchimateElementProxy newElementProxy) using the code inside "Update all diagram objects" section of ArchimateElementProxy#mergeInto and then refactor ArchimateElementProxy#mergeInto to use DiagramModelComponentProxy#setConcept.

can one import other javascript files into a javascript file

can one import other javascript files into a javascript file... if so can we document what you have allowed for that...

junction is instantiated through element

junction is instantiated through element ... but this is not in the documentation

New Feature - Add autoNest option to view.add(element)

In some occasion, a script has to add an element to a view using absolute coordinate, but if the added element is (visually) on top of another then it is not nested. This feature request suggests to add a new (optional) option to view.add(element, ...) method so that in such case the new element is nested inside the already existing one below it.

So this involves addind a new ArchimateDiagramModelProxy#add() method.

This new method would be something like: public DiagramModelObjectProxy add(ArchimateElementProxy elementProxy, int x, int y, int width, int height, boolean autoNest)

With autoNest=false, we use the current implementation, but with autoNest=true we should reproduce the new behavior which should be implemented in ModelUtil#addArchimateDiagramObject()

A proof of concept jArchi implementation is provided as an example: AutoNest.txt

Feature request: export views to more than PNG format

I have a publication use case for this feature. I have a model with 19 views. I commonly publish the models to pdf for distribution. I use the File/Export/View as Image function to produce the PDFs. Executing this 19 times for each publication cycle takes a bit of time that I'd like to automate.

I'm told that jarchi can already programmatically manipulate and save views as PNGs. But I am left with the manual task of printing to PDF - so no real time savings or accuracy improvements there.

Consider adding ability to export views to more than PNG format in jArchi

Thanks