"Existing" vs "External"

[hindsholm]

Hi, I just discovered this project and I am very happy to see C4 support in PlantUML being alive again 🙂
But there is one thing which puzzles me, and that is the inconsistency with c4model.com with regards to existing vs external.
On the C4 website gray elements indicate existing model elements, while external elements are indicated by system boundaries. See e.g. this legend:

However, in this library (and the previous ones from @RicardoNiepel and @adrianvlupu) gray is used to indicate external elements while there is no notation for distinguishing between existing and new elements.
Because of this inconsistency, we have made our own fork, but I would love to get rid of it and use this standard library instead.
So I would suggest adding support for showing existing elements like in the C4 documentation.

[kirchsth]

Hi,

with the last version you could simply solve it via an "existing" tag and then you can style it like below (or use the existing ..._Ext() elements as workaround).

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

AddTagSupport("existing",  $fontColor="black", $borderColor="black", $bgColor="#888888")

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
    Container(web_app_existig, "Web Application Existing", "C#, ASP.NET Core 2.1 MVC", "existing", $tags="existing")
    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
}
System(twitter, "Twitter")

Rel(admin, web_app, "Uses", "HTTPS")
Rel(web_app, twitter, "Gets tweets from", "HTTPS")

SHOW_DYNAMIC_LEGEND()
@enduml

BR Helmut

[hindsholm]

Hi @kirchsth

Thx a lot for the tip about the tag support. It looks very useful, and I will investigate it further.

However, I still don't understand why C4-PlantUML doesn't support "existing systems" out of the box.
Allow me to clarify 🙂

If you go to https://c4model.com/#coreDiagrams and click on the first "See example diagram, key, and narrative" button (sorry, it is not possible to link directly to the diagram), you see the basic Internet Bank model along with a text describing the colouring of existing systems and a legend:

If you instead go to the C4-PlantUML Core Diagrams page, you see the exact same diagram but with a different legend indicating that now two of the systems are external:

This is made even more confusing by the fact that one of the systems is described as "The internal Microsoft Exchange e-mail system." 🙂

I suggest adding support for existing systems (which is a very useful concept) to align C4-PlantUML with c4models.com.
Removing the current support for external systems could also be considered because they may easily be indicated by using boundaries.

[kirchsth]

Hi Hildsholm,

I think you are too strict. Even Structurizer ignores this detail and generate C4-Plantuml diagrams with this limitation.
Eg. you can see it on https://structurizr.com/json?example=big-bank-plc
And the colors of the diagram elements are not 100% the same (based on different meaning), you can check it with the "SystemLandscape view". The generated "Structuriz" diagrams has different compared with the generated "C4-PlantUML" based on the different meaning.

BR Helmut
PS.: and luckily, we have tags that you can define your missing existing systems too.

[simonbrowndotje]

I'm not involved in the development of this library, but I would like to say that the C4 model doesn't prescribe any particular notation, and "existing system" isn't a part of the semantics - it's just something that I added to that particular example.

"Internal" and "External" are also not a part of the C4 model, but it can certainly be useful to state which elements are "outside" a particular boundary (e.g. an organisation), which is why the Structurizr tooling natively supports internal/external. With the "Big Bank plc" example, all elements are marked as "internal", with the exception of the "Personal Banking Customer". That said though, the example diagrams on c4model.com don't differentiate that "external" person from a notation perspective, although the "Personal Banking Customer" is shown outside of the "enterprise" boundary.

If you take a look at the Structurizr DSL - Big Bank plc example and view the C4-PlantUML export, you'll notice that particular export does style the external person differently. (screenshot below).

It doesn't support "existing system" as a concept though. And I guess that's the real question here ... should C4-PlantUML support an "existing system" concept? I can't answer that, but if C4-PlantUML decides to support such a concept, what other concepts should it support natively, and what colours should be assigned to them? I went through the same line of thinking with the Structurizr tooling, which is how I ended up with the "tags and tagging" route (inspired by CSS) ... people can tag elements with their own custom semantics, and style them as desired.

[kirchsth]

Hi @hindsholm,
if you have only problems with the legend and use all external elements ..._Ext as "existing", you can define your own legend like below.
BR Helmut

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
' uncomment the following line and comment the first to use locally
' !include C4_Context.puml

' replace
' LAYOUT_WITH_LEGEND()
' with 
hide stereotype
legend right
|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
|<$PERSON_BG_COLOR> person |
|<$SYSTEM_BG_COLOR> system|
|<$EXTERNAL_SYSTEM_BG_COLOR> existing system |
endlegend

' activate structrizr person icon
SHOW_PERSON_SPRITE(person2)

title System Context diagram for Internet Banking System

Person(customer, "Personal Banking Customer", "A customer of the bank, with personal bank accounts.")
System(banking_system, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.")
System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP")
Rel(banking_system, mainframe, "Uses")
@enduml

[hindsholm]

Thank you @kirchsth and @simonbrowndotje for your helpful answers.

I guess I may have been a bit too strict in my interpretation of c4model.com. It's just that we have been very happy using C4 in our company for the last couple of years, and it is really spreading now because everyone immediately "gets it". And through all this work we have used the notion of existing vs. new systems (and containers) which we find extremely useful because almost all enterprise development is about building new features that must interact with existing systems. So we basically use "existing" all the time while we use boundaries to show external systems.

About a year ago I made a pull request to @adrianvlupu introducing "existing" elements. I was also unsuccessful at that time 🙂 so we ended up making our own fork of his fork of C4-PlantUML. In this fork we did a very crude search and replace from "external" to "existing", and it has been working fine for us. (We also changed the colors, but that is a minor issue). But of course we don't really want to have our own fork, we would much rather use - and contribute to - this common project.

I by no means an expert in the PlantUML language, but I can see that with the new structure of the code in this library, introducing new elements has become easier. And your helpful example @kirchsth led my into trying this:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

!global $EXISTING_SYSTEM_BG_COLOR = "#999999"
!global $EXISTING_SYSTEM_BORDER_COLOR = "#8A8A8A"

!unquoted procedure System_Existing($alias, $label, $descr="", $sprite="", $tags="")
rectangle "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("existing_system", $tags) as $alias
!endprocedure

UpdateSkinparamsAndLegendEntry("existing_system", $bgColor=$EXISTING_SYSTEM_BG_COLOR, $fontColor=$COLOR_NEUTRAL, $borderColor=$EXISTING_SYSTEM_BORDER_COLOR)

Person(customer, "Personal Banking Customer")
System(banking_system, "Internet Banking System")

System_Existing(mail_system, "E-mail system")
System_Existing(mainframe, "Mainframe Banking System")

Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails")
Rel(banking_system, mainframe, "Uses")

LAYOUT_WITH_LEGEND()
@enduml

This is actually what we want, except of course for the legend. Apparently PlantUML allows you to redefine procedures, so if I just add my own procedure:

!procedure LAYOUT_WITH_LEGEND()
hide stereotype
legend right
|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
|<$PERSON_BG_COLOR> person |
|<$SYSTEM_BG_COLOR> system|
|<$EXISTING_SYSTEM_BG_COLOR> existing system |
endlegend
!endprocedure

everything works. Of course it would be even better if the legend code allowed for customization, but I am not sure my PlantUML skills are sufficient for that 🙂

[kirchsth]

Hi @hindsholm,
if you add "External System" as new tag, you have a working (dynamic) legend too like below
BR Helmut
PS.: changed colors are supported too (you can see it in my first awnser with the black font and border) if you use SHOW_DYNAMIC_LEGEND().

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

' only color sample
!global $EXISTING_SYSTEM_BG_COLOR = "Green"
!global $EXISTING_SYSTEM_BORDER_COLOR = "#8A8A8A"

!unquoted procedure System_Existing($alias, $label, $descr="", $sprite="", $tags="")
rectangle "$getSystem($label, $descr, $sprite)$getProps()" $toStereos("existing_system", $tags) as $alias
!endprocedure

' define a new tag
' !!!! use AddTagSupport
AddTagSupport("existing_system", $bgColor=$EXISTING_SYSTEM_BG_COLOR, $fontColor=$ELEMENT_FONT_COLOR, $borderColor=$EXISTING_SYSTEM_BORDER_COLOR)

Person(customer, "Personal Banking Customer")
System(banking_system, "Internet Banking System")

System_Existing(mail_system, "E-mail system")
System_Existing(mainframe, "Mainframe Banking System")

Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails")
Rel(banking_system, mainframe, "Uses")


' !!!!! you need show dynamic legend
SHOW_DYNAMIC_LEGEND()
@enduml

[hindsholm]

Thank you @kirchsth for yet another helpful answer.
I think I can create a thin wrapper which will allow us to process our existing diagrams with stdlib C4-PlantUML and get rid of our old fork. At least I'll give it a try 🙂
I'll close this issue now.

[kirchsth]

Hi @hindsholm,
I finished my tag support of relations too. And during that I changed some function names.
If you want to update your part please check/use my (finished) extensions implementation until the changes are merged in this branch. (PR comes today or tomorrow)
Thank you and best regards
Helmut