plantuml
Audit
- Macro ID
- plantuml
- Source
- PlantUML Macro
- Type
- Generator
- Classification reason
- The content is the diagram source, a data source for the image the macro generates from it, through a PlantUML server.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-20
- Auditor
- Compared macros
- chart jira
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | OK | "PlantUML" is the name of the technology the macro draws with, the word users of diagrams-as-text search for, so it is recorded OK like html. |
| D2 summary | OK | the description, "Convert various text input formats into diagram images using PlantUML.", says what the macro produces, but "text input formats" is vague where it means the PlantUML text language and its sibling languages, and "images" leaves out the svg and txt outputs. It does not repeat the name alone, so it is recorded OK. |
| D3 category | OK | in Content only, like chart, chartjs and jira, the other generators that draw from data or text. The Diagram macros of the Diagram Application have no category. |
| D4 quick-action | OK | Quick Actions finds the macro first for "plantuml" and "PlantUML", 2nd for "uml" (after sequence) and 6th of 6 for "diagram", the last. The synonyms "sequence diagram", "class diagram" and "puml" give no PlantUML entry. The French and German names are "PlantUML", as in English, a technology name that is not translated. A macro named after its technology is OK even when few synonyms find it, like html. Synonyms used: uml, diagram, sequence diagram, class diagram, puml. |
| L1 consistency | OK | compared with chart and jira, two generators of the Content category that draw output from text. Like jira, plantuml requires its content, the diagram source, so Quick Actions opens the Edit Macro dialog instead of inserting the macro right away, which is by design since an empty diagram means nothing. |
| L2 doc-parameters | KO | the parameters are only documented on the legacy extensions.xwiki.org page, not in the new documentation, see the Documentation status page. That page does not list the content in its parameter table, and its defaults do not match the dialog: format is "png unless configured in xwiki.properties" where the select opens blank, see C3 of format, and type is "Defined in the content" where the select opens on plantuml. |
| L3 doc-example | OK | the most common example is the Use Case Diagram, {{plantuml}} @startuml :Customer: -> (Withdraw) note right of (Withdraw) : This is an example. @enduml {{/plantuml}} , the first example of the documentation that is not a template with placeholder text. On a fresh XWiki it renders "Failed to execute the PlantUML macro. Cause: [The PlantUML Server URL [http://www.plantuml.com/plantuml] is not in the list of trusted domains.]", as do all 7 examples, since the default server is not trusted. The documentation does state the setup step: its Configuration section says "The PlantUML server domain needs to be added to the trusted domains list, for security reasons" under a 2.4.1+ label. It is recorded OK since a setup step the documentation states is OK, with this weakness: the step follows the sentence "It works out of the box with all the different kinds of diagrams, using the PlantUML server available on the internet", which is no longer true, it does not say where the list is, and it is far from the examples, which carry no warning. |
| I1 pattern | OK | Quick Actions and the Insert Macro dialog both open the Edit Macro dialog, since the content is mandatory. This is the generic behavior of a macro with a mandatory parameter, OK like include and jira. |
| I2 zero-config | OK | submitting the Edit Macro dialog with the default values does nothing, with no message, since the content is required: the generic behavior of the dialog. {{plantuml/}} renders, in view mode, "Failed to execute the [plantuml] macro. Cause: [Cannot invoke "String.trim()" because "content" is null]", a Java message counted under E2. |
| I3 instant | N/A | |
| I4 cursor | N/A | |
| I5 focus | OK | the content, the only mandatory parameter, comes first and has the focus. The server is not essential for the dialog since a default one is configured on the wiki, see C3 of server. |
| E1 wysiwyg | KO | the editor never shows the diagram. Right after the insertion it shows the generic placeholder "macro:plantuml", and after saving and reopening the page it shows the rendering error, here the trusted-domains one, never a placeholder that says what the macro draws. The macro renders asynchronously, see PlantUMLMacro.java. No diagram could be rendered on this instance, so the editor of a configured wiki was not seen. To reproduce: insert the macro from Quick Actions with the most common example, then save and edit the page again. |
| E2 errors | KO | a missing content and an invalid server give a Java message. {{plantuml/}} gives "Cannot invoke "String.trim()" because "content" is null", {{plantuml server="abc"}}@startuml A -> B @enduml{{/plantuml}} gives "no protocol: abc", and server="" gives "no protocol: ", with the cause "Invalid PlantUML Server URL" only in the details. The values of format and type are rejected at parsing with a clear message that lists the allowed values, and wrong case is accepted, as declared. The trusted-domains message is clear but does not say where the list is. |
| E3 nesting | OK | in a list item, a table cell and a box the macro stays in place, with the same trusted-domains error as in the page body, and the editor shows the placeholder inside them. The content is diagram source typed in a dialog text area, so a list, a table or a box in it does not apply. No diagram could be rendered, so the real output was not seen in these cases. |
| E4 inline-support | OK | the macro declares inline support. In a sentence it renders the same error box, inside the sentence, with no other change. No diagram could be rendered, so the inline result of an image was not seen. |
| E5 empty | N/A | |
| E6 inplace | N/A |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | KO | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: "The textual definition of the diagram" does not say what to type: the PlantUML language, which the macro wraps in @startuml and @enduml when the content does not start with that tag, or the other supported languages. A user who does not know PlantUML finds nothing in the dialog, nor a link to its language reference. To reproduce: open the Edit Macro dialog from Quick Actions. C2: mandatory, which is right, an empty diagram means nothing. C4: a plain text area in the Edit Macro dialog for the source of the diagram, like the script macros. C6: the content comes first, before the optional parameters. |
| format | KO | OK | KO | OK | OK | OK | N/A | OK | OK | OK | C1, minor: "the PlantUML diagram output format" does not say what each value is for, which the documentation does, svg scaling better and carrying links, and it does not say what the blank option stands for, see C3. C3: the select opens blank, which hides the value it stands for: the documentation says png, unless plantuml.format is set in xwiki.properties. Png is the usual value, so the select could show it, or say that blank is the wiki setting. C4: a select of svg, png and txt. C6: first of the optional parameters, and not set by the most common example. |
| server | KO | OK | OK | OK | OK | OK | N/A | KO | OK | KO | C1, minor: "the PlantUML Server URL" does not say that an empty value uses the server configured for the wiki, nor that its domain must be in the trusted domains list of the wiki. The documentation also says that an empty server="" forces the embedded mode when a server is set in the administration, which a blank field cannot express. C3: the field opens empty, which stands for the server configured for the wiki, in xwiki.properties or the PlantUML Administration Application, like the icon set of displayIcon. On a fresh wiki that server is the one of plantuml.com, not trusted: see L3. C4: a text field for a URL. C8: a rarely used parameter, since the server is a setting of the wiki, not marked advanced. Moving it to an advanced tab would keep it out of the way of the user. C13: a URL with no declared format: server="abc" is accepted by the dialog and fails at rendering with "no protocol: abc", see E2. A domain that is not trusted is only refused at rendering too. |
| title | OK | OK | OK | OK | OK | OK | N/A | OK | OK | N/A | C1: "the diagram title" says what it sets. It does not say that a title line in the content wins over the parameter, which the documentation states. C3: the field opens empty, for no title, a sensible default. |
| type | KO | OK | OK | OK | OK | OK | N/A | KO | OK | OK | C1, minor: "the type of diagram" does not say that the parameter only matters when the content has no @start tag, which the documentation states, and the values, like dot, jcckit or ebnf, are names of PlantUML engines that mean nothing to most users. C3: the select preselects plantuml, the most used type, so it is OK. The documentation says "Defined in the content" where the macro declares plantuml, see L2. C4: a select of the 13 types. C8, minor: the content of nearly every diagram starts with its @start tag, which sets the type, so the parameter is rarely needed, but it is documented and realistic for content without a tag, so it is not hidden. |
Other notes
The name, description and parameter texts are not translated: in French and German only the name and label of the content and the group name are, and the parameter names are their IDs, see the notes of the parameters.
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| L2 | L2 doc-parameters | XINFRA-525 | |
| E1 | E1 wysiwyg | XWIKI-23947 | |
| E2 | E2 errors | XCOMMONS-3847 (partial), XRENDERING-823 (partial), PLANTUML-37 (partial) | |
| C1:$content | C1 clarity, $content | PLANTUML-35 | |
| C1:format | C1 clarity, format | PLANTUML-35 | |
| C3:format | C3 defaults, format | XWIKI-23759 (partial) | PLANTUML-36 (partial) |
| C1:server | C1 clarity, server | PLANTUML-35 | |
| C8:server | C8 advanced, server | PLANTUML-36 | |
| C13:server | C13 constraints, server | PLANTUML-37 | |
| C1:type | C1 clarity, type | PLANTUML-35 | |
| C8:type | C8 advanced, type | PLANTUML-36 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-23759 | Existing | C3:format | |
| XWIKI-23947 | Existing | E1 | |
| XCOMMONS-3847 | New | E2 | |
| XRENDERING-823 | New | E2 | |
| PLANTUML-35 | New | C1:$content C1:format C1:server C1:type | |
| PLANTUML-36 | New | C8:server C8:type | C3:format |
| XINFRA-525 | New | L2 | |
| PLANTUML-37 | New | C13:server | E2 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
