Using the vCenter Orchestrator Plug-In

for Microsoft Windows PowerShell 1.0.x

vCenter Orchestrator 4.2

This document supports the version of each product listed and

supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.

EN-000757-04

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com

Copyright 20112013 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com

VMware, Inc.

Contents

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x 5
Updated Information 7

1 Introduction to the VMware vCenter Orchestrator Plug-In for Microsoft

Windows PowerShell 9

PowerShell Plug-In Components 9

Role of vCenter Orchestrator with the PowerShell Plug-In
Plug-In Interaction with Windows PowerShell 10
Supported Communication Protocols 11
Configure WinRM to Use HTTP 11
Configure WinRM to Use HTTPS 12
Installing the PowerShell Plug-In 13
PowerShell Plug-In Functional Prerequisites 13
Install the PowerShell Plug-In 13

10

2 Using the PowerShell Plug-In 15

Using the PowerShell Plug-In Inventory 15

Configuring the PowerShell Plug-In 16
Configuration Workflows 16
Configure Kerberos Authentication 16
Add a PowerShell Host 17
Running PowerShell Scripts 18
Invoke a PowerShell Script 18
Invoke an External Script 18
Generating Actions 19
Generate an Action from a PowerShell Script 19
Generate an Action for a PowerShell Cmdlet 20
Passing Invocation Results Between Actions 21
PowerCLI Integration with the PowerShell Plug-In 21
Converter Workflows 21
Sample Workflows 21
Access the PowerShell Plug-In API 22
Working with PowerShell Results 22
Examples of Scripts for Common PowerShell Tasks 23
Troubleshooting 25
Servers Not Found in Kerberos Database 25
Unable to Obtain a Kerberos Ticket 25
Kerberos Authentication Fails Due to Time Differences 25
Kerberos Authentication Session Mode Fails 26
Unable to Reach a Key Distribution Center for a Realm 26

VMware, Inc.

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Index 27

VMware, Inc.

Using the vCenter Orchestrator Plug-In for

Microsoft Windows PowerShell 1.0.x

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x provides information and

instructions about configuring and using the VMware vCenter Orchestrator Plug-In for Microsoft Windows
PowerShell 1.0.x.

Intended Audience
This book is intended for anyone who is installing and configuring the plug-in, using the API of the plug-in,
and using the workflow library. The information in Using the vCenter Orchestrator Plug-In for Microsoft Windows
PowerShell 1.0.x is written for experienced users who are familiar with virtual machine technology, with
Orchestrator workflow development, and with Windows PowerShell.
For more information about Orchestrator, see
http://www.vmware.com/support/pubs/orchestrator_pubs.html.
For more information about Windows PowerShell, see
http://technet.microsoft.com/en-us/library/bb978526.aspx.

VMware, Inc.

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

VMware, Inc.

Updated Information

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x is updated with each release of the
product or when necessary.
This table provides the update history of Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell
1.0.x.
Revision

Description

EN-000757-04

Added a note to Add a PowerShell Host, on page 17 and Configure Kerberos Authentication, on
page 16 that Kerberos authentication requires a FQDN host address.

EN-000757-03

Made the following corrections and improvements:

n Added an important note in Configure WinRM to Use HTTP, on page 11.
n Added a new path for Kerberos configuration file for Linux operating system, added an important note,
and updated the Kerberos configuration example in Configure Kerberos Authentication, on
page 16.

EN-000757-02

Release 1.0.1 of the PowerShell plug-in, which adds support for Kerberos authentication.
n Added information about the new authentication type Kerberos in Add a PowerShell Host, on
page 17.
n Added configuration information about the new authentication type Kerberos in Configure Kerberos
Authentication, on page 16.
n Added troubleshooting information about Kerberos in Troubleshooting, on page 25.

EN-000757-01

Added information about configuring trusted hosts when the WinRM host machine is in an external domain
in Configure WinRM to Use HTTP, on page 11. This information is applicable for the initial 1.0 release
of the plug-in.

EN-000757-00

Release 1.0 of the plug-in.

VMware, Inc.

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

VMware, Inc.

Introduction to the VMware vCenter

Orchestrator Plug-In for Microsoft
Windows PowerShell

The PowerShell plug-in (VMware vCenter Orchestrator plug-in for Microsoft Windows PowerShell) allows
interaction between vCenter Orchestrator and Windows PowerShell.
You use the plug-in to call PowerShell scripts and cmdlets from Orchestrator actions and workflows, and to
work with the result. The plug-in contains a set of standard workflows. You can also create custom workflows
that implement the plug-in API.
This chapter includes the following topics:
n

PowerShell Plug-In Components, on page 9

Supported Communication Protocols, on page 11

Installing the PowerShell Plug-In, on page 13

PowerShell Plug-In Components

The PowerShell plug-in relies on a number of components to function properly.
vCenter Orchestrator and Windows PowerShell provide the platform for the plug-in, and the plug-in provides
interaction between those products. The PowerShell plug-in can also interact with other components, such as
vCenter Server and vSphere PowerCLI.

VMware, Inc.

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Figure 1-1. Component Relations

vCenter Orchestrator
vCenter Server

vCenter Server
plug-in

PowerShell
plug-in

WinRM/HTTP(S)
or SSH

Windows
WinRM service or OpenSSH v5.9
PowerShell
PowerCLI (optional)

The plug-in can communicate with Windows PowerShell through the OpenSSH and WinRM communication
protocols. See Supported Communication Protocols, on page 11.
Optionally, you can integrate the PowerShell plug-in with vSphere PowerCLI and vCenter Server. See
PowerCLI Integration with the PowerShell Plug-In, on page 21.
NOTE You can install all components on a local host. The usage, functionality, and communication protocol
requirements of the PowerShell plug-in do not change if vCenter Orchestrator and Windows PowerShell are
installed on the same machine.

Role of vCenter Orchestrator with the PowerShell Plug-In

You must use the Orchestrator configuration interface to install the PowerShell plug-in. You use the
Orchestrator client to run and create workflows and access the plug-in API.
The PowerShell plug-in is powered by vCenter Orchestrator. Orchestrator is a development and processautomation platform that provides a library of extensible workflows to manage the VMware vCenter
infrastructure and other technologies.
Orchestrator allows integration with management and administration solutions through its open plug-in
architecture. PowerShell is one example of an administration solution that you can integrate with Orchestrator
by using plug-ins.

Plug-In Interaction with Windows PowerShell

You can use the plug-in to run Orchestrator workflows that interact with Windows PowerShell hosts and
perform tasks, such as invoking PowerShell scripts.
Windows PowerShell is a task-based command-line shell and scripting language designed for system
administration.

10

VMware, Inc.

Chapter 1 Introduction to the VMware vCenter Orchestrator Plug-In for Microsoft Windows PowerShell

Supported Communication Protocols

You can establish a connection between the PowerShell plug-in and Windows PowerShell through only the
supported communication protocols.
The PowerShell plug-in supports the following communication protocols.
Communication Protocol

Version

OpenSSH

The plug-in supports OpenSSH 5.9.

WinRM

The plug-in supports WinRM 2.0.

WinRM through HTTP

The PowerShell plug-in supports communication with the WinRM host through the HTTP protocol. Although
WinRM authenticates the communication, the data transfer is not encrypted and is sent as plain text on the
network. You should use the HTTP protocol if IPSec is configured between the machines that communicate.
Basic authentication is supported. To use it, you must set the AllowUnencrypted property to true in both the
service and client WinRM configuration. For an example of HTTP configuration, see Configure WinRM to
Use HTTP, on page 11.

WinRM through HTTPS

The PowerShell plug-in supports communication with the WinRM host through the HTTPS protocol. You can
use the HTTPS protocol as a more secure communication method.
To use the HTTPS protocol, you must generate a certificate for server authentication and install the certificate
on the WinRM host. For an example of HTTPS configuration, see Configure WinRM to Use HTTPS, on
page 12.

Configure WinRM to Use HTTP

You can configure the WinRM host to enable communication with the PowerShell plug-in through the HTTP
protocol.
You must modify the WinRM configuration by running commands on the WinRM host machine. You can use
the same machine as both the WinRM service and WinRM client.
IMPORTANT If you skip any of the steps when configuring WinRM to use HTTP, the host might not be added,
and you might get an error message in the logs such as
Caused by: org.dom4j.DocumentException: Error on line -1 of document : Premature end of file.
Nested exception: Premature end of file.
at org.dom4j.io.SAXReader.read(SAXReader.java:482)
at org.dom4j.DocumentHelper.parseText(DocumentHelper.java:278)
at
com.xebialabs.overthere.cifs.winrm.connector.JdkHttpConnector.sendMessage(JdkHttpConnector.java:
117)

Procedure
1

Run the following command to set the default WinRM configuration values.
c:\> winrm quickconfig

VMware, Inc.

11

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

(Optional) Run the following command to check whether a listener is running, and verify the default ports.
c:\> winrm e winrm/config/listener

The default ports are 5985 for HTTP, and 5986 for HTTPS.
3

Enable basic authentication on the WinRM service.

a

Run the following command to check whether basic authentication is allowed.

c:\> winrm get winrm/config

Run the following command to enable basic authentication.

c:\> winrm set winrm/config/service/auth @{Basic="true"}

Run the following command to allow transfer of unencrypted data on the WinRM service.
c:\> winrm set winrm/config/service @{AllowUnencrypted="true"}

Enable basic authentication on the WinRM client.

a

Run the following command to check whether basic authentication is allowed.

c:\> winrm get winrm/config

Run the following command to enable basic authentication.

c:\> winrm set winrm/config/client/auth @{Basic="true"}

Run the following command to allow transfer of unencrypted data on the WinRM client.
c:\> winrm set winrm/config/client @{AllowUnencrypted="true"}

If the WinRM host machine is in an external domain, run the following command to specify the trusted
hosts.
c:\> winrm set winrm/config/client @{TrustedHosts="host1, host2, host3"}

Run the following command to test the connection to the WinRM service.
c:\> winrm identify -r:http://winrm_server:5985 -auth:basic -u:user_name -p:password encoding:utf-8

Configure WinRM to Use HTTPS

You can configure the WinRM host to enable communication with the PowerShell plug-in through the HTTPS
protocol.
The WinRM host requires a certificate so that it can communicate through the HTTPS protocol. You can either
obtain a certificate or generate one. For example, you can generate a self-signed certificate by using the
Certificate Creation tool (makecert.exe) that is part of the .NET Framework SDK.
Prerequisites
Verify that you can access the Microsoft Management Console (mmc.exe) on the WinRM host.
Procedure
1

Generate a self-signed certificate.

The following command line contains example syntax for creating a certificate on the WinRM host by
using makecert.exe.
makecert.exe -r -pe -n "CN=host_name-3,O=organization_name" -e mm/dd/yyyy -eku
1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel
Cryptographic Provider" -sy 12 certificate_name.cer

12

VMware, Inc.

Chapter 1 Introduction to the VMware vCenter Orchestrator Plug-In for Microsoft Windows PowerShell

Add the generated certificate by using the Microsoft Management Console.

a

Run mmc.exe.

Select File > Add/Remove Snap-in.

From the list of available snap-ins, select Certificates and click Add.

Select Computer account and click Next.

Click Finish.

Verify that the certificate is installed in Console Root > Certificates (Local Computer) > Personal >
Certificates and Console Root > Certificates (Local Computer) > Trusted Root Certification
Authorities > Certificates.
If the certificate is not installed in the Trusted Root Certification Authorities and Personal folders, you
must install it manually.

Create an HTTPS listener by using the correct thumbprint and host name.
The following command line contains example syntax for creating an HTTPS listener.
winrm create winrm/config/Listener?Address=*+Transport=HTTPS
@{Hostname="host_name";CertificateThumbprint="certificate_thumbprint"}

Test the connection.

The following command line contains example syntax for testing the connection.
winrs -r:https://host_name:port_number -u:user_name -p:password hostname"}

Installing the PowerShell Plug-In

You must use the Orchestrator configuration interface to install the PowerShell plug-in.

PowerShell Plug-In Functional Prerequisites

To be able to install and use the PowerShell plug-in, your system must meet the functional prerequisites.

vCenter Orchestrator
Verify that you have a running instance of Orchestrator. You can log in to the Orchestrator configuration
interface at http://orchestrator_server:8282. Version 1.0 of the plug-in works with vCenter Orchestrator 4.2.
For information about setting up Orchestrator, see Installing and Configuring VMware vCenter Orchestrator.

Windows PowerShell
Verify that you have access to a Windows PowerShell host. Version 1.0 of the plug-in works with Windows
PowerShell 1.0 and 2.0.
For information, see the Windows PowerShell documentation.

Install the PowerShell Plug-In

To be able to use the PowerShell plug-in, you must download the .vmoapp file containing the plug-in and install
it by using the Orchestrator configuration interface.
Prerequisites
n

Verify that you are logged in to the Orchestrator configuration interface at http://orchestrator_server:8282.

Verify that you have downloaded the .vmoapp file from

http://www.vmware.com/products/datacenter-virtualization/vcenter-orchestrator/plugins.html.

VMware, Inc.

13

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Procedure
1

On the General tab, click Install Application.

Upload the PowerShell plug-in.

a

Click the magnifying glass icon.

Select the .vmoapp file to install.

Click Open.

Click Install.

A message appears after successful installation. The PowerShell plug-in is installed without a tab in the
Orchestrator configuration interface.

14

On the Startup Options tab, click Restart service to complete the plug-in installation.

VMware, Inc.

Using the PowerShell Plug-In

The PowerShell plug-in workflow library contains workflows that allow you to manage PowerShell hosts and
run custom PowerShell operations.
You can use the Inventory view in the Orchestrator client to manage the available PowerShell resources. You
can use the scripting API of the plug-in to develop custom workflows.
This chapter includes the following topics:
n

Using the PowerShell Plug-In Inventory, on page 15

Configuring the PowerShell Plug-In, on page 16

Running PowerShell Scripts, on page 18

Generating Actions, on page 19

Passing Invocation Results Between Actions, on page 21

PowerCLI Integration with the PowerShell Plug-In, on page 21

Sample Workflows, on page 21

Access the PowerShell Plug-In API, on page 22

Working with PowerShell Results, on page 22

Examples of Scripts for Common PowerShell Tasks, on page 23

Troubleshooting, on page 25

Using the PowerShell Plug-In Inventory

The PowerShell plug-in exposes all objects in the connected PowerShell hosts in the Inventory view. You can
use the Inventory view to add authorization elements or to run workflows on PowerShell objects.
Within the inventory of the plug-in, you can monitor PowerShell hosts and their snap-ins and cmdlets. Each
remote host can contain snap-ins and each snap-in can contain cmdlets.
You can enable the Use contextual menu in inventory option to display the workflows that are available for
an inventory object. After the option is enabled, when you right-click an object in the Orchestrator inventory,
all available workflows for the object are displayed.

VMware, Inc.

15

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Configuring the PowerShell Plug-In

You must use the Orchestrator client to configure the PowerShell plug-in.

Configuration Workflows
The Configuration workflow category contains workflows that allow you to manage PowerShell hosts.
You can access these workflows from Library > PowerShell > Configuration on the Workflows view in the
Orchestrator client.
Workflow Name

Description

Add a PowerShell host

Adds a PowerShell host to the plug-in's inventory.

Manage SSL certificates

Verifies a host URL, and if required, shows a user interaction message for SSL certificates user
approval.

Remove a PowerShell host

Removes a PowerShell host from the plug-in's inventory.

Update a PowerShell host

Updates the specified PowerShell host in the plug-in's inventory.

Validate a PowerShell host

Validates the specified PowerShell host's configuration.

Configure Kerberos Authentication

You can use Kerberos authentication when you add a host.
The krb5.conf file contains the following information:
n

Kerberos configuration information

Locations of Key Distribution Centers (KDC) and administration servers for the Kerberos realms of interest

Default values for the current realm and for Kerberos applications

Mappings of host names onto Kerberos realms

Procedure
u

Create a krb5.conf file and save it to the following location.

Operating System

Path

Windows

your_Orchestrator_installation_folder/jre/lib/security/

Linux

/opt/vmo/jre/lib/security

A krb5.conf file has the following structure:

[libdefaults]
default_realm = YOURDOMAIN.COM
udp_preference_limit = 1
[realms]
YOURDOMAIN.COM = {
kdc = kdc.yourdomain.com
default_domain = yourdomain.com

16

VMware, Inc.

Chapter 2 Using the PowerShell Plug-In

}
[domain_realms]
.yourdomain.com=YOURDOMAIN.COM
yourdomain.com=YOURDOMAIN.COM

NOTE The Kerberos authentication requires a Fully Qualified Domain Name (FQDN) host address.
IMPORTANT When you add or modify the krb5.conf file, you must restart the Orchestrator server service.

Add a PowerShell Host

You can run a workflow to add a PowerShell host and configure the host connection parameters. You can set
up a connection to a remote or a local PowerShell host.
Procedure
1

Log in to the Orchestrator client as an administrator.

Click the Workflows view in the Orchestrator client.

In the workflows hierarchical list, select Library > PowerShell > Configuration and navigate to the Add
a PowerShell host workflow.

Right-click the Add a PowerShell host workflow and select Start workflow.

In the Name text box, type the name of the host.

In the Host / IP text box, type the address of the host.

NOTE The Kerberos authentication requires a Fully Qualified Domain Name (FQDN) host address.

(Optional) In the Port text box, type the port of the host.

Select the PowerShell host type that the plug-in connects to.
a

Select a transport protocol.

NOTE If you use the HTTPS transport protocol, the certificate of the remote PowerShell host is
imported into the Orchestrator keystore.

Select the authentication type.

IMPORTANT If you want to use Kerberos authentication, you must enable it on the WinRM service.

10

Select the type of session mode that the plug-in uses to connect to the PowerShell host.
Option

Description

Shared Session

The plug-in uses shared credentials to connect to the remote host. You must
provide the PowerShell host credentials for the shared session.

Per User Session

The Orchestrator client retrieves credentials from the user who is logged in.

Click Submit to run the workflow.

After the workflow runs successfully, the PowerShell host appears in the Inventory view.

VMware, Inc.

17

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Running PowerShell Scripts

You can run workflows to invoke an external or custom script on a PowerShell host.

Invoke a PowerShell Script

You can run an existing or custom PowerShell script on a host in the plug-in's inventory.
Prerequisites
n

Verify that you are logged in to the Orchestrator client as an administrator.

Verify that you have a connection to a PowerShell host from the Inventory view.

Procedure
1

Click the Workflows view in the Orchestrator client.

In the workflows hierarchical list, select Library > PowerShell and navigate to the Invoke a PowerShell
script workflow.

Right-click the Invoke a PowerShell script workflow and select Start workflow.

Select a PowerShell host on which to run the scrpt.

In the Script text box, type or paste the PowerShell script that you want to run.

Click Submit to run the workflow.

Invoke an External Script

You can run an external PowerShell script on a host in the plug-in's inventory.
External PowerShell scripts are contained in .ps1 files. The .ps1 file that you want to run must be located on
the PowerShell host.
Prerequisites
n

Verify that you are logged in to the Orchestrator client as an administrator.

Verify that you have a connection to a PowerShell host from the Inventory view.

Verify that you have acces to other .ps1 files that the script might reference.

Procedure
1

Click the Workflows view in the Orchestrator client.

In the workflows hierarchical list, select Library > PowerShell and navigate to the Invoke an external
script workflow.

Right-click the Invoke an external script workflow and select Start workflow.

Select a PowerShell host on which to run the scrpt.

In the Name text box, type the filename of the external .ps1 script that you want to run.
NOTE If the .ps1 file is not in the default folder, you must type the absolute filepath. You can use system
environment variables to specify script paths. For example, $env:HOMEPATH\test1.ps1.

In the Arguments text box, type the script arguments.

The valid syntax is the same as that used in the PowerShell console.

18

Click Submit to run the workflow.

VMware, Inc.

Chapter 2 Using the PowerShell Plug-In

Generating Actions
You can run workflows to generate actions based on a PowerShell script or a PowerShell cmdlet. You can use
the generated actions as building blocks for custom workflows.

Generate an Action from a PowerShell Script

You can run a workflow to generate an action from a PowerShell script that you provide. You can optionally
generate a sample workflow that can run the generated action.
You can customize the script of the action that you generate by using placeholders. For each placeholder, the
workflow creates a corresponding action parameter of type string in the generated action. When you run the
action, you can provide an actual value as the action parameter. The value that you provide replaces the
placeholder.
Prerequisites
n

Verify that you are logged in to the Orchestrator client as an administrator.

Verify that you have a connection to a PowerShell host from the Inventory view.

Procedure
1

Click the Workflows view in the Orchestrator client.

In the workflows hierarchical list, select Library > PowerShell > Generate and navigate to the Generate
an action from a PowerShell script workflow.

Right-click the Generate an action from a PowerShell script workflow and select Start workflow.

In the Script text box, type or paste the PowerShell script from which to generate the action.
NOTE You can use {#ParamName#} as a placeholder for user input. If the placeholder is of type string, you
must use double quotes to pass the value of the placeholder to the action.
The following script is an example of how to link the generated action parameter to a script parameter.
param($name={#ParamName#})
echo $name;

In the Name text box, type a name for the action that you want to generate.

Select an existing module in which to generate the action.

Select whether to generate a workflow.

Option

Description

Yes

Generates a sample workflow that can run the generated action. You must
select a folder in which to generate the workflow.
NOTE The name of the generated workflow consists of the predefined string
Invoke Script and the name of the generated action.

No

A sample workflow is not generated.

Click Submit to run the workflow.

What to do next
You can integrate the generated action in custom workflows.

VMware, Inc.

19

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Generate an Action for a PowerShell Cmdlet

You can run a workflow to generate an action for a PowerShell cmdlet and parameter set that you provide.
With this action, you can use PowerShell functionality in Orchestrator. You can optionally generate a sample
workflow that can run the generated action.
You can use a large set of data types with the PowerShell script engine. The data types that you can use include
primitive types such as Integer, Boolean, Char, any type available from the .NET assembly, or user-defined
types. When generating actions based on PowerShell cmdlet definitions, the input and output cmdlet
parameters are represented by types that the Orchestrator platform supports. The PowerShell plug-in defines
the type mappings. In general, primitive types are mapped to the corresponding Orchestrator types, and
complex types are represented by the PowerShellRemotePSObject object.
Prerequisites
n

Verify that you are logged in to the Orchestrator client as an administrator.

Verify that you have a connection to a PowerShell host from the Inventory view.

Procedure
1

Click the Workflows view in the Orchestrator client.

In the workflows hierarchical list, select Library > PowerShell > Generate and navigate to the Generate
an action for a PowerShell cmdlet workflow.

Right-click the Generate an action for a PowerShell cmdlet workflow and select Start workflow.

Select a PowerShell cmdlet to run when using the action that you generate.

Select a parameter set for the cmdlet.

The parameter set definition values appear in the Parameter set definition text box.
NOTE You cannot modify the parameter set definition values by editing the string in the Parameter set
definition text box. You can review the string for information about the parameters that the parameter
set contains.

In the Name text box, type a name for the action that you want to generate.

Select an existing module in which to generate the action.

Select whether to generate a workflow.

Option

Description

Yes

Generates a sample workflow that can run the generated action. You should
select a folder in which to generate the workflow.
NOTE The name of the generated workflow consists of the predefined string
Execute Cmdlet and the name of the generated action.

No

A sample workflow is not generated.

Click Submit to run the workflow.

What to do next
You can integrate the generated action in custom workflows.

20

VMware, Inc.

Chapter 2 Using the PowerShell Plug-In

Passing Invocation Results Between Actions

The PowerShell plug-in supports passing of results as parameters from one PowerShell script invocation to
another. To pass results correctly, both invocations must happen in the same session.

PowerCLI Integration with the PowerShell Plug-In

You can use functionality that is available in a third-party snap-in, such as VMware vSphere PowerCLI, with
the PowerShell plug-in.
To use the third-party snap-in functionality, the snap-in must be available on the PowerShell host. To load the
snap-in in the current session, you must also call the AddPsSnapin action. When using PowerCLI, you must set
the name of the snap-in to VMware.VimAutomation.Core.
The PowerShell plug-in does not provide pre-generated actions for third-party snap-ins. You can generate
actions for third-party snap-ins by running the Generate an action for a PowerShell cmdlet workflow. See
Generate an Action for a PowerShell Cmdlet, on page 20.
The com.vmware.library.powershell.converter package contains basic building blocks that allow conversion
from a vCO VC:<SomeObjectType> object, to the corresponding object from PowerCLI. This feature allows
workflows from the vCenter Server plug-in to interact with workflows from the PowerShell plug-in and to
pass parameters between the two plug-ins.

Converter Workflows
You can use the sample workflows from the Converter workflow category to test the integration between the
PowerShell plug-in and PowerCLI. To test the integration, PowerCLI must be installed on the PowerShell host.
The Converter sample workflows demonstrate the conversion functionality available in the plug-in.
NOTE The PowerShell plug-in does not support all types that are available in PowerCLI and the vCenter Server
plug-in. Unsupported types return an exception.
You can access these workflows from Library > PowerShell > Samples > Converter on the Workflows view
in the Orchestrator client.
Workflow Name

Description

Convert PSObject to vCO object

Converts PowerShellRemotePSObject to VC:<SomeObjectType>.

Convert PSObject to vCO object to PSObject

Converts PowerShellRemotePSObject to VC:<SomeObjectType> and the

reverse.

Convert vCO object to PSObject

Converts VC:<SomeObjectType> to PowerShellRemotePSObject.

Sample Workflows
The Samples workflow category contains workflows that allow you to test basic use cases.
You can access these workflows from Library > PowerShell > Samples on the Workflows view in the
Orchestrator client.
Workflow Name

Description

Invoke a script via API

Demonstrates how to call a PowerShell script through the available scripting API.

List directory content

Lists the contents of a directory.

Pipeline execution example

Demonstrates how you can run multiple cmdlets arranged into a pipe.

Toggle virtual machine state

Toggles the power state of a virtual machine.

VMware, Inc.

21

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Access the PowerShell Plug-In API

Orchestrator provides an API Explorer to allow you to search the PowerShell plug-in API and see the
documentation for JavaScript objects that you can use in scripted elements.
Procedure
1

Log in to the Orchestrator client as an administrator.

Access the API Explorer from either the Orchestrator client or from the Scripting tabs of the workflow,
policy, and action editors.

To access the API Explorer from the Orchestrator client, click Tools > API Explorer in the Orchestrator
client toolbar.

To access the API Explorer from the Scripting tabs of the workflow, policy, and action editors, click
Search API on the left.

To expand the hierarchical list of PowerShell plug-in API objects, double-click the PowerShell module in
the left pane.

What to do next
You can copy code from API elements and paste it into scripting boxes. For more information about API
scripting, see Developing with VMware vCenter Orchestrator.

Working with PowerShell Results

You can use objects from the API of the PowerShell plug-in to work with results that Windows PowerShell
returns.
You can use the methods from the PowerShellInvocationResult class to get information about a script that
you run.
Method

Description

getErrors()

Returns a list of errors reported by the PowerShell engine during script invocation.

getInvocationState()

Status of the script. The possible values are Completed or Failed.

getHostOutput()

Output of the script as it appears on the PowerShell console.

getResults()

Objects returned by the PowerShell engine. The returned object is of type

PowershellRemotePSObject.

PowershellRemotePSObject is a remote representation of objects returned by the PowerShell engine.

PowershellRemotePSObject contains XML serialization of the result that can be accessed by calling the
getXml() method.

The PowerShell plug-in also provides an object model that wraps the XML result and provides easier access
to particular object properties. The getRootObject() method provides access to the object model. In general,
the getRootObject() method maps the PowerShell types to types available in Orchestrator, by using the
following rules.

22

If the returned object is of a primitive PowerShell type, the object is mapped to the corresponding
Orchestrator primitive type.

If the returned object is of type collection, the object is represented as ArrayList.

If the returned object is of type dictionary, the object is represented as Hashtable.

If the returned object is of type complex, the object is represented as PSObject.

VMware, Inc.

Chapter 2 Using the PowerShell Plug-In

Examples of Scripts for Common PowerShell Tasks

You can cut, paste, and edit the JavaScript examples to write scripts for common PowerShell tasks.
For more information about scripting, see the vCenter Orchestrator Developer's Guide.

Example: Run a PowerShell Script Through the API

You can use JavaScript to run a PowerShell script through the API of the plug-in.
This example script performs the following actions.
n

Opens a session to a PowerShell host.

Provides a script to run.

Checks invocation results.

Closes the session.

var sess;
try {
//Open session to PowerShell host
var sess = host.openSession()
//Set executed script
var result = sess.invokeScript('dir')
//Check for errors
if (result.invocationState == 'Failed'){
throw "PowerShellInvocationError: Errors found while executing script \n" +
result.getErrors();
}
//Show result
System.log( result.getHostOutput() );
} catch (ex){
System.error (ex)
} finally {
if (sess) {
//Close session
host.closeSession( sess.getSessionId() );
}
}

Example: Work with Result

You can use JavaScript to work with the result of a PowerShell script run.
This example script performs the following actions.
n

Checks the invocation state.

Extracts a value from the result.

Checks the RemotePSObject type.

var sess = host.openSession()

sess.addCommandFromString("dir " + directory)
var invResult = sess.invokePipeline();
//Show result
System.log( invResult.getHostOutput() );

VMware, Inc.

23

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

//Check for errors

if (invResult.invocationState == 'Failed'){
System.error(invResult.getErrors());
} else {
//Get PowerShellRemotePSObject
var psObject = invResult.getResults();
var directories = psObject.getRootObject();
var isList = directories instanceof Array
if ( isList ){
for (idx in directories){
var item = directories[idx];
if ( item.instanceOf('System.IO.FileInfo') ){//Check type of object
System.log( item.getProperty('FullName') );//Extract value from result
}
}
} else {
System.log( directories.getProperty('FullName') );//Extract value from result
}
}
host.closeSession( sess.getSessionId());

Example: Connect with Custom Credentials

You can use JavaScript to connect to a PowerShell host with custom credentials.
var sess;
try {
sess = host.openSessionAs(userName, password);
var invResult = sess.invokeScript('$env:username');
//Check for errors
if (invResult.invocationState == 'Failed'){
System.error(invResult.getErrors());
} else {
//Show result
System.log( invResult.getHostOutput() );
}
} catch (ex){
System.error (ex)
} finally {
if (sess) {
host.closeSession( sess.getSessionId());
}
}

24

VMware, Inc.

Chapter 2 Using the PowerShell Plug-In

Troubleshooting
If you encounter problems when running or using PowerShell plug-in, you can use a troubleshooting topic to
understand and solve the problem, if there is a workaround.

Servers Not Found in Kerberos Database

After you add servers with Kerberos authentication, the servers might not be found because they are not added
correctly.
Problem
When you try to connect to a server, the server is not found in Kerberos database.
No valid credentials provided (Mechanism level: No valid
credentials provided (Mechanism level: Server not found in Kerberos
database (7)))

Cause
This error might be caused by domain or mapping problems, or because of a DNS problem where the service
principal name is not built correctly. Kerberos authentication does not workwhen the destination is an IP
address.
Solution
When you add a PowerShell host using the Kerberos authentication type a DNS or NetBIOS destination.

Unable to Obtain a Kerberos Ticket

When you provide wrong credentials, the plug-in fails to obtain a Kerberos ticket.
Problem
You are unable to add a host to the plug-in's inventory and the result is the following error message.
Pre-authentication information was invalid (24)

Cause
You have provided wrong credentials.
Solution
Provide the correct credentials.

Kerberos Authentication Fails Due to Time Differences

System time differences in the environment that uses Kerberos configuration might lead to authentication
failure.
Problem
Attempts to use Kerberos for initial authentication of a host or for resource access fail and the following error
message appears.
Clock Skew

Cause
If the system time on the computers in the environment deffers with more than 5 minutes from the client
computer or from one another, the Kerberos authentication fails.

VMware, Inc.

25

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

Solution
Synchronize the system times in the environment.

Kerberos Authentication Session Mode Fails

When you use Kerberos authentication with Shared Session or Session per User, adding the PowerShell host
might fail.
Problem
When you attempt to add a PowerShell host to the plug-in's inventory using Shared Session or Session per
User, the workflow fails, and the following error appears.
Null realm name (601) - default realm not specified (Dynamic Script Module name :
addPowerShellHost#16)

Cause
The default realm is not specified in the Kerberos configuration file krb5.conf neither provided as a part of the
user name.
Solution
Provide a default realm in your Kerberos configuration file or specify the realm in your user name when
authenticating Kerberos.

Unable to Reach a Key Distribution Center for a Realm

Any misspelling in the krb5.conf file might cause a failure when you add a host.
Problem
When you are adding a host, the Kerberos authentication is unable to reach a Key Distribution Center (KDC)
for yourrealm.
Cannot get kdc for realm YOURREALM.COM

Cause
The libdefaults and realms sections in the krb5.conf file might be misspelled.
Solution
Verify that the libdefaults and realms sections in your krb5.conf file are spelled correctly.

26

VMware, Inc.

Index

A
action generation 19
adding a PowerShell host 17
API, working with results 22
API access 22
audience 5
authentication, Kerberos 16

C
communication protocol support 11
components 9
configuration 16

E
external script, call 18

F
functional prerequisites 13

G
Generate an action for a PowerShell cmdlet 20
Generate an action from a PowerShell script 19

H
host
configure 16
manage 16

I
installation 13
installation process 13
introduction 9
Inventory 15
invocation result passing 21
Invoke a PowerShell script 18
Invoke an external script 18

O
Orchestrator 10

PowerShell host
adding 17
registering 17
PowerShell scripts
invoke 18
run 18
prerequisites 13

R
registering a PowerShell host 17

S
script, call 18
scripting examples 23
supported communication protocols 11

T
troubleshooting
Kerberos aauthentication 25
Kerberos authentication 25, 26
Key Distribution Center 26
servers not found 25
ticket 25
time difference 25
Troubleshooting
Kerberos Authentication 26
Shared Session 26

U
updated information 7
usage 15

W
Windows PowerShell 10
WinRM
HTTP configuration 11
HTTPS configuration 12
workflows
configuration 16
Converter 21
sample 21

passing invocation results between actions 21

PowerCLI integration 21
PowerShell 10

VMware, Inc.

27

Using the vCenter Orchestrator Plug-In for Microsoft Windows PowerShell 1.0.x

28

VMware, Inc.