Monday, September 22, 2014

Tool: SMART Documentation & Conversion 2.0 Helper For Orchestrator Runbooks

Update, 09-22-2014
Based on this posting I got feedback from Bruno Saille, the Program Manager who’s responsible for this tooling (among other things). I’ve decided to incorporate his feedback in blue. Thanks Bruno for your feedback, awesome!

Already some months ago Microsoft released an updated version their tool to document your Orchestrator  Runbooks, Orchestrator Visio and Word Generator.

However, as it turns out, this is just more than an update of the tool since it incorporates an update of the tool SMART Runbook Conversion Helper as well. This results in the tool SMART Documentation and Conversion Helper 2.0.

The tool itself – with a long description about how to use it with some good examples – can be found here.

So far, so good. But since I’ve used this tool I want to share some of my personal experiences:

  1. Icons please?
    Bumped into it just once. Visio and Word output ended up without icons, even though the export PS script for Runbook icons (this is a 32 bits PS script!) had run successfully and all icon files (jpeg) were present in the same folder the script was run from. Only fix for me was to remove all the icon files, rerun the export PS script for Runbook icons again. Afterwards Visio and Word output had icons again. Don’t know whether this was a one time glitch.

  2. Output to Word is dead slow
    On a well dimensioned server it took a long time to convert some Runbooks to Word format, especially compared to the conversion to Visio. Something which I couldn’t solve and just had to ride it out.

    Feedback from Bruno Saille, Microsoft PM responsible for this software: ‘…Yes, Word output is unfortunately slow, and this is due to how PowerShell works with COM automation. The same code used to be much faster in .NET, and the Visio automation code is not slower with PowerShell. Good thing is that WMF 5.0 is supposed to have a few enhancements in COM automation speed, so this may help (I have not had a chance to give it a good try)…’

  3. Running multiple PS instances on the same computer doesn’t work for conversion to Word
    Tried to run two PS instances in order to make the conversion go faster. For Visio and PS this works great, but when converting Runbooks to Word documents, it doesn’t work. Somehow the document gets corrupted and only the last line is kept. The rest is overwritten by newer output of the conversion. No title, no table. Just a single line of text.

  4. Configure Visio before you start the conversion
    Visio needs some additional configuration before you start your first conversion to it. In my case Visio was installed on the D:\ drive, so I had to modify the path referring to a specific Visio startup file.

  5. Be patient
    The tool works, but has some quirks, one of them is lacking speed. Also when you click something, sometimes there will be a lag. Just be patient and wait. Until now the tool didn’t crash on me which is far more unwelcome.

  6. Placement of the tool window
    When running the tool and starting a conversion (especially to Word), don’t forget to place the window of the tool to a place which doesn’t ‘eat away’ most of your screen. Because when a conversion is started, this windows can’t be dragged to another position. Just something to be aware off.

    Feedback from Bruno Saille, Microsoft PM responsible for this software: ‘…That is one of the limitation of doing this via a PowerShell XAML/WPF "GUI" : The tool will not give focus back until the processing has been finished. This is why we tried to add more extensive feedback in the console window at the same time, so you can confirm something is happening. You can move the console window around even when the GUI is "waiting". Adding multi-threading, etc. might be possible, but then it may bring more complexity than anything, vs a more "simple" PS script that you can modify to your needs…’

Besides this I am happy with the tool since it allows me to gain a good insight in an Orchestrator environment and more important, the Runbooks present. But don’t forget that this tool is the START of your journey in how the Runbooks are made, and not the end of it.

Having a cup of coffee with the persons who built the Runbooks provides tons of information as well, which can’t be captured by any tooling. But than of course, those people must be still around AND available…

No comments: