• Documenting a Citrix Provisioning Services Farm with Microsoft PowerShell and Word – Version 2

    February 20, 2013

    PowerShell, PVS

    The script to document a Citrix Provisioning Services (PVS) farm has proven to be very popular.  I have always wanted to take the time to create a version of the script that would output to a Microsoft Word document.  Ryan Revord had taken the XenApp 6.0 script and changed it to create a basic Microsoft Word document.  Ryan saved me a lot of work but I wanted improve on the document created by adding a cover page, Table of Contents and footer.  This article will explain the changes to the script to create a Word document.

    NOTE: This script is continually updated.  You can always find the most current version by going to https://carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

    As much as Microsoft pushes PowerShell for their products and on their users, I find it surprising there is no native PowerShell support for any of the Office products.  For example there is no New_WordDocument, Get-WordDocument or Save-WordDocument.  In order to use Word with PowerShell you must use the Word COM Object model.  Finding detailed information on that subject was not easy.  Fortunately for me, Jeff Hicks had blogged about a presentation he did in 2012 where he linked to some sample PowerShell script files.  One of his sample files gave me the start I needed.

    The prerequisites to follow along with this article are:

    • Word 2007, 2010 or 2013 installed on the computer running the script
    • PVS 5.6, PVS 6.0 or PVS 6.1
    • PVS Console PowerShell snap-in registered

    Note: The parts of this script that deal with creating the Word document are derived 100% from the XenApp 6.5 script.  To read the details of the changes to the script that deal with Microsoft Word, please read Documenting a Citrix XenApp 6.5 Farm with Microsoft PowerShell and Word – Version 3.  Several of the bug fixes and issues resolved for Version 3.1 of the XenApp 6.5 script are included in this script.  These include:

    • Several typos were fixed to get rid of my southern drawl. No more “gettin”, “settin” or “runnin”.
    • Write-Verbose statements were added.
    • Fixed all the issues reported by running the script with Set-StrictMode –Version 2.0 set.
    • For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set. For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set. The script will now check both locations.
    • Some companies do not install the Microsoft Word Templates. This cause the Cover Page and Table of Contents sections of the script to generate numerous errors. The script now checks to see if the appropriate Word Template file is loaded successfully. If not, then the Cover Page and Table of Contents are skipped. The rest of the report is generated.
    • Pat Coughlin showed me how to disable Spell Check and Grammar Check while the document is created. For large PVS Farms, this can substantially speed up the document creation. For those large farms that can generate 1000+ page documents, Word would crash trying to keep track of all the spelling and grammar errors.
    • I received a question as to whether Microsoft Word needed to be installed to create the Word document. The script now verifies that Word is installed. If not, a warning is given and the script exits.
    • I received reports of the script “crashing” if Word was running before the script was run. The script will now check to see if Word is running and if it is, the script will exit. If the script is run from a XenApp server, the script gets the Session ID of the user running the script. Then the script checks if the WinWord process is running in that session. If it is, a warning is given and the script exits.

    In trying to find resources to figure out how to use PowerShell to create a complex Word document, I found Jeff Hick’s blog post and sample scripts.

    http://jdhitsolutions.com/blog/2012/05/san-diego-2012-powershell-deep-dive-slides-and-demos/

    Jeff had a ZIP file with several sample PowerShell scripts.  One of them, Demo-WordReport.ps1, was extremely helpful.

    Pat Coughlin showed me how to disable Spell Check and Grammar Check while the document is created.  For large PVS Farms, this can substantially speed up the document creation.  For those large farms that can generate 1000+ page documents, Word would crash trying to keep track of all the spelling and grammar errors.

    There are three pieces of information the script needs for the Cover Page and Footer:

    1. Company Name
    2. Cover Page
    3. User Name

    Since a digitally signed version of the script is provided, these three pieces of information need to be passed to the script as parameters.  A signed PowerShell script cannot be modified or the script is rendered useless.

    These parameters give us $CompanyName, $CoverPage and $UserName.  Each has an alias: CN for CompanyName, CP for CoverPage and UN for UserName.

    The default for $CompanyName is read from the registry key where Microsoft Office stores user information.  For some users, when Microsoft Word is installed, the HKCU:\Software\Microsoft\Office\Common\UserInfo\CompanyName registry key is set and for some, it is not set.  For those users, the HKCU:\Software\Microsoft\Office\Common\UserInfo\Company registry key is set.  The script checks both locations.

    The default for $CoverPage is Motion.  Motion is a Word Cover Page that comes with all versions of Word, looks good but will require a minor tweak of changing the font used by the date field to a smaller font size.  Some companies do not install the Microsoft Word Templates.  The script checks to see if the appropriate Word Template file is loaded successfully.  If not, then the Cover Page and Table of Contents are skipped.  The rest of the report is generated.

    The default for $UserName is taken from the USERNAME environment variable.

    The parameter names can be spelled out or the aliases can be used or any combination.  All three of these examples are valid:

    -CompanyName “XYC, Inc.” –CoverPage “Grid” –UserName “Joe User”

    -CN “XYC, Inc.” –CP “Grid” –UN “Joe User”

    -CoverPage “Grid” –UN “Joe User”

    For the third example, the default Company Name will be used.

    For the Word document to be saved a file name is needed and for the Cover Page, a title is needed.

    The filename for the document is the PVS farm name with the extension DOCX.  The document is stored in the folder where the script is run.

    Each version of Word comes with Cover Pages and only two are shared across all versions.  The version of Word installed on the computer running the script needs to be determined.  If a wrong cover page is passed as $CoverPage and that Cover Page is not in the installed version of Word, the script will run but a lot of errors will be returned.  The script validates the $CoverPage against the valid Cover Pages specific to each version of Word.

    If an invalid Cover Page is used, the script gives an error, closes Word and exits.

    In Version 1 of this script, in order to write out a line of output, my friend Michael B. Smith wrote a Line function.  That function is no longer needed.  Ryan took Michael’s function and modified it to write a line to Word.

    In updating this script, I fixed several bugs and logic issues.  For example, the time of “12:00 AM” for various update schedules was incorrectly printed as “012:00 PM”.  An example of a logic fix is For PVS 6.x vDisk Update Management.  I was only processing the Virtualization Hosts and vDisks only if at least one Task had been defined.  The Virtualization Hosts and vDisks are now processed independently of the Tasks.

    Since this script has parameters, I created help text for the script.  Running the following command from the PowerShell prompt will display the full help text.

    
    Get-Help .\PVS_Inventory_v2.ps1 -full
    
    

    You can also use –online to get taken to this article.

    
    Get-Help .\PVS_Inventory_V2.ps1 -online
    
    

    Running the script with –verbose, gives information of the script’s running.

    
    .\PVS_inventory_v2.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Motion" -UserName "Amalgamated Consulting Group" -verbose
    
    

    Sample output.

    PS C:\webster> .\pvs_inventory_v2.ps1 -CompanyName "The Accidental Citrix Admin" -CoverPage "Contrast" -UserName "Amalgamated Consulting Group" -verbose
    VERBOSE: checking for McliPSSnapin
    VERBOSE: Getting PVS version info
    VERBOSE: Build PVS farm values
    VERBOSE: Setting up Word
    VERBOSE: Create Word comObject.  If you are not running Word 2007, ignore the next message.
    VERBOSE: The object written to the pipeline is an instance of the type “Microsoft.Office.Interop.Word.ApplicationClass"  from the component's primary interop assembly. If this type exposes different members than the IDispatch members, scripts written to work with this object might not work if the primary interop assembly is not installed.
    VERBOSE: Running Microsoft Word 2010
    VERBOSE: Validate company name
    VERBOSE: Validate cover page
    VERBOSE: Company Name: The Accidental Citrix Admin
    VERBOSE: Cover Page  : Contrast
    VERBOSE: User Name   : Amalgamated Consulting Group
    VERBOSE: Farm Name   : PVS61Farm
    VERBOSE: Title       : Inventory Report for the PVS61Farm Farm
    VERBOSE: Filename    : C:\webster\PVS61Farm.docx
    VERBOSE: Load Word Templates
    VERBOSE: Create empty word doc
    VERBOSE: disable spell checking
    VERBOSE: insert new page, getting ready for table of contents
    VERBOSE: table of contents
    VERBOSE: set the footer
    VERBOSE: get the footer and format font
    VERBOSE: Footer text
    VERBOSE: add page numbering
    VERBOSE: return focus to main document
    VERBOSE: move to the end of the current document
    VERBOSE: Processing PVS Farm Information
    VERBOSE: Processing Security Tab
    VERBOSE: Processing Groups Tab
    VERBOSE: Processing Licensing Tab
    VERBOSE: Processing Options Tab
    VERBOSE: Processing vDisk Version Tab
    VERBOSE: Processing Status Tab
    VERBOSE: Processing Sites
    VERBOSE: Processing Site PVS61Site
    VERBOSE: Processing Security Tab
    VERBOSE: Processing Options Tab
    VERBOSE: Processing vDisk Update Tab
    VERBOSE: Processing Servers in Site PVS61Site
    VERBOSE: Processing Server PVS61
    VERBOSE: Processing General Tab
    VERBOSE: Processing Network Tab
    VERBOSE: Processing Stores Tab
    VERBOSE: Processing Stores for server
    VERBOSE: Processing Store PVS61Store
    VERBOSE: Processing Options Tab
    VERBOSE: Processing Logging Tab
    VERBOSE: Processing Server Tab on Advanced button
    VERBOSE: Processing Network Tab on Advanced button
    VERBOSE: Processing Pacing Tab on Advanced button
    VERBOSE: Processing Device Tab on Advanced button
    VERBOSE: Processing Bootstrap files
    VERBOSE: Processing Bootstrap files for Server PVS61
    VERBOSE: Processing General Tab
    VERBOSE: Processing Options Tab
    VERBOSE: Processing all vDisks in site
    VERBOSE: Processing vDisk PVS61vDisk
    VERBOSE: Processing Properties General Tab
    VERBOSE: Processing Identification Tab
    VERBOSE: Processing Auto Update Tab
    VERBOSE: Processing vDisk Update Management
    VERBOSE: Processing virtual hosts
    VERBOSE: Processing virtual host XenServer5
    VERBOSE: Processing General Tab
    VERBOSE: Processing Advanced Tab
    VERBOSE: Processing all Update Managed vDisks for this site
    VERBOSE: Processing Managed vDisk PVS61Store\PVS61vDisk
    VERBOSE: Processing General Tab
    VERBOSE: Processing Personality Tab
    VERBOSE: Processing Status Tab
    VERBOSE: Processing Logging Tab
    VERBOSE: Processing Task Task2
    VERBOSE: Processing General Tab
    VERBOSE: Processing Schedule Tab
    VERBOSE: Processing vDisks Tab
    VERBOSE: Processing ESD Tab
    VERBOSE: Processing Scripts Tab
    VERBOSE: Processing Access Tab
    VERBOSE: Processing Task Task3
    VERBOSE: Processing General Tab
    VERBOSE: Processing Schedule Tab
    VERBOSE: Processing vDisks Tab
    VERBOSE: Processing ESD Tab
    VERBOSE: Processing Scripts Tab
    VERBOSE: Processing Access Tab
    VERBOSE: Processing all device collections in site
    VERBOSE: Processing Collection PVS61Collection
    VERBOSE: Processing General Tab
    VERBOSE: Processing Security Tab
    VERBOSE: Processing Auto-Add Tab
    VERBOSE: Processing each collection process for each device
    VERBOSE: Processing Device TestVM3
    VERBOSE: Processing General Tab
    VERBOSE: Processing vDisks Tab
    VERBOSE: Processing all bootstrap files for this device
    VERBOSE: Processing Authentication Tab
    VERBOSE: Processing Personality Tab
    VERBOSE: Processing all site views in site
    VERBOSE: Processing all PVS Farm Views
    VERBOSE: Processing Stores
    VERBOSE: Processing Store PVS61Store
    VERBOSE: Processing General Tab
    VERBOSE: Processing Servers Tab
    VERBOSE: Processing Server PVS61
    VERBOSE: Processing Paths Tab
    VERBOSE: Finishing up Word document
    VERBOSE: Set Cover Page Properties
    VERBOSE: Update the Table of Contents
    VERBOSE: Save and Close document and Shutdown Word
    PS C:\webster>
    

    How to use this script?

    I saved the script as PVS_Inventory_V2.ps1 in the C:\PSScripts folder.  From the PowerShell prompt, change to the C:\PSScripts folder, or the folder where you saved the script.  From the PowerShell prompt, type in:

    .\PVS_Inventory_V2.ps1 and press Enter.

    A word about Word

    1. Word must be installed
    2. After installation, Word should be opened, at least once, before you run the script
    3. It is better to do File, Options, OK before running the script

    The script does very strange things if the last two items are not done.  All kinds of errors are generated by the script if Word has not been opened at least once.  The second time the script is run (without Word haven been opened), fewer errors are generated.  The third time the script is run, it runs without errors.

    Word 2013 is the worst.  If Word 2013 is installed and never opened before running the script, a popup box is shown asking to set file extension defaults.  It does not matter if Never ask me again is selected and Yes or No is clicked, the popup box will return until Word 2013 is opened and closed.

    I am assuming there are registry keys and values that need to be set for the Word comObject to operate properly.

    Bottom Line: If you just installed Word, open Word and close Word before running the script.

    If you have any suggestions for the script, please let me know.  Send an e-mail to webster@carlwebster.com.

    NOTE: This script is continually updated.  You can always find the most current version by going to https://carlwebster.com/where-to-get-copies-of-the-documentation-scripts/

    Copies of all the Cover Pages, from the XenApp scripts, can be found here:

    Word 2007

    Word 2010

    Word 2013

     

    , , , , , , ,

    About Carl Webster

    Webster is a Sr. Solutions Architect for Choice Solutions, LLC and specializes in Citrix, Active Directory and Technical Documentation. Webster has been working with Citrix products for many years starting with Multi-User OS/2 in 1990.

    View all posts by Carl Webster

    One Response to “Documenting a Citrix Provisioning Services Farm with Microsoft PowerShell and Word – Version 2”

    1. Anton Says:

      As I said, awesome work Carl!
      Many people will benefit from this scripts in the near feature 🙂

      Cheers,
      Anton

      Reply

    Leave a Reply