Export to C4-PlantUML: External persons rendered as internal persons

[dirkgroot]

When I export diagrams from my Structurizr DSL model to C4-PlantUML, external persons are rendered as internal persons. For example:

I expect the external person to be rendered in a gray color, rather than a blue color.

Reproduction scenario

Given this workspace:

workspace {
    model {
        enterprise "Customer" {
            person_internal = person "Internal user"
            system = softwareSystem "Test system"
        }

        person_external = person "External user"

        person_internal -> system "Uses"
        person_external -> system "Uses"
    }
    views {
        systemContext system {
            include *
        }
    }
}

When I export the system context diagram to C4-PlantUML, this PUML file is generated:

@startuml
title Test system - System Context

top to bottom direction

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

Enterprise_Boundary(enterprise, "Customer") {
  Person(Internaluser, "Internal user", "", $tags="Element+Person")
  System(Testsystem, "Test system", "", $tags="Element+Software System")
}

Person_Ext(Externaluser, "External user", "", $tags="Element+Person")

Rel_D(Internaluser, Testsystem, "Uses", $tags="Relationship")
Rel_D(Externaluser, Testsystem, "Uses", $tags="Relationship")

SHOW_LEGEND()
@enduml

Resulting in the above image.

Cause

This is caused by the Person tag that's being assigned to the Person_Ext element in the PUML file. When this tag is replaced by Person_Ext or when it's omitted entirely then the external person is rendered correctly.

Before creating this issue, I double-checked whether or not this is intended behaviour for C4-PlantUML: plantuml-stdlib/C4-PlantUML#228.

Possible solutions

• Omit tags entirely in the generated PlantUML, and rely on the default rendering provided by C4-PlantUML. I'm not sure wether or not this will break the rendering of other elements.
• Make sure that external persons get the Person_Ext tag instead of the Person tag.

[kirchsth]

Possible solutions:

in plantuml-stdlib/C4-PlantUML#228 I found following problems

1. update/creates of the required tag definitions (based on the styles) in C4-PlantUML is missing.
2. add the tags in reverse order that the most detailed is the first one:
   first tag has the highest priority (e.g. if 2 styles/tags define a background color the first wins)
3. mark "External_xxx" with new "External_xxx" tags

Maybe additional changes could be done (or in another PR?):

4. activate SHOW_PERSON_OUTLINE()
   4a. and if description of the person is empty add \n\n or <25 char add \n to it that the y-dimension of the shape is higher. If required I could add the \n support in C4-PlantUML itself)

It could be that https://github.com/cloudflightio/structurizr-export-c4plantuml solves most of the problems already and only the PR has to be completed. @klu2: can you please check my assumption?

e.g. with all changes based on following DSL

workspace {
    model {
        enterprise "Customer" {
            dwh_user = person "DWH User" "User of some DWH" "Internal user"
            dwh_developer = person "DWH Developer" "Developer of some DWH" 
        }

        dhw_user = person "DHW User" "User of DataHandwerk Toolkit" "External user"
        // "External_Person" is only used as workaround atm
        dhw_developer = person "DHW Developer" "Developer of DataHandwerk Toolkit" "External_Person"       
    }
    views {
        systemlandscape "SystemLandscape" {
             include *
             autoLayout
        }
        styles {
            element "Person" {
                shape Person
                background #2222CC
            }
            element "External_Person" {
                shape Person
                background #FFCCCC
            }            
            element "Internal user" {
                shape Person
                background #4444FF
            }
            element "External user" {
                shape Person
                background #FF4444
            }            
        }
    }
}

with the new rules the generator would create something like

@startuml
title System Landscape for Customer

top to bottom direction

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

' additional changes: 4. activate person outline
SHOW_PERSON_OUTLINE()

' additional changes: 1. update existing tags/styles if required
UpdateElementStyle("person", #2222CC, $ELEMENT_FONT_COLOR)
' additional changes: if SHOW_PERSON_OUTLINE() is not used, structurizr sprite could be used too
UpdateElementStyle("external_person", #FFCCCC, $ELEMENT_FONT_COLOR, $sprite="person2")
' additional changes: 1. create new tags/styles if required
AddElementTag("Internal user", "#4444FF", $ELEMENT_FONT_COLOR)
AddElementTag("External user", "#FF4444", $ELEMENT_FONT_COLOR, $sprite="person2")

Enterprise_Boundary(enterprise, "Customer") {
  ' additional changes: 2. invert tag order that most detailed tag wins
  ' additional changes: (as workaround) 4a. add \n
  Person(DWHUser, "DWH User", "Userof some DWH\n", $tags="Internal user+Person+Element")
  Person(DWHDeveloper, "DWH Developer", "Developer of some DWH\n", $tags="Person+Element")
}

' additional changes: 2. invert tag order that most detailed tag wins
' additional changes: 3. use External_Person instead of Person
Person_Ext(DHWDeveloper, "DHW Developer", "Developer of DataHandwerk Toolkit", $tags="External_Person+Element")
Person_Ext(DHWUser, "DHW User", "User of DataHandwerk Toolkit", $tags="External user+External_Person+Element")

SHOW_LEGEND()
@enduml

@simonbrowndotje: can you accept klu2 PR if everything is working?

Thank you and best regards
Helmut

[dirkgroot]

I've been fiddling around with this, and the simplest fixes seem to be to just prefix the $tags for a person with External_Person, or to not use the tags at all and rely on C4-PlantUML defaults.

@kirchsth Customisation using UpdateElementStyle and/or the usage of tags is not necessary if you just want to use the default styling provided by C4-PlantUML, right?

@simonbrowndotje I'm curious: Could you clarify what your purpose is with putting Structurizr tags in the PlantUML files?

[kirchsth]

Hi @dirkgroot

yes, it works without UpdateElementStyle() too (maybe an export option could be useful)

(but if you want the same structurizr colors, ... then you can use it;
and if you use additional styles/tags in DSL you get automatically matching colors too)

BR Helmut

[simonbrowndotje]

I'm curious: Could you clarify what your purpose is with putting Structurizr tags in the PlantUML files?

It was a response to this issue -> structurizr/java-extensions#51