Updated tool : SMART Documentation and Conversion Helper for your Orchestrator Runbooks

  • Articolo

Note: This tool is now included in a single package including all SMA Runbook Toolkit (SMART) tools. The download link has been updated below.

Hello Readers,

Some of you may be using the Orchestrator Visio and Word Generator today, to document your Orchestrator Runbooks. Some of you may also be using the SMART Runbook Conversion Helper, to help understand what your existring Orchestrator Runbooks would look like in Service Management automation (SMA). Understanding that both tools are being used by Orchestrator users, and that they both deal with an “export” capability to either Visio, Word, or PowerShell Workflows, it just made sense to merge the two.

So today I am releasing the SMART Documentation and Conversion Helper 2.0. Still fully written in PowerShell and based on the SMART Runbook Conversion Helper, this tool allows to:

  • Export an Orchestrator Runbook to Visio
  • Export an Orchestrator Runbook to Word
 This functionnality was previously in the Orchestrator Visio and Word Generator tool
  • Export an Orchestrator Runbook to PowerShell Workflow
 This functionnality was previously in the SMART Runbook Conversion Helper

Here is a screenshot of the updated user interface:

clip_image002

 

As an Orchestrator Visio and Word Generator user, you now get:
  • PowerShell Workflow export capabilites, which might be interesting as you get into SMA.
  • Updated Word export capabilities : It now leverages the same subroutines as the PowerShell Worfklow export, and is much more clean and detailed than the Word export in OVWG
  • Access to the script source : The Orchestrator Visio and Word Generator was based on .NET, the updated/new tool is now fully based on PowerShell. So it makes it easier to look at the source script, and update it for any issues or enhancements (e.g. update it to work with other versions of Visio/Word, add SQL Server authentication, export of a all runbooks in a folder, etc. – to list some of the requests I have seen). If you do make any updates and enhancements, please make sure you embrace the community spirit and share them back!
As a SMART Runbook Conversion Helper user, you now get:
  • Visio and Word export in the same interface

 

Download location

DownloadButton

How to use the tool

Note: As a prerequisite if you plan to use the Visio and Word exports, it is important to go through the image export process. This leverages a separate script also provided with the tool (SMART-DocumentationConversionHelper-ImageExport.ps1), more details can be found in the documentation file included in the download package.

  1. Launch the tool (SMART-DocumentationConversionHelper.ps1) by running it with PowerShell or the PowerShell ISE. The tool should be able to run on any machine, and without any parameters. By default, it will just time out if you do not have an Orchestrator DB locally (it defaults to localhost), and will give you the option to select another server in the user interface. You can also set the DB server via the command line (-DBServer switch), or in the script itself. Finally, the tool also remembers the last server used, thanks to a configuration file automatically saved/loaded. Yes, I copied and pasted this from the SMART Runbook Conversion Helper blog post, since this directly comes from this tool Smile 
  2. Select a Runbook. The tree view in the user interface is the same as in the Orchestator Runbook Designer. Runbooks are displayed in blue, folders are displayed in black.
  3. Select your export options – see more details below. Depending on Word 2013 and Visio 2013 being present, the option to export to Word and Visio will or will not be provided
  4. Just click “Export”!

More detailed instructions

These remain largely the same as the previous versions of the separate tools, and you can refer to the blog posts previously mentioned, as well as to the readme file included with the tool. Only change is related to Visio and Word export:

  • SMART Documentation and Conversion Help 2.0 assumes a default set of settings for Visio, and you can update them using the “Visio Settings…” button.
  • Since it is usually only done once at the beginning, or only very rarely after that, the Image Export process – that retrieves the thumbnails used in Orchestrator Runbooks to include them in Visio and Word exports – has been made separate in its own script (SMART-DocumentationConversionHelper-ImageExport.ps1). It just takes one parameter, which is the path to the Orchestrator extensions, and will present you with a user interfac to specifiy that path if it was not provided as a parameter. Since the thumbnails are stored in Orchestrator 32-bit DLLs, note that the Image Export script must be run with PowerShell 32-bit. The script will check for that and exit, if you run it in Powershell 64-bit.  This does not apply to the main script, which works with PowerShell 64-bit

Detailed requirements are in the readme file in the download package, but in a nutshell you will need a 64-bit machine with PowerShell 4.0 to run the tool, with Visio 2013 and Word 2013 if you wish to leverage this type of export.

Details on the different options in the user interface:

  • “Visio Settings…” allows you to view and update the settings specifics to Visio 2013. They are automatically saved in the same configuration file as the database server details, and reused when reopening the tool
  • “[Images Export]” counts the number of JPEG files in the same directory as the tool. At minimum, you should have one picture, the default one used by the tool when it cannot find the thumbnail for the activity type it is exporting to Visio or Word. Run the SMART-DocumentationConversionHelp-ImageExport.ps1 script to go through the export process at least once and populate the JPEG files.
  • Visio options : If “Save and Close” is checked, the VSDX file is saved to the local directory, instead of being kept open. By default it is not checked, so you can manipulate the diagram layout before saving it yourself. “Group Thumbnails” is checked by default and groups activities and thumbnails and activities for easy manipulation.
  • Word options : If “Save and Close” is checked, the DOCX file is saved to the local directory, instead of being kept open.
  • PowerShell options : If “Save and Close” is checked, the PS1 file is saved to the local directory, instead of opening ISE and leaving it open with the script. “Skeleton Only” mode is explained below.

Note : Options for Visio, Word and PowerShell are only available after checking the corresponding export box. For example, you will not be able to choose “Save and Close” for Word, if you have not select the “Export to Word” option.

When doing a PowerShell export, what is the difference between “Skeleton export” vs “Full export”?

  • Skeleton export : Basically, this is the structure of the source Runbook branches and conditions in a PowerShell Workflow syntax, with “workflow”, “param”, “parallel”, “sequence” and the potential “if” conditions.
  • Full export (default mode) : The same structure as “skeleton mode” is exported, but with details about all properties of all activities in the source Orchestrator Runbook. Specific parsing is done for Run .NET Script activities (including PowerShell), Initialize Data, Return Data, Schedules, Counters. For each properties, published data and variables are replaced by their actual display names (no GUIDs!), so you can easily relate to what they mean. At the bottom of the script, the tool provides a summary of variables, counters, schedules, initialize data activities, return data activities, loops, merging branches. That way, you have a list of items potentially worth investigating when porting your Runbook.

In closing – a few sample outputs

These should be the same as what you had in previous versions of the corresponding tools, except for the updated Word export.

Example 1

image

Orchestrator Runbook

image

Visio Export

image

Word Export

 

001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 ################################################################################# # WORKFLOW CREATED BY THE SMART DOCUMENTATION AND CONVERSION HELPER # This was created in 'Skeleton Mode', to only display # the overall structure of the source Orchestrator Runbook ################################################################################# workflow Invoke-1Managefreespace { Monitor Free Space Alert Delete File Get Disk Space Status Parallel { If ({Activity:Get Disk Space Status}.Percent-avail -lt "20") { Send Email If ({Activity:Send Email} {linkcondition:returns} "success") { Create Incident with Template } } If ({Activity:Get Disk Space Status}.Percent-avail -ge "20") { Close Alert } } } #################################################################################

PowerShell Export (skeleton mode)

Example 2

image

Orchestrator Runbook

image

Visio Export

image

Word Export (extract from the middle of the file)

001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 ################################################################################# # WORKFLOW CREATED BY THE SMART DOCUMENTATION AND CONVERSION HELPER # This was created in 'Skeleton Mode', to only display # the overall structure of the source Orchestrator Runbook ################################################################################# workflow Invoke-DeployNewStandaloneServerwSQL { ( [parameter(Mandatory=$true)] [String]$Instance_Name, [parameter(Mandatory=$true)] [String]$DB_Engine_Admin ) Initialize Data Get Service Parallel { If ({Activity:Get Service}.Count -eq "0") { Send Platform Event (2) (2) Deploy Service Template Send Platform Event (2) Return Data } If ({Activity:Get Service}.Count -eq "0") { Inject Instance Name on File } If ({Activity:Get Service}.Count -eq "1") { Get New VM Number Parallel { Sequence { Send Platform Event Scale Out Service Send Platform Event (3) Return Data } Inject Instance Name on File } } } } #################################################################################

PowerShell Export (skeleton mode)

001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 ################################################################################# # WORKFLOW CREATED BY THE SMART DOCUMENTATION AND CONVERSION HELPER # Make sure you review the summary analysis at the end of this file # to make final adjustements to the runbook ################################################################################# workflow Invoke-DeployNewStandaloneServerwSQL { ( [parameter(Mandatory=$true)] [String]$Instance_Name, [parameter(Mandatory=$true)] [String]$DB_Engine_Admin ) # START ACTIVITY - Initialize Data (Activity Type : Initialize Data) # Parameters were added in the workflow definition # Instance Name=> [String]$Instance_Name # DB Engine Admin=> [String]$DB_Engine_Admin # END ACTIVITY - Initialize Data # START ACTIVITY - Get Service (Activity Type : Get Service) # Configuration = sc-vmm2012sp1 # Properties = # Filter : Service Name [equals] {Variable:Placement - Dedicated-NoHA-Instance - VMM Service Farm} # END ACTIVITY - Get Service Parallel { If ({Activity:Get Service}.Count -eq "0") { # START ACTIVITY - Send Platform Event (2) (2) (Activity Type : Send Platform Event) # EventType = information # EventSummary = Creating SQL Farm for dedicated databases/instances # EventDetails = # END ACTIVITY - Send Platform Event (2) (2) # START ACTIVITY - Deploy Service Template (Activity Type : Run .NET Script) # Script Type = PowerShell $result=Invoke-Command -Computer {Variable:General - VMM Server Name} -ScriptBlock { import-module virtualmachinemanager $result = Get-SCVMMServer -ComputerName "{Variable:General - VMM Server Name}" $Cloud = Get-SCCloud -Name "{Variable:Deployment - VMM Cloud}" $ST= Get-SCServiceTemplate -Name "{Variable:Deployment - VMM Service Template for SQL Farm}" $ServiceConfig = New-SCServiceConfiguration -ServiceTemplate $ST -Name "{Variable:Placement - Dedicated-NoHA-Instance - VMM Service Farm}" -Cloud $Cloud -Description "This is a test" $NewService = New-SCService -ServiceConfiguration $ServiceConfig } # Published Data - None # END ACTIVITY - Deploy Service Template # START ACTIVITY - Send Platform Event (2) (Activity Type : Send Platform Event) # EventType = information # EventSummary = VM {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-1 was added to the farm # EventDetails = # END ACTIVITY - Send Platform Event (2) # START ACTIVITY - Return Data (Activity Type : Return Data) # VMName = {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-1 # DeploymentStatus = Success # END ACTIVITY - Return Data } If ({Activity:Get Service}.Count -eq "0") { # START ACTIVITY - Inject Instance Name on File (Activity Type : Trigger Policy) # PolicyObjectID = {F81B052F-EF5F-4AA9-8D53-861BA1B90EE0} # PolicyPath = Policies\SQL Server Provisioning\Subroutines\Other\Inject Instance Name on File # TriggerByPolicyPath = False # TargetActionServers = # WaitToComplete = False # Input parameter : Server Name = {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-1 # Input parameter : Instance Name = {Activity:Initialize Data.PublishedData:Instance Name} # END ACTIVITY - Inject Instance Name on File } If ({Activity:Get Service}.Count -eq "1") { # START ACTIVITY - Get New VM Number (Activity Type : Run .NET Script) # Script Type = PowerShell $newVMNb=Invoke-Command -Computer {Variable:General - VMM Server Name} -ScriptBlock { import-module virtualmachinemanager $result = Get-SCVMMServer -ComputerName "{Variable:General - VMM Server Name}" $nbVM = (get-VM | where-object {$_.name -match "{Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}"}).count $newVMNb = $nbVM +1 $newVMNb } # Published Data - Name : newVMNb / Type : String / Value : newVMNb - # END ACTIVITY - Get New VM Number Parallel { Sequence { # START ACTIVITY - Send Platform Event (Activity Type : Send Platform Event) # EventType = information # EventSummary = Scaling out SQL Farm for dedicated databases/instances # EventDetails = # END ACTIVITY - Send Platform Event # START ACTIVITY - Scale Out Service (Activity Type : Run .NET Script) # Script Type = PowerShell $result=Invoke-Command -Computer {Variable:General - VMM Server Name} -ScriptBlock { import-module virtualmachinemanager $result = Get-SCVMMServer -ComputerName "{Variable:General - VMM Server Name}" $Svc = Get-SCService -name "{Variable:Placement - Dedicated-NoHA-Instance - VMM Service Farm}" $CT = Get-SCComputerTier -Service $Svc New-SCVirtualMachine -ComputerTier $CT -Name "{Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-{Activity:Get New VM Number.PublishedData:newVMNb}.{Variable:General - Domain Name (FQDN)}" } # Published Data - None # END ACTIVITY - Scale Out Service # START ACTIVITY - Send Platform Event (3) (Activity Type : Send Platform Event) # EventType = information # EventSummary = VM {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-{Activity:Get New VM Number.PublishedData:newVMNb} was added to the farm # EventDetails = # END ACTIVITY - Send Platform Event (3) # START ACTIVITY - Return Data (Activity Type : Return Data) # VMName = {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-{Activity:Get New VM Number.PublishedData:newVMNb} # DeploymentStatus = Success # END ACTIVITY - Return Data } # START ACTIVITY - Inject Instance Name on File (Activity Type : Trigger Policy) # PolicyObjectID = {F81B052F-EF5F-4AA9-8D53-861BA1B90EE0} # PolicyPath = Policies\SQL Server Provisioning\Subroutines\Other\Inject Instance Name on File # TriggerByPolicyPath = False # TargetActionServers = # WaitToComplete = False # Input parameter : Instance Name = {Activity:Initialize Data.PublishedData:Instance Name} # Input parameter : Server Name = {Variable:Placement - Dedicated-NoHA-Instance - VM Prefix}-{Activity:Get New VM Number.PublishedData:newVMNb} # END ACTIVITY - Inject Instance Name on File } } } } ########################### CONVERSION HELPER SUMMARY ########################### # RUNBOOK START : Starting activity in the source Runbook is an Initialize Data activity. Actual parameters have been added at the beginning of the resulting workflow. Spaces in the parameters' names have been replaced by underscore characters. # VARIABLES : Variables were found in the source Runbook and should be replaced by SMA variables. Here is the list of variables discovered, and how many times they were used in the source Runbook : # - {Placement - Dedicated-NoHA-Instance - VMM Service Farm} (x3) - Current Value = SQL Farm 01 # - {General - VMM Server Name} (x6) - Current Value = vmm2012sp1 # - {Deployment - VMM Cloud} (x1) - Current Value = Contoso Southwest BU # - {Deployment - VMM Service Template for SQL Farm} (x1) - Current Value = SQL Server Farm # - {Placement - Dedicated-NoHA-Instance - VM Prefix} (x8) - Current Value = DEMO-WS-SQL # - {General - Domain Name (FQDN)} (x1) - Current Value = contoso.com # SUBROUTINES : Subroutines are involved through Invoke Runbooks activities in the source Orchestrator Runbook. You would likely replace these subroutines by SMA subroutine Runbooks. Here is the list of invoked Runbooks discovered, and how many times they were called by the source Runbook : # - Inject Instance Name on File (x2) # OUTUT DATA : Return Data activities are used in the source Orchestrator Runbook. Properties returned are embedded earlier in the script. Here is a list of names for the corresponding activities, and how many times they were called by the source Runbook : # - Return Data (x2) # SCHEDULES : No Check Schedule activities were used in this source Runbook. # COUNTERS : No Counter-related activities were used in this source Runbook. # PARALLEL BRANCHES : The following activities had multiple outbound links. These have been added to the script as 'parallel' script paragraphs, but you might also want to look if the use of 'parallel' is actually needed or could be optimized. # - Get Service # - Get New VM Number # LINK CONDITIONS : No string conditions were used in this source Runbook's links. # LOOPS : If there are loops within the source Runbooks, they are listed below, and you may also need to look at the exit/non-exit conditions to convert them: # MERGING BRANCHES : If there are activities with multiple inbound branches, they are listed below and the script output may be simplified (right now it duplicates code for each branch, in this situation) # JUNCTIONS : No junctions were used in this source Runbook. #################################################################################

PowerShell Export (full mode)

image

The 3 saved exports

image

PowerShell command output – the Word export is generally the Visio and PowerShell exports are the fastest

Comments

  • Anonymous
    January 01, 2003
    Hi Column A,

    Apologies for the late reply, I was out of the office.

    Yes, the tool was tested with Office 32-bit, and assumes it's the version installed. To explain the reasoning : Office installs itself as 32-bit by default, even on 64-bit machine. It is also most generally the version recommended :http://office.microsoft.com/en-us/support/choose-the-32-bit-or-64-bit-version-of-office-HA102840825.aspx

    Regarding the other issue you mentioned about the images export : The script SMART-DocumentationConversionHelper-ImageExport.ps1 must be run before, in 32-bit mode. This exports the images (when it can), and they should be then be automatically be picked up during Word/Visio export. Also, make sure you then run the tool from the same directory where the images are located. There is a note at the bottom right of the tool to notify you of how many images have been found in the local folder.

    Hope this helps, let me know
    Thanks
  • Anonymous
    January 01, 2003
    The comment has been removed
  • Anonymous
    January 01, 2003
    The comment has been removed
  • Anonymous
    January 01, 2003
    awesome post, thanks
  • Anonymous
    January 01, 2003
    Note: The Word output is BRILLIANT!!!! Absolutely BRILLIANT!!!! Such a great way to debug and improve.

    I ran this on Win 8.1 x64 pro with Office x64 and Visual Studio 2013 (with the SCORCH server and databases on other servers) and it ran fine with the following exceptions:
    1. The default path on Visio settings has Program Files (x32). The (x32) needed to be removed.
    2. No images came across in Visio or Word output (no big deal). The image installer complained about pictures a bunch of times if that helps any. I'm using lots of 3rd party IPs, so the images isn't a big deal.

    This is the script output for the failures:

    [ 16:04:50 ] -- Working on activity : Create User (Activity Type : Create User)
    Exception calling "AddPicture" with "1" argument(s): "This is not a valid file name.
    Try one or more of the following:
    * Check the path to make sure it was typed correctly.
    * Select a file from the list of files and folders."
    At C:OrchestratorSMART-DocumentationConversionHelper20SMART-DocumentationConversionHelper.ps1:1
    168 char:31
    + else {$oPara1.Range.InlineShapes.AddPicture((Get-Locatio ...
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : ComMethodTargetInvocation

    Exception calling "AddPicture" with "1" argument(s): "This is not a valid file name.
    Try one or more of the following:
    * Check the path to make sure it was typed correctly.
    * Select a file from the list of files and folders."
    At C:OrchestratorSMART-DocumentationConversionHelper20SMART-DocumentationConversionHelper.ps1:1
    168 char:31
    + else {$oPara1.Range.InlineShapes.AddPicture((Get-Locatio ...
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : ComMethodTargetInvocation

    Exception calling "AddPicture" with "1" argument(s): "This is not a valid file name.
    Try one or more of the following:
    * Check the path to make sure it was typed correctly.
    * Select a file from the list of files and folders."
    At C:OrchestratorSMART-DocumentationConversionHelper20SMART-DocumentationConversionHelper.ps1:1
    135 char:23
    + else {$oPara1.Range.InlineShapes.AddPicture((Get-Location -PSPro ...
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : ComMethodTargetInvocation
  • Anonymous
    January 01, 2003
    Hi Heshy,
    Apologies for the late reply.
    While we are not planning a short term update for the tool, it is fully available in PowerShell, so it could be possible to update the script to achieve what you are mentioning. If you or someone else adds this and makes this an option, feel free to share it back if you can, so others in the community can also benefit from it. Thanks!
  • Anonymous
    June 04, 2014
    Hi,

    This will prove really useful for sure!

    I just had a small issue : I couldn't have it connect to a named instance and had to modify the code to remove every mention of the DBPORT from every connection string... I don't really know why .

    So, every $Global:SQLConnstr = "Server=" + $Global:DatabaseServer +"," + $Global:DatabasePort + ";Integrated Security=SSPI;database=" + $DatabaseName
    need to be changed to $Global:SQLConnstr = "Server=" + $Global:DatabaseServer + ";Integrated Security=SSPI;database=" + $DatabaseName
  • Anonymous
    July 17, 2014
    Hi,

    I have a problem with the SMART Documentation and Conversion Helper.
    When I export a Runbook to a Wordfile, it generates some activities twiec or more times.

    And also it generates activities from old versions of the runbook. So that means that I have a realy large Wordfile with every activitie in it when ever I had checked out the runbook.

    Is there any help for this?
    Or someone with the same problem?

    Regards Patrick
  • Anonymous
    July 22, 2014
    I can confirm the behavior that Patrick is seeing with Word exports created via the tool containing all Activities ever associated with a runbook, even if they have been removed from the Runbook Designer Workflow.

    For example, I originally had a Query XML activity as part of a runbook being developed, but instead settled on using XPATH queries via a PowerShell script, so I removed the Query XML activity. When I run the SMART tool though, my Word File export contains references to the original Query XML activity.

    It looks like this data might be coming from cached info on the Runbook Server, as I see no reference to my deleted activities in the [Microsoft.SystemCenter.Orchestrator].[Activities] view in the DB.
  • Anonymous
    July 22, 2014
    The comment has been removed
  • Anonymous
    January 27, 2015
    Hi,

    I was wondering if the script could be modified to allow us to pass a domainuserid DB credentials that are not the same as the elevated admin credentials used to launch powrshell. It would most ideal as a parameter or prompt when launching the script.