Rational Team Concert Workflow Visualiser

Overview

Example workflow diagram Workflow Visualiser is a tool that takes the RTC process configuration XML and exports graphical representation of the workflows included in the configuration.

Motivation

The most typical task I'm facing at new RTC deployments is analysis of their workflow and its implementation in RTC. The usual procedure is:

  1. Meet with the customer to try to understand the workflow (states, transitions)
  2. Draw the workflow in Microsoft Visio and discuss the Visio files with customer
  3. Implement the workflow in RTC

This would be all great it there wasn't number 4 – implement the changes the customer finds after the implementation in RTC, which usually repeats several times. In this moment the Visio diagrams and the RTC implementation get out of sync and it is not easy to keep them synchronized. Workflow Visualiser helps in this step as I can export the real diagram and either send it to the customer for review or redraw it in Visio.

Another case in which this tool comes handy are big workflows (with 10< states). Although the transition table in RTC workflow designer is straightforward, checking such a workflow is not an easy task. Seeing a graphical representation of the workflow makes it clear.

Running the program

The program has to be invoked from command line and the command line arguments are:

Usage: java -jar visualiser.jar [options] source-xml-file
 Options:
  -h|--help Print help and exit
  --version Print help and exit
  -d|--dot Location of dot executable (defaults to /usr/bin/dot)
  -o|--out Output directory (defaults to /tmp/)
  -f|--format Output format (see the output formats of dot) (defaults to pdf)
  -s|--source Save the DOT source file in the output directory

Examples

Windows example PDF
  • JAR stored in C:\visualiser.jar
  • Process XML configuration file saved in process.xml
  • Graphviz installed in standard location
  • Export diagrams in PDF format to „C:\temp“
java -jar "C:\visualiser.jar" -o "C:\temp" -d "C:\Program Files\Graphviz2.26.3\bin\dot.exe" process.xml

Windows example PNG
  • JAR stored in C:\visualiser.jar
  • Process XML configuration file saved in process.xml
  • Graphviz installed in standard location
  • Export diagrams in PNG format to „C:\temp“
java -jar "C:\visualiser.jar" -o "C:\temp" -d "C:\Program Files\Graphviz2.26.3\bin\dot.exe" -f png process.xml

Linux example
  • JAR stored in ~/visualiser.jar
  • Process XML configuration file saved in process.xml
  • Graphviz installed in standard location (/usr/bin/dot)
  • Export diagrams in PDF format to ~/diagrams
java -jar ~/visualiser.jar -o ~/diagrams process.xml
Download

Download

Prerequisites

The program uses Graphviz for diagram drawing. You must have Graphviz installed on your computer to be able to run the program. It can be freely downloaded from http://www.graphviz.org/Download.php

Binary

Download Runnable JAR

Source code

Source code is available at GitHub: https://github.com/…w-visualiser. It includes pom.xml with the Maven project dependencies.

License

Pro program is distributed under Apache License, Version 2.0. For the license agreement of the used libraries see the appropriate license agreement included in the distribution.

Version history

  • 2010–04–09 Initial version
  • 2010–04–09.2 Resolution edges corrected

Comments, bug reports

Any comments or bug reports are welcome. Send them either in the comments under this article or via email to honza@stastnarodina.com

Tags: ,

23 Responses to “Rational Team Concert Workflow Visualiser”

  1. Robert says:

    Very cool!

  2. Russell says:

    Thanks a great utility. It works flawlessly

  3. Randy Haven says:

    Can you output in a format consumable by RSA? Not sure what the resource format is, probably an OMG UML standard.

  4. honza says:

    Randy,
    the tool supports formats exported by Graphviz. To see list of them, go to http://www.graphviz.org/…/output.html. The front page of graphviz http://www.graphviz.org/ also mentions GXL format. Maybe that could be a starting point for you.

  5. Jirong Hu says:

    Hi

    I am able to generate the pdf files for Simple and Traditional process template, but failed in Scrum one (process.xml is from the sample JUnit project). Here is the error:

    C:\build>java -jar „C:\build\visu­aliser.jar“ -o „V:\HOST_C\Ji­rong\Youth2011\RTC\W­ork Item\Workflow\S
    rum“ -d „C:\Program Files\Graphviz 2.28\bin\dot.exe“ Srum_process.xml
    com.sun.org.a­pache.xerces.in­ternal.impl.i­o.MalformedBy­teSequenceExcep­tion: Invalid byte 1 of 1-byte
    UTF-8 sequence.
    at com.sun.org.a­pache.xerces.in­ternal.impl.i­o.UTF8Reader.in­validByte(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.i­o.UTF8Reader.re­ad(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.XMLEn­tityScanner.lo­ad(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.XMLEn­tityScanner.pe­ekChar(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.XMLDo­cumentFragmen­tScannerImpl$Frag­mentContentDri
    ver.next(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.XMLDo­cumentScannerIm­pl.next(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.impl.XMLDo­cumentFragmen­tScannerImpl.scan­Document(Unkno
    wn Source)
    at com.sun.org.a­pache.xerces.in­ternal.parser­s.XML11Configu­ration.parse(Un­known Source)
    at com.sun.org.a­pache.xerces.in­ternal.parser­s.XML11Configu­ration.parse(Un­known Source)
    at com.sun.org.a­pache.xerces.in­ternal.parser­s.XMLParser.par­se(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.parser­s.DOMParser.par­se(Unknown Source)
    at com.sun.org.a­pache.xerces.in­ternal.jaxp.Do­cumentBuilderIm­pl.parse(Unknown Source)
    at javax.xml.par­sers.DocumentBu­ilder.parse(Un­known Source)
    at com.stastnaro­dina.workflow­Visualiser.Par­ser.parse(Par­ser.java:32)
    at com.stastnaro­dina.workflow­Visualiser.Ma­in.main(Main.ja­va:46)

    C:\build>


    <!--
    Copyright © 2007–2009 IBM Corporation. All rights reserved.
    This file is part of a process template created for use with the Jazz Process Framework.
    Your use of the process template (and hence this file) is subject to the following terms and conditions found in the process attachment named process_templa­te_license.html.
    -->

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚/${scope-path}‘

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Zoom
    false

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚/${scope-path}‘

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    '' <!-- All -->

    Zoom
    false

    Jazz
    http://jazz.net
    2
    technology
    Jazz platform community site

    3

    com.ibm.team.wor­kitem.queries­.predefined.my­Open
    com.ibm.team.wor­kitem.queries­.predefined.my­OpenCurrent
    com.ibm.team.wor­kitem.queries­.predefined.o­penCreated
    com.ibm.team.wor­kitem.queries­.predefined.o­penSubscribed
    com.ibm.team.wor­kitem.queries­.predefined.pen­dingApprovals

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚{My Team Areas}‘

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Zoom
    false

    Jazz
    http://jazz.net
    2
    technology
    Jazz platform community site

    3

    com.ibm.team.wor­kitem.queries­.predefined.my­Open
    com.ibm.team.wor­kitem.queries­.predefined.my­OpenCurrent
    com.ibm.team.wor­kitem.queries­.predefined.o­penCreated
    com.ibm.team.wor­kitem.queries­.predefined.o­penSubscribed
    com.ibm.team.wor­kitem.queries­.predefined.pen­dingApprovals

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚{My Team Areas}‘

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Zoom
    false

    Jazz
    http://jazz.net
    2
    technology
    Jazz platform community site

    3

    com.ibm.team.wor­kitem.queries­.predefined.my­Open
    com.ibm.team.wor­kitem.queries­.predefined.my­OpenCurrent
    com.ibm.team.wor­kitem.queries­.predefined.o­penCreated
    com.ibm.team.wor­kitem.queries­.predefined.o­penSubscribed
    com.ibm.team.wor­kitem.queries­.predefined.pen­dingApprovals

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚{My Team Areas}‘

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Zoom
    false

    <!-- Project -->

    Release
     
    0

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ''

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ''

    Zoom
    false

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ''

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ''

    Zoom
    false

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ''

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ''

    Zoom
    false

    com.ibm.team.pro­cess.scrum.bloc­ked
    com.ibm.team.wor­kitem.queries­.predefined.re­centlyModified
    com.ibm.team.wor­kitem.queries­.predefined.re­centlyClosed

    Current Sprint
     
    0

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ''

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Zoom
    false

    Details
    ‚2‘

    ProjectAreaName
    ‚{Current Project Area}‘

    TeamAreaName
    ‚{My Team Areas}‘

    Category
    ''

    ProjectAreaName1
    ‚{Current Project Area}‘

    Interval
    ‚{Current Iteration}‘

    Severity
    ''

    Type
    ''

    Zoom
    false

    Thanks
    Jirong

  6. honza says:

    Hi Jirong,
    thanks for the comment. It seems that the XML parser does not like some character in you process template XML file. Could you, please, send me the xml file to honza@stastnarodina.com, as the XML got corrupted in your post.
    Regards,
    Jan

  7. russell norlund says:

    Hi Honza, when I try to run the visualiser tool on Windows 2008 I get the following error message:

    Any Ideas?

    C:\Users\$rnor­lund\Documents>rtcvi­sualiser.bat

    C:\Users\$rnor­lund\Documents>C:\Tem­p\Java\bin\ja­va -jar „C:\Temp\visu­aliser.jar“
    -o „c:\Temp“ -d „C:\Program Files (x86)\Graphviz 2.28\bin\dot.exe“ process.xml

    java.io.IOExcep­tion: Cannot run program „C:\Program Files (x86)\Graphviz 2.28\bi
    n\dot.exe“: CreateProcess error=14001, The application has failed to start becau
    se its side-by-side configuration is incorrect. Please see the application event
    log or use the command-line sxstrace.exe tool for more detail
    at java.lang.Pro­cessBuilder.star­t(Unknown Source)
    at java.lang.Run­time.exec(Unknown Source)
    at java.lang.Run­time.exec(Unknown Source)
    at com.stastnaro­dina.workflow­Visualiser.Ma­in.main(Main.ja­va:62)
    Caused by: java.io.IOExcep­tion: CreateProcess error=14001, The application has f
    ailed to start because its side-by-side configuration is incorrect. Please see t
    he application event log or use the command-line sxstrace.exe tool for more deta
    il
    at java.lang.Pro­cessImpl.crea­te(Native Method)
    at java.lang.Pro­cessImpl.(Unknown Source)
    at java.lang.Pro­cessImpl.star­t(Unknown Source)
    … 4 more

    Kind Regards

    Russell

  8. Steve says:

    Great tool. I use this a lot.
    Since you are parsing through the source, would it be possible to identify which Roles can advance the workflow to the next workflow state ?

  9. honza says:

    Hi Steve,

    it should be technically possible, but I don't plan to implement it now, because I don't design workflows as much as I did in the past anymore.

    As it is an open source software (Apache License), you are free to do any changes. I would appreciate if you publish your altered code back for everybody to use.

    Regards,
    Jan

  10. Devika says:

    I am getting same error as Russell Norlund. Any guidance would be very helpful. Thank you.

    Error details:
    08/11/2011 12:10:15:049 ERMServer: Failed to query Graphviz version information

    08/11/2011 12:10:15:049 ERMServer: with: D:\Program Files (x86)\emailto­pia\Response Manager\Server\­..\Graphviz2.28\bin\dot -V

    08/11/2011 12:10:15:050 ERMServer: java.io.IOExcep­tion: Cannot run program „D:\Program Files (x86)\emailto­pia\Response Manager\Server\­..\Graphviz2.28\bin\dot“: CreateProcess error=14001, The application has failed to start because its side-by-side configuration is incorrect. Please see the application event log or use the command-line sxstrace.exe tool for more detail

    08/11/2011 12:10:18:131 ERMServer:

    08/11/2011 12:10:18:131 ERMServer: Warning: Failed to run dot.

    08/11/2011 12:10:18:131 ERMServer: Download dot version 2.2.1 or versions greater than 2.4

    08/11/2011 12:10:18:131 ERMServer: from http://www.graphviz.org and make sure that dot is either in your path

    08/11/2011 12:10:18:131 ERMServer: or point to where you installed Graphviz with the -gv option.

    08/11/2011 12:10:18:131 ERMServer: Generated pages will not contain a diagramtic view of table

  11. honza says:

    Hello Devika,

    I don't know how to fix this as I don't have access to any Windows 2008 machine.

    Googling revealed this answer: http://answers.microsoft.com/…465e18e3f3ef Try it.

    In general it seems that there is a problem with running graphviz. To troubleshoot this, try to run graphviz directly. I guess you will get the same error.

    Regards,
    Jan

  12. Bruno Braga says:

    Good job!
    I'm an IBMer (RTC regional mentor).
    My customers said: THANK YOU

  13. Sam says:

    Hi,

    Need help in debugging message output. Here is the command that I am running „java -jar "visualiser.jar“ -o „C:\tmp\“ -d „C:\Graphviz2­.28\bin\dot.e­xe“ c:\tmp\proces­s.xml", yet the output states that „The input file has to be set“. What am I missing?

    Thanks,
    Sam

  14. honza says:

    Hi Sam,
    this is weird. It seems like the command line arguments parser failed to detect the last argument (path to the XML). The only think I can advise is to download the source and try to debug it there.
    You may also try to enclose the last argument in quotes.
    Rgds,
    Jan

  15. Russell says:

    If you get the following xml error

    Invalid byte 1 of 1-byte UTF-8 sequence.

    try this:

    If you paste the process content into notepad:

    1. turn word-wrap off
    2. save the file with UTF-8 encoding
  16. xni says:

    Great Jan, it's simply fantastic !

    Many thanks
    andrea

  17. Mayur Gupta says:

    Great Utility. Thanks it saved lot of time.

  18. Jirong Hu says:

    Sorry to get back to you so late. Today I opened the xml file in XMLPad and XMLPad automatically corrected the issue, I guess. Then I can generate the work flow files with no issue.

    I copied the process.xml file from within RTC eclipse client GUI.

    Thanks
    Jirong

  19. Kevin JC says:

    Absolutely brilliant! This works like a charm with RTC 4.0.1. It has saved me hours of monkeying in Visio. The fact that the resolutions are shown is incredibly helpful.

    Thanks.

    kjc

  20. Victoria Martinez Torino says:

    Nice and helpful utility!! I worked perfectly with RTC 4.0.2.
    Thanks!

  21. Kevin JC says:

    Works for RTC 4.0.04 M2.

  22. samd says:

    I have a complex defect workflow. he default output shows all the resoution codes. is there a way NOT to include them?

    also, is there a way to specify the start node and where it shoud be on the output page?

    drawn manually this isn't that hard, but the pdf is really busy

  23. honza says:

    Hello Samd,

    not including the resolution codes would require a change in the code. However, this should be a rather small change (just filtering out the nodes you don't want to include).

    As the project is now available on GitHub, I suggest you fork my repository: https://github.com/…w-visualiser and send a pull request if you want to share this with others.

    Regards.

Leave a Reply