How to Dump Workflows

How to Dump Workflows

To help you debug your workflows, you can generate a visual representation of them as SVG or PNG images. First, install any of these free and open source applications needed to generate the images:

  • Graphviz, provides the dot command;
  • PlantUML, provides the plantuml.jar file (which requires Java).

If you are defining the workflow inside a Symfony application, run this command to dump it as an image:

  1. # using Graphviz's 'dot' and SVG images
  2. $ php bin/console workflow:dump workflow-name | dot -Tsvg -o graph.svg
  4. # using Graphviz's 'dot' and PNG images
  5. $ php bin/console workflow:dump workflow-name | dot -Tpng -o graph.png
  7. # using PlantUML's 'plantuml.jar'
  8. $ php bin/console workflow:dump workflow_name --dump-format=puml | java -jar plantuml.jar -p  > graph.png
  10. # highlight 'place1' and 'place2' in the dumped workflow
  11. $ php bin/console workflow:dump workflow-name place1 place2 | dot -Tsvg -o graph.svg

The DOT image will look like this:

../_images/blogpost.png

The PlantUML image will look like this:

../_images/blogpost_puml.png

If you are creating workflows outside of a Symfony application, use the GraphvizDumper or StateMachineGraphvizDumper class to create the DOT files and PlantUmlDumper to create the PlantUML files:

  1. // Add this code to a PHP script; for example: dump-graph.php
  2. $dumper = new GraphvizDumper();
  3. echo $dumper->dump($definition);
  5. # if you prefer PlantUML, use this code:
  6. # $dumper = new PlantUmlDumper();
  7. # echo $dumper->dump($definition);
  1. # replace 'dump-graph.php' by the name of your PHP script
  2. $ php dump-graph.php | dot -Tsvg -o graph.svg
  3. $ php dump-graph.php | java -jar plantuml.jar -p  > graph.png

Styling

You can use metadata with the following keys to style the workflow:

  • for places:
    • bg_color: a color;
    • description: a string that describes the state.
  • for transitions:
    • label: a string that replaces the name of the transition;
    • color: a color;
    • arrow_color: a color.

Strings can include \n characters to display the contents in multiple lines. Colors can be defined as:

Below is the configuration for the pull request state machine with styling added.

  • YAML

    1. # config/packages/workflow.yaml
    2. framework:
    3.     workflows:
    4.         pull_request:
    5.             type: 'state_machine'
    6.             marking_store:
    7.                 type: 'method'
    8.                 property: 'currentPlace'
    9.             supports:
    10.                 - App\Entity\PullRequest
    11.             initial_marking: start
    12.             places:
    13.                 start: ~
    14.                 coding: ~
    15.                 test: ~
    16.                 review:
    17.                     metadata:
    18.                         description: Human review
    19.                 merged: ~
    20.                 closed:
    21.                     metadata:
    22.                         bg_color: DeepSkyBlue
    23.             transitions:
    24.                 submit:
    25.                     from: start
    26.                     to: test
    27.                 update:
    28.                     from: [coding, test, review]
    29.                     to: test
    30.                     metadata:
    31.                         arrow_color: Turquoise
    32.                 wait_for_review:
    33.                     from: test
    34.                     to: review
    35.                     metadata:
    36.                         color: Orange
    37.                 request_change:
    38.                     from: review
    39.                     to: coding
    40.                 accept:
    41.                     from: review
    42.                     to: merged
    43.                     metadata:
    44.                         label: Accept PR
    45.                 reject:
    46.                     from: review
    47.                     to: closed
    48.                 reopen:
    49.                     from: closed
    50.                     to: review

  • XML

    1. <!-- config/packages/workflow.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xmlns:framework="http://symfony.com/schema/dic/symfony"
    6.     xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd
    7.         http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
    8. >
    10.     <framework:config>
    11.         <framework:workflow name="pull_request" type="state_machine">
    12.             <framework:marking-store>
    13.                 <framework:type>method</framework:type>
    14.                 <framework:property>currentPlace</framework:property>
    15.             </framework:marking-store>
    17.             <framework:support>App\Entity\PullRequest</framework:support>
    19.             <framework:initial_marking>start</framework:initial_marking>
    21.             <framework:place>start</framework:place>
    22.             <framework:place>coding</framework:place>
    23.             <framework:place>test</framework:place>
    24.             <framework:place name="review">
    25.                 <framework:metadata>
    26.                     <framework:description>Human review</framework:description>
    27.                 </framework:metadata>
    28.             </framework:place>
    29.             <framework:place>merged</framework:place>
    30.             <framework:place name="closed">
    31.                 <framework:metadata>
    32.                     <framework:bg_color>DeepSkyBlue</framework:bg_color>
    33.                 </framework:metadata>
    34.             </framework:place>
    36.             <framework:transition name="submit">
    37.                 <framework:from>start</framework:from>
    39.                 <framework:to>test</framework:to>
    40.             </framework:transition>
    42.             <framework:transition name="update">
    43.                 <framework:from>coding</framework:from>
    44.                 <framework:from>test</framework:from>
    45.                 <framework:from>review</framework:from>
    47.                 <framework:to>test</framework:to>
    49.                 <framework:metadata>
    50.                     <framework:arrow_color>Turquoise</framework:arrow_color>
    51.                 </framework:metadata>
    52.             </framework:transition>
    54.             <framework:transition name="wait_for_review">
    55.                 <framework:from>test</framework:from>
    57.                 <framework:to>review</framework:to>
    59.                 <framework:metadata>
    60.                     <framework:color>Orange</framework:color>
    61.                 </framework:metadata>
    62.             </framework:transition>
    64.             <framework:transition name="request_change">
    65.                 <framework:from>review</framework:from>
    67.                 <framework:to>coding</framework:to>
    68.             </framework:transition>
    70.             <framework:transition name="accept">
    71.                 <framework:from>review</framework:from>
    73.                 <framework:to>merged</framework:to>
    75.                 <framework:metadata>
    76.                     <framework:label>Accept PR</framework:label>
    77.                 </framework:metadata>
    78.             </framework:transition>
    80.             <framework:transition name="reject">
    81.                 <framework:from>review</framework:from>
    83.                 <framework:to>closed</framework:to>
    84.             </framework:transition>
    86.             <framework:transition name="reopen">
    87.                 <framework:from>closed</framework:from>
    89.                 <framework:to>review</framework:to>
    90.             </framework:transition>
    92.         </framework:workflow>
    94.     </framework:config>
    95. </container>

  • PHP

    1. // config/packages/workflow.php
    2. $container->loadFromExtension('framework', [
    3.     // ...
    4.     'workflows' => [
    5.         'pull_request' => [
    6.             'type' => 'state_machine',
    7.             'marking_store' => [
    8.                 'type' => 'method',
    9.                 'property' => 'currentPlace',
    10.             ],
    11.             'supports' => ['App\Entity\PullRequest'],
    12.             'initial_marking' => 'start',
    13.             'places' => [
    14.                 'start',
    15.                 'coding',
    16.                 'test',
    17.                 'review' => [
    18.                   'metadata' => [
    19.                       'description' => 'Human review',
    20.                   ],
    21.                 ],
    22.                 'merged',
    23.                 'closed' => [
    24.                   'metadata' => [
    25.                       'bg_color' => 'DeepSkyBlue',
    26.                   ],
    27.                 ],
    28.             ],
    29.             'transitions' => [
    30.                 'submit'=> [
    31.                     'from' => 'start',
    32.                     'to' => 'test',
    33.                 ],
    34.                 'update'=> [
    35.                     'from' => ['coding', 'test', 'review'],
    36.                     'to' => 'test',
    37.                     'metadata' => [
    38.                         'arrow_color' => 'Turquoise',
    39.                     ],
    40.                 ],
    41.                 'wait_for_review'=> [
    42.                     'from' => 'test',
    43.                     'to' => 'review',
    44.                     'metadata' => [
    45.                         'color' => 'Orange',
    46.                     ],
    47.                 ],
    48.                 'request_change'=> [
    49.                     'from' => 'review',
    50.                     'to' => 'coding',
    51.                 ],
    52.                 'accept'=> [
    53.                     'from' => 'review',
    54.                     'to' => 'merged',
    55.                     'metadata' => [
    56.                         'label' => 'Accept PR',
    57.                     ],
    58.                 ],
    59.                 'reject'=> [
    60.                     'from' => 'review',
    61.                     'to' => 'closed',
    62.                 ],
    63.                 'reopen'=> [
    64.                     'from' => 'start',
    65.                     'to' => 'review',
    66.                 ],
    67.             ],
    68.         ],
    69.     ],
    70. ]);

The PlantUML image will look like this:

../_images/pull_request_puml_styled.png

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.