wps / egon.io

A tool to visualize Domain Stories in your browser

Egon - The Domain Story Modeler

A tool to visualize Domain Stories in your browser.

About

• See http://domainstorytelling.org for more information on Domain Storytelling.
• The Egon.io Website contains a user manual.

Development

1. Install the dependencies via npm ci
2. Run the local development server via npm run start. Egon.io is accessible at http://localhost:4200.
3. Run tests via npm run test

Architecture

See architecture documentation.

Deployment

There are several deployment options:

• Standalone version (Zip file): If your organization already runs a web server, you can copy the zip file to the web server and extract it there to make Egon available to your organization.
• Docker container: If you prefer to provide websites as Docker container, you can build your own.
• If you don't want to build and deploy Egon.io yourself, than use one of the ready-to-use options provided by the Egon.io team:
  • Run Egon.io online
  • TODO: In the future, we will provide a ready-made Docker image: docker pull ghcr.io/wps/egon.io:latest

Deploy Standalone Version (Zip file)

1. In the package.json and environment.prod.ts update the version-tag appropriately
2. Run the command ng build --configuration production
   • This should create (or update the contents of) the folder dist_build
3. Run the command npm run zip
   • This should create (or update the contents of) the folder dist containing a zip.file named egon-xxx, where xxx is the name in the version-tag of the package.json

Deploy Docker Container

1. In the root directory of your sourcecode, run docker build -t egon-dev .
2. To start the container, run docker run -p 8080:80 egon-dev

Adapt container name and port as needed.

License

Egon - The Domain Story Modeler is licensed under GPLv3.0.

Egon uses bpmn-js which is licensed under the bpmn.io license.

Egon uses ngx-color-picker which is licensed under the MIT license.

GPLv3.0

Copyright (c) 2018-present WPS - Workplace Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

bpmn.io License

Copyright (c) 2014-present camunda Services GmbH

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The source code responsible for displaying the bpmn.io project watermark that links back to https://bpmn.io as part of rendered diagrams MUST NOT be removed or changed. When this software is being used in a website or application, the watermark must stay fully visible and not visually overlapped by other elements.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The MIT License

Copyright (c) 2016 Zef Oy

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

egon.io's Issues

change direction of activity

To make it easier to correct modeling mistaktes, the direction of an arrow should be changeable.

provide examples

examples (as .dst files) should be downloadable from GitHub

upgrade to diagram-js 3.0.0 and bpmn-js 3.0.0

https://bpmn.io/blog/posts/2018-bpmn-js-3-0-0.html

export as png or jpg

In addition to the svg export, a direct export to png or jpg would be useful because these file formats are often easier to share and distribute.

customizable icon set

Is your feature request related to a problem? Please describe.
One of the ideas of domain storytelling's pictographic language is to use domain-specific icon. But so far, only a fixed icon set is available in the modeler.

Describe the solution you'd like
Ideally, the modeler provides a configurable icon set. The modeler ships with a few dozen icons. Which are available in the palette and context pad should be configurable by the user, without the need to deploy a new version of the modeler.

If even the new, configurable icon set does not meet the user's reqirements, it should be easy for programmers to add additional icons. That would require to download the source code, program some javascript and CSS and deploy the modeler.

To ensure compatibility between modeler instances with different icon sets, the current icon set should be used as a fallback. E.g. unknown actor icons could be mapped to "person" actors.

Describe alternatives you've considered

Additional context
We should keep the base icon set as is, allowing end users to grow it if needed. That will likely result in scenarios where the palette becomes too big or unmanageable, but I think that might be a desirable problem to have and one to solve once we have it.

arrowheads should snap properly after moving work objects/actors

Add icons for work objects?

The standard icon set was compiled to express typical "office work" and should cover a lot of domains. Are there some icons missing that are universally applicable?

special characters should not be removed from labels

Describe the bug
Special characters like & are automatically revomed from labels after hitting enter.

Is there really a need to sanitize user input?

Expected behavior
There should be a reasonable guideline, which inputs are forbidden.

Desktop (please complete the following information):

• Modeler Version: v0.5.0

Change arrow animation order

Is your feature request related to a problem? Please describe.
Currently the animation order [the little number (1) or (2) next to an arrow] is fixed based on when I added it. The problem is that new arrows are discovered during the modeling phase, that might have an order number that is lower than the already existing arrows.

Describe the solution you'd like
I would like to be able to reorder arrows in the animation.

Describe alternatives you've considered
I would like to be able to edit the arrow order label.

Additional context
None

On dst-import story should be moved towards origin

Is your feature request related to a problem? Please describe.
When creating a story, one cannot see where the canvas origin is, sometimes resulting in stories that are far away from the origin, making it almost impossible to find them when importing them again.

Describe the solution you'd like
The story should be moved towards the origin when importing it.

Describe alternatives you've considered
One could also consider moving the story during export, but this would mean fixing a story that is far away from the origin would require importing and re-exporting it.

Size of annotation is not saved on export/import

Describe the bug
When I change the size of an annotation, the change is not preserved after export/import.

To Reproduce
Steps to reproduce the behavior:

1. Add an annotation to a work object or actor
2. Double click to add text
3. While the annotation is still in edit mode, change its size
4. Finish editing the annotation. The changed size is preserved.
5. Export as .dst
6. Import from .dst
7. The size of the annotation was reset to the default size.

Expected behavior
Size should be preserved

Desktop (please complete the following information):

• Modeler Version: v0.5.0
• Browser: chrome
• OS: Windows 10

Use npm package lock

To ensure all development machines use the same package tree, start using npm package-lock.json.

PNG Export Broken in Firefox

Describe the bug
When downloading the DS as PNG in Firefox, nothing happens. It works in Chrome (as implemented in #26). Chrome works fine. There is no error logged to the developer console.

To Reproduce
Steps to reproduce the behavior:

1. Create any domain story
2. Export as PNG
3. See nothing

Expected behavior
An offer to download the PNG, as with SVG.

Desktop:

• Modeler Version: current master ( c926fc9)
• Browser: Firefox 65, 64 Bit
• OS: Ubuntu 18.10 and Windows 10

Create workspace settings for VS Code

To avoid linting errors, create a settings file for VS Code:

• use workspace settings
• code formating rules should match the ones used by the linter
• activate "format on save"

Help users to number activities consecutively

Is your feature request related to a problem? Please describe.
Sometimes one needs to rearrange, delete or insert activities in a domain story. This will probably mess up the numbering.

Describe the solution you'd like
To check if the activities are in the right sequence, I replay the domain story. But that requires the activities to be numbered consecutively. If they are not, a error message is shown. I would like a error message that tells me which numbers are missing.

Describe alternatives you've considered
The error message could also show which is the last number that is still ok.

Replay Stories in Presentation Mode

Is your feature request related to a problem? Please describe.
When using the "replay" feature with large domain stories, I often have to scroll or zoom out to see the whole story unfold.

Describe the solution you'd like
When I start the replay, the application should turn in a "presentation mode". When I replay a story, I am not interested in the title and description. Also, I don't need the logo buttons, the import/export buttons, the dictionary and the keyboard shortcuts. Therefore, they do not need to be visible and the space can be used to maximize the space for the actual story.
The back, forward and stop button and the activity number (e.g. 3/11) only need to be visible during replay. Therefore, they can be removed when modeling and the space that is gained could be used to maximize modeling space (go back to 1 line layout instead of the 2 line layout that was introduced with v0.4.0)

Describe alternatives you've considered

add legend for keyboard shortcuts

The modeler should contain a legend for all available keyboard shortcuts.
Could be implemented similar to bpmn-js (see screenshot): Click on button opens overlay.

merge branch architecture-refactoring to master

make modeler work with Safari browser

test for compatibility issues and fix them

Missing labels and broken arrows

Describe the bug
After adding a new work object via the context pad, the label of the new work object was not visible anymore (see activity 9):

Also, the position could not be changed. I deleted the work object and created a new one (again from the context pad), but the behaviour was the same.
After that problem occured, I added an actor an an annotation that were broken too (see 9 and 2 in the screenshot). However, replay still worked.

I downloaded the Domain Story as SVG, but it did not contain the broken activity 9 and the broken annotation at 2.
Exporting and importing the .dst file fixed the Domain Story, all broken activities and labels worked as expected.

To Reproduce
I could not reproduce the behaviour manually, but there is an error in the console log:

app.js:28457 Error: element with id shape_6598 already exists
    at Canvas._ensureValid (app.js:27286)
    at Canvas._addElement (app.js:27332)
    at Canvas.addShape (app.js:27361)
    at CreateShapeHandler.execute (app.js:36232)
    at app.js:26713
    at CommandStack._atomicDo (app.js:26676)
    at CommandStack._internalExecute (app.js:26707)
    at CommandStack.execute (app.js:26463)
    at DSModeling.Modeling.createShape (app.js:35713)
    at AppendShapeHandler.preExecute (app.js:36009)

My guess is that the activity that connects to the newly created work object did not get a unique ID.

Desktop (please complete the following information):

• Modeler: v0.3.0
• Browser: Chrome
• Version 70.0.3538.110
• OS: Windows 10

arrows should not overlap with labels

When the label of a model element (actor or work object) has more than one line, arrows connected to the model element begin/end in the second line of text.
It should be possible to have at least two lines of text without overlapping arrows.

export story does not save arrows and main title

It looks like it's only possible to open the conversation icon with text after saving and reopening.

PS: thanks for your presentations at TAG 2018

increase vertical modeling space

Especially on small screens (13" Laptop) and with low resolutions (e.g. old presenters), the header takes up a lot of space. That reduces the space that is left for modeling.
We should find a way to increase vertical modeling space but at the same time allow several lines of description in the header.

Dirty Flag

Is your feature request related to a problem? Please describe.
When working on multiple stories, one can easily forget, if a story has been modified since the last time it was exported.

Describe the solution you'd like
Add a dirtyFlag if the DomainStory has changed since the last export.

Add test for .dst file upload with iconCustomization

The tests for importing .dst-files must be updated to test .dst-files with icon-configuration

move arrow's label manually

To fine-tune the layout, it would be helpful if one could move the labels of arrows manually.

edit activity by double clicking on activity label or number

Is your feature request related to a problem? Please describe.
Some users expect the activity label and/or number to be editable. After all, a double click on the label of an actor or work object lets you edit its label. Activities behave differently.
Also, double-clicking on the line of the arrow is not that easy.

Describe the solution you'd like
If I doube-click on the label of an activity, I can edit the label.
If I doube-click on the number of an activity, I can edit the number.

Describe alternatives you've considered
Inline-editing after double click would we closest to the behavior that users expect. But if I remember correctly, we have already looked into that and it was not so easy to get it to work with a label and a number.
For me, a viable alternative would be that a double-click on either the label or the number opens the same popup that we currently show when clicking on the arrow.

apostrophes are not allowed in labels

If you type an apostrophe, it gets removed as soon as you hit enter. For example: If you type the french word l'apostrophe it will be changed to lapostrophe.
Apostrophes should be allowed so that the modeler is usable for international users.

Reconnecting arrows breaks replay

Describe the bug
When you reconnect an arrow, the order in which the activities are displayed during replay is messed up.

To Reproduce
See attached .txt-file (rename to .dst)
bug in replay_2018-12-03.txt

Originally, there was an activity from Actor A to Object 1 to Actor B.
Then, I reconnected the arrow from Actor A to Object 2.
Then, I connected Actor A again with Object 1.
When I start the replay, the arrows and work objects from the original connection are shown (see attached screenshot)

Expected behavior
When replay is started, the arrows and work objects should be displayed in the correct order.

Desktop (please complete the following information):

• Browser

chrome

• OS: Windows 10

SVG and PNG export cut description

Describe the bug
When the description text is longer than the width of the domain story, the text gets cut off.

To Reproduce

SVG export cuts description_2019-03-07.txt --> rename to .dst

Steps to reproduce the behavior:

1. Add a lengthy description (several sentences)
2. Add e.g. an actor to the domain story (the "smallest" domain story that is possible)
3. Export as SVG
   Same behaviour when exporting as PNG

Expected behavior
The description could be wrapped or the width of the SVG could be increased.

Screenshots
SVG export cuts description_2019-03-07.svg.txt
--> rename to SVG

Desktop (please complete the following information):

• Modeler Version: v0.4.0
• Browser: Chrome 72.0.3626.121 (
• OS: Windows 10

colored icons

Is your feature request related to a problem? Please describe.
Let the user change the color of a work object or actor, e.g. to express org. units, to distinguish digital and analog work objects etc.

Describe the solution you'd like

Describe alternatives you've considered

Additional context
Could be conflicting with #35 and #33

change icon for one instance of a actor/work object

Is your feature request related to a problem? Please describe.
One of the ideas of domain storytelling's pictographic language is to use domain-specific icon. But so far, only a fixed icon set is available in the modeler. With this feature, it would be possible to add individual icons (or even more complex graphics).

Describe the solution you'd like
Change an icon by uploading a SVG from a local drive.
The custom SVG is exported in the .dst file to ensure compatibility.

Describe alternatives you've considered
Might not be that important anymore after implementing #32

Additional context

Need a way to model assumptions

It would be nice if the modeler had a way to captured assumptions in the tool

enable offline use

As of v0.2.0, the modeler requires an internet connection at least at first startup to download js libraries and icons. Once the ressources are cached in the browser, the modeler can be used offline.
It would be better to deploy all required ressources with the modeler so that it is truly offline enabled.

custom icons?

We want to brainstorm and compare different ways to customize icons.

enable renaming of several work objects at once

Let's say a work object "contract" occurs several times in the same story. Then you discover that the domain experts actually use the term "agreement". The modeler should provide a feature to rename all instances of "contract" to "agreement" so that I don't have to correct every occurence manually.

Activities cannot be deleted

Describe the bug
Activities cannot be deleted by clicking on the trash symbol in the context pad. However, deleting them with the delete key works.

To Reproduce

1. create an activity, e.g. between an actor and a work object
2. Click on the arrow to open the context pad
3. Click on trash symbol in the context pad
4. Activity is not deleted

Expected behavior
Activities can be deleted by either clicking on the trash icon in the context pad or by hitting the delete key on the keyboard.

Desktop (please complete the following information):

• Browser: Chrome
• Version: 70.0.3538.110
• OS: Windows 10

auto completion for editing work objects

To speed up modeling, the modeler should show suggestions for words when editing labels of work objects. The set of words that are suggested consists of all unique words that are used in work object lables.

Actors are usually unique per story, so auto completion is only really useful for work objects.

Parallel steps

Could find the feature, but seems that parallel steps are missing.

SVG export should countain title and description

search for text

enable to search for text in all the story and highlight/jump to matches

SVG does not contain Arrowheads

Describe the bug
When the SVG is opened in an image viewer or GIMP, there are no arrowheads.
It seems that it only works when the SVG is opened in a browser (Chrome or Firefox). This also affects SVGs that are rendered in Latex documents, both on Windows and Linux.

To Reproduce
Steps to reproduce the behavior:

1. Draw anything
2. Export as SVG
3. Open the image in something different than a browser.
4. See no arrowheads

Expected behavior
The arrowheads shoudl be rendered.

Screenshots

Desktop:

• Modeler Version: current master and https://www.wps.de/modeler
• Browser: Firefox 65, 64 bit
• OS: Ubuntu 18.10 and Windows 10.

Is there any workaround?

Text annotations don't show up.

In Chrome Version 70.0.3538.102 text is not displayed and looks like an empty annotation box.

customizable color themes

Is your feature request related to a problem? Please describe.
Provide customizable color themes for actors and work objects, e.g. to distinguish between them.

Describe the solution you'd like
Ideally, the color theme should be configurable by the user, without the need to deploy a new version of the modeler.

Describe alternatives you've considered

Additional context
Could be conflicting with #34 and #33

use outline icons instead of solid icons in palette and context pad

The modeler uses the outline version of Google's Material icons,. However, in the context pad and in the palette, solid icons are used instead.
The icons should be unified. Outline is the style of choice because it is more printer friendly.

reconnecting activities breaks auto-numbering

When an activity is reconnected to another target type (i.e. from an work object to an actor or the other way round), the activity needs to be update to show/not show a numbers. The appropriate dialog for editing the activity should be shown on click.

Auto-numbering should consider if a number was removed (e.g. by changing the source from actor to work object).

fix undo/redo

Undo (ctrl+z) and redo (ctrl+y) do not work properly:

• changes to actor & work objects are not pushed to the command stack
• does not adjust activitiy numbers
• does not change title and description
• possibly other issues (needs further testing)

hyphenation for labels

Is your feature request related to a problem? Please describe.
When work objects or actors have long names, these are not hyphenated. As a result, the line is broken after a fixes length. Readability of the labels decreases. Languages with longer words like German are especially affected.

Describe the solution you'd like
Hyphenation already works* for the title and description. It should work for labels as well.
*) depending on your language and browser. Works only in Firefox and Chrome for Android/Mac, see https://caniuse.com/#search=hyphen

Describe alternatives you've considered
Word-wrap is already enabled and not a solution.

deleting a group should not delete the group's content

dst files created with version 0.4.0 do not show up in 0.5.0 modeler

Hi,
Trying to import a 0.4.0 version dst-file into the new 0.5.0 online modeler does not show any of the created icons and processes. The modeler screen remains blank. However, the name list of all entities is imported and can be modified.
This affects all major browsers (IE, Firefox, Chrome). That said, Chrome at least gives a hint regarding an incompatible version when importing the yesterdays created file.
Hope time was not wasted and import can be made compatible. Thanks
Regards