## Rational Team Concert Workflow Visualiser

### Overview

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

#### 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

#### Source code

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

### Version history

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

Tags: ,

### 27 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.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.

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.

24. samd says:

thanks.. will add that to my list of things to do.

25. jasonm says:

Hi Honza – would it be possible to grab the executable visualizer.jar somewhere? When I click the link above, it steps me through a web domain/Wix connection page.

I tried downloading the source and built it with mvn clean install, but that didn't create the executable.

Thanks!

26. honza says:

Hi Jason,