All arrows are numbered, "append mode" and message flow

[kirchsth]

Hi @johthor,

I like the tool and your (counter) model uses shorter notations (Maybe in one of the next versions of C4-PlantUML I will reuse some of your patterns).

I found/have some ideas which could be useful in your tool:

1. all arrows are numbered and colored

In https://medium.com/domain-driven-stories/using-draw-io-to-capture-domain-stories-3ca828f732a0

all arrows have the number of the activity and based on the position in the activity the number has a different color

• blue: activity starts by an actor;
• red: activity ends by an actor;
• yellow: all other which combines only objects

2. the last used/created object of an activity is stored in $lastObject

Actors are typically predefined and has already a concrete name that they can be reused in the model, but objects are very oft dynamically created and cannot be referenced at the moment.
If it is stored in eg. !global $lastObject it can be copied and reused in the script

3. startObjectNote($object=""), endNote()

If no $object is defined then automatically the $lastObject gets the note, otherwise the concrete defined one.
(optional a startActorNote() could be added too, in this case the default is the last defined Actor()).

Or if we change the definition that the default element is
a) after an activity() call the $lastObject
b) after an "Actor()" or "Object()" call the corresponding actor or object
then only one startNote() call could be enough.

4. message flow modelling

In https://github.com/ddd-crew/domain-message-flow-modelling and https://domainstorytelling.org/articles/domain-message-flow-modeling/

complete messages with all properties can be modelled.
If you like the pattern with the tables, we could add a note sample in the documentation that it can be reused.

5.append() call, maybe obsolete
I didn't saw your "11-composable-activities" branch therefore I introduced an append() function.
But I assume your approach is better.

I started with a "dummy implementation" (styling,... arguments are missing, automatic color calculation of the numbers....) but I think it shows the rough ideas.

If you like I could eg. add the automatic color calculation (as soon your composable activities implementation is finished) and the !global $lastObject.

Best regards
Helmut

[kirchsth]

I tried a simplified notation of object (message) properties. : starts a new column and ; a new row.

objectNote("", $properties("firstStartTime (epoch):long,ms;lastEndTime (epoch):long,ms;duration (min):"))

!$mixed = "bla bla bla\n" + $properties("firstStartTime:epoch ms;lastEndTime:epoch ms;duration:min") + "\nbla bla bla bla"
objectNote("", $mixed)

objectProperties("", "^firstStartTime:epoch ms:bla bla bla;lastEndTime:epoch ms:bla bla bla;duration:min:bla bla bla")

Details see below (styling,... arguments are still missing)

[johthor]

We could also check if it is possible to take JSON data as an input and render it as a table something like {rows: [{row1},{row2}], header: {..}} and / or render the JSON directly as a JSON diagram partial.

Even YAML might be possible.

[johthor]

Hi @kirchsth,
I've had some time to think about your ideas, and I believe most of them will be compatible with #11 and work nicely with the development already done there.

However, regarding "1. all arrows are numbered and colored" I believe that they only number all connecting arrows because they are reusing the work objects.
This does not comply with the description given at the domain storytelling site.

Every actor appears only once in the domain story.
But for every activity,
we draw a separate work object
(even if the same work object already exists in a previous sentence).
If you follow that rule,
arranging work objects and arrows becomes a lot easier.
There is another good reason for this.
As the story evolves,
a work object may change its status or representation.

Therefore, I wouldn't want to make this the primary mode to number activities.
But I don't see a reason not to support this way of numbering activities via a secondary mode.

Regarding "2. the last used/created object of an activity is stored in $lastObject" that is kind of already part of #11.
I wanted to simplify the dynamic creation of work objects and get rid of some of the duplicated parameters of the activity macro as well as support complexer activity structures.
That means after the PR is merged the alias of the work object created last will most likely be available as $lastCreatedObject, actors as $lastCreatedActor, and both might also be available as $lastCreatedElement.

Unfortunately, that leads to yet another breaking API change which takes longer than expected.

Regarding "3. startObjectNote($object), endNote()" I really like the idea
and thought about something similar already as for now the $note argument only allows for short simple notes.
With $lastCreatedElement there is no need to distinguish between actor and object references.

However, I would prefer the names beginAnnotation() and endAnnotation to comply with the naming in the domain storytelling book.
There could even be an annotate() one day replacing the $note parameter on actors and objects.

Regarding "4. message flow modelling" I'm currently not too familiar with the method but could envision some kind of library extension with the necessary macros to describe those messages.
Currently, I'm not sure how to describe those rectangles as an arrow label.

As you noticed I'm already working on an append macro.
Unfortunately, that will still take some time as apparently I'm the king of side quests, and now I'm adding a script to automatically rewrite the diagram descriptions.

Regarding the "simplified notation of object (message) properties" I've introduced the following definitions inspired by EDIFACT

!global $DST_PUML_ELEMENT_SEPARATOR ?= "+"
!global $DST_PUML_COMPONENT_SEPARATOR ?= ":"

Maybe those could be used to describe the rows and columns.

[kirchsth]

Hi @johthor,

thank you for reading.

at 1) a separate mode is perfect.
You are right it is not a typical/starting use case that objects are reused but if we start with a more detailed planning it could be useful

at 2) thank you
at 3) annotation is the much better term, thank you

at 4)
I wouldn't add the description to the arrows, the first image was only a picture which I found in the original article (based on your comment the "content of each message in a separate box next to each message" would be the better sample). I would still remain with the "standard" notation: The object gets a more detailed annotation (like in the "egon.io" sample).
For me, only the simplified property/table definition was missing.

at json/yaml) I like your short notations and with json/yaml it is not so compact anymore. I would offer it only as an additional option.

[johthor]

Hi again, I just discovered yet another way to use notes.

note on link
Message properties go here
end note

Which will add a note to the last created arrow and works inside the current code. That should allow for the original message flow notation.