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

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

  • Comments 5
  • Likes

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

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • 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

  • 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

  • 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.

  • Found the solution to Issue that Patrick and I were seeing, with deleted activities showing up in the Word Document export.

    Line 1119 in SMART-DocumentationConversionHelper.ps1 modified to:
    $SqlQueryDOC = "select UniqueID, ObjectType, Name, Description, PositionX, PositionY from OBJECTS WHERE ParentID = '" + $RunbookID + "' AND ObjectType <> '7A65BD17-9532-4D07-A6DA-E0F89FA0203E' AND Deleted = 0"

  • Hi Lucas and Patrick., and apologies for the late reply.
    Thanks Lucas, great find! You are right, this is the SQL Query as it should be on line 1119 - it was correct in the Visio Export routine (line 937) and this was probably an oversight when taking the code from the previous tool and porting it to PowerShell (because this was some of the things that were supposed to be enhanced along the way!). It is true that deleted activities remain in the Orchestrator DB and need to be filtered out in queries.
    Have a great week-end