Developing Remote Plug-ins with the

vSphere Client SDK

Update 2
Modified 20 June 2019
VMware vSphere 6.7
vSphere Client SDK 6.7
Developing Remote Plug-ins with the vSphere Client SDK

You can find the most up-to-date technical documentation on the VMware website at:

https://docs.vmware.com/

If you have comments about this documentation, submit your feedback to

docfeedback@vmware.com

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

©
Copyright 2018, 2019 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc. 2
 Contents

About This Book 6

Revision History 7

1 About the vSphere Client SDK 8

Knowledge Requirements for Using the vSphere Client SDK 8
SDK Version Compatibility 9
Overview of Remote Plug-in Architecture 9
vSphere Client SDK Contents 9
Where To Get the vSphere Client SDK 10

2 Using the vSphere Client Remote Plug-in Sample 11

About the Remote Plug-in Sample 11
Components in the Remote Plug-in Sample 12
Build the vSphere Client Remote Plug-in Sample 13
Find the SSL Thumbprint and GUID of vCenter Server 14
Find the SSL Thumbprint of the Remote Plug-in Server 15
Register the vSphere Client Remote Plug-in Sample 16
Viewing the vSphere Client Remote Plug-in Sample 18
Remote Plug-in Sample Directory Structure 27

3 Remote Plug-in Architecture in the vSphere Client 32

Components of the vSphere Client Architecture 32
vCenter Server Configurations 33
Communication Paths in Remote Plug-in Architecture 34
Communications Among UI Components in the vSphere Client 35
Client-Server Communications with Remote Plug-ins 37
Security Concepts for Remote Plug-ins 37

4 Creating a Remote Plug-in for the vSphere Client 38

Code Components to Create a Remote Plug-in for the vSphere Client 38
Deployment Requirements for a Remote Plug-in for the vSphere Client 39
vSphere Client Plug-in Registration Tool 39
Sample Manifest File for a Remote Plug-in 40

5 Deploying Remote Plug-ins for the vSphere Client 42

Remote Plug-in Life Cycle 42
Remote Plug-in Discovery by the vSphere Client 43

VMware, Inc. 3
Developing Remote Plug-ins with the vSphere Client SDK

Plug-In Caching 44
Remote Plug-in Deployment 45
Remote Plug-in Topologies 45
Remote Plug-in Terminology 45
Visibility of Remote Plug-in Views 45
Remote Plug-in Multi-Instance Support 46
Differentiating Plug-in Instances 47
Remote Plug-in Deployment Example with Simultaneous Users 48
Remote Plug-in Multi-Version Support 57

6 Choosing Extension Points for vSphere Client Plug-ins 59

Types of Extension Points in the vSphere Client 59
Remote Plug-in Manifest Example 61
Extension Points in the vSphere Client 63

7 vSphere Client Plug-in User Interface Modules 64

Bootstrapping the JavaScript API 64
vSphere Client JavaScript API: htmlClientSdk Interface 65
vSphere Client JavaScript API: Modal Interface 65
vSphere Client JavaScript API: Application Interface 66
vSphere Client JavaScript API: Event Interface 69
Example Using the modal API 69

8 Using Themes with vSphere Client Plug-ins 71

Using Style Variables in Plug-In CSS 71
Building Output Style Sheets for vSphere Client Plug-Ins 73
Configuring and Loading Theme Style Sheets in vSphere Client Remote Plug-Ins 75

9 Remote Plug-in Server Considerations for the vSphere Client 78

Communication Paths for Authentication in the Remote Plug-in Server 78
vSphere Authentication in the Remote Plug-in Server 79
Response Codes to session/clone-ticket Request 81

10 Additional Resources 82

11 Troubleshooting Remote Plug–ins for the vSphere Client 83

Plug-in Does Not Appear in vSphere Client 83
Wrong Plug-in URL 84
Troubleshooting: Plug-in Thumbprint Incorrect 85
Manifest Cannot Be Parsed 86
Wrong Plug-in Type 86

VMware, Inc. 4
Developing Remote Plug-ins with the vSphere Client SDK

Plug-in Marked As Incompatible 87

Plug-in Registered with Incompatible Version 88
Plug-in View is missing in the vSphere Client 88
Missing Entry in the Instance Selector 89
Unable to Change Plug-in Manifest File 89
OSGi Deployment Failure 89
Troubleshooting: Problems with Registration Script in SDK 90
Plug-in Already Registered 90
Unable To Unregister Plug-in 91

VMware, Inc. 5
About This Book

Developing Remote Plug-ins with the vSphere Client SDK provides information about developing and
deploying HTML-5 extensions to the vSphere Client user interface.

VMware provides many APIs and SDKs for different applications and goals. This documentation provides
information about the extensibility framework of the vSphere Client for developers who are interested in
extending the Web application with custom functionality.

Intended Audience
This information is intended for anyone who wants to extend the vSphere Client with custom functionality.
Users typically are software developers who use HTML and JavaScript to create graphical user interface
components that work with VMware vSphere®.

VMware Technical Publications Glossary

VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For
definitions of terms as they are used in VMware technical documentation, go to http://www.vmware.com/
support/pubs.

VMware, Inc. 6
Revision History

This book, Developing Remote Plug-ins with the vSphere Client SDK, is updated with each release of the
product or when necessary.

This table provides the update history of Developing Remote Plug-ins with the vSphere Client SDK.

Revision Description

20 JUN 2019 Minor corrections to Troubleshooting chapter.

30 MAY 2019 Minor updates and corrections.

Added Troubleshooting chapter.

11 APR 2019 Changes for vSphere Client SDK 6.7U2 release.

n Replaced Virgo server with Tomcat server.
n Updated JavaScript API to handle UI themes.
n Added chapter about UI themes.
n Added information about plug-in caching.
n Added information about plug-in handling in linked mode.
n Expanded and improved chapter about running remote plug-in sample.
n Improved information about plug-in deployment.

12 FEB 2019 Minor updates and corrections.

Expanded material about Deployment.

16 OCT 2018 Initial release.

VMware, Inc. 7
About the vSphere Client SDK 1
The VMware vSphere® Client provides a means for connecting to VMware vCenter Server® systems and
managing the objects in the vSphere infrastructure. The VMware vSphere Client is an HTML5-based web
application with a modular architecture that supports plug-in extensions. The vSphere Client SDK
provides tools and examples that help you create custom plug-ins to extend the functionality of the
vSphere Client.

This chapter includes the following topics:

n Knowledge Requirements for Using the vSphere Client SDK

n SDK Version Compatibility

n Overview of Remote Plug-in Architecture

n vSphere Client SDK Contents

n Where To Get the vSphere Client SDK

Knowledge Requirements for Using the vSphere Client

SDK
Developing extensions for the vSphere Client by using the vSphere Client SDK, requires familiarity with
HTML and JavaScript for the user interface components. The server components of remote plug-ins can
be written using any technology you choose.

n You can extend the vSphere Client if you have skill with Web application development by using
JavaScript and HTML. You can use any user interface technology to create views for the vSphere
Client user interface layer. The sample provided within the SDK uses Angular, TypeScript, and the
Clarity Design System.

n You can use any coding language you choose for server components. A remote plug-in generally
places these functional requirements on the server components:

n A web server that provides HTML, JavaScript, graphic, and localization resources for the user
interface.

n A custom API that provides controller and model functionality to support the view component.

n Business logic components that establish Web Services API sessions with vCenter Server
instances, and retrieve data to satisfy requests from the view component. The Web Services API
is language agnostic, but requesters often use Java, C#, or Python bindings.

VMware, Inc. 8
Developing Remote Plug-ins with the vSphere Client SDK

SDK Version Compatibility

Remote plug-ins are supported by vSphere 6.7 Update 1 and later versions. Earlier versions of vCenter
Server are incompatible with remote plug-ins.

Overview of Remote Plug-in Architecture

This diagram shows a simplified view of how remote plug-ins fit into the vSphere Client.

Figure 1-1. A Simplified View of Remote Plug-in Architecture

Browser

vSphere Client UI Plug-in UI

2 4 5

static resources static resources

3 HTML, CSS, JS
HTML, CSS, JS

vsphere-ui service

Extension
1 Manifest File
Manager

Other Managed
6 Business Logic
Objects

Web Services API

vCenter Server Plug-in Server

The circled numbers identify the following data paths:

1. The remote plug-in installer registers the plug-in manifest file with the vCenter Server Extension
Manager, by using the Web Services API.

2. A web browser downloads user interface elements of the vSphere Client from the vsphere-ui service in
vCenter Server.

3. The vsphere-ui service downloads and parses the plug-in manifest file to determine where the plug-in
extends the user interface.

4. The browser downloads user interface elements of the plug-in from the plug-in server.

5. The plug-in user interface requests data from the plug-in server.

6. The plug-in server uses the Web Services API to interact with vCenter Server.

For a more detailed look at the architecture of remote plug-ins and their environment, see Chapter 3
Remote Plug-in Architecture in the vSphere Client.

vSphere Client SDK Contents

The vSphere Client SDK contains the following directories to aid plug-in developers.

VMware, Inc. 9
Developing Remote Plug-ins with the vSphere Client SDK

docs n Detailed instructions for setting up IDEs.

n Documentation for JavaScript API used by UI components of plug-ins.

n FAQ with troubleshooting and development advice for plug-in

developers.

libs Run-time libraries for Spring framework and vSphere API RPC.

samples A complete remote plug-in sample that demonstrates both client-side and
server-side modules, as well as accompanying metadata.

tools Scripts to assist with development tasks.

vsphere-ui A complete version of the vSphere Client, both client and server modules.
This directory is not relevant for remote plug-ins.

Where To Get the vSphere Client SDK

You can download the vSphere Client SDK from the VMware {code} landing page. The landing page also
has links to the latest documentation, including release notes.

See the latest landing page at https://code.vmware.com/sdk/client.

VMware, Inc. 10
Using the vSphere Client
Remote Plug-in Sample 2
For an introduction to the vSphere Client Remote Plug-in SDK, you can install and run the remote plug-in
sample. The remote plug-in sample demonstrates a secure, efficient, remote plug-in that was developed
according to recommended practices. The sample illustrates several key features that you can adapt to
develop your own plug-ins.

This chapter assumes that you have access to a vCenter Server instance and a development machine
where you build and run the sample plug-in server.

This chapter includes the following topics:

n About the Remote Plug-in Sample

n Components in the Remote Plug-in Sample

n Build the vSphere Client Remote Plug-in Sample

n Find the SSL Thumbprint and GUID of vCenter Server

n Find the SSL Thumbprint of the Remote Plug-in Server

n Register the vSphere Client Remote Plug-in Sample

n Viewing the vSphere Client Remote Plug-in Sample

n Remote Plug-in Sample Directory Structure

About the Remote Plug-in Sample

The Remote Plug-in sample supports a Global View extension to the vSphere Client. The user interface
component creates a modal dialog and several portlets that extend a vSphere inventory object view.

The user interface code also shows how to:

n Initialize the Client API.

n Retrieve session authentication information and pass it to the plug-in server.

n Perform a data retrieval request to the plug-in server.

n Define a context action for a VirtualMachine object.

The plug-in server code shows how to:

n Respond to a data retrieval or modification request.

n Clone and cache a user session with a vCenter Server.

VMware, Inc. 11
Developing Remote Plug-ins with the vSphere Client SDK

The Remote Plug-in sample does the following actions:

n Creates a global view.

n Opens a modal dialog.

n Authenticates to vCenter Server

n Performs a data retrieval call.

n Creates a relation between a Chassis object and a HostSystem object.

n Creates several views that extend a context object view.

n Defines an action on a VirtualMachine context object.

Components in the Remote Plug-in Sample

The remote plug-in sample in the vSphere Client SDK shows how to design and implement, deploy and
register a remote plug-in. The sample is functionally simple, to focus on displaying the infrastructure
rather than the business logic.

The sample remote plug-in package contains several components:

n The user interface is written in JavaScript and Angular, using Clarity design components to maintain
compatibility with the vSphere Client user interface.

n The sample plug-in server is written in Java, but Java is not a requirement. The server includes the
following:

n In-memory data storage for fictitious Chassis objects.

n Controller logic to handle user interface requests for Chassis objects and vSphere HostSystem
objects.

n Service interfaces for operations on both kinds of objects.

n A library layer to interface to vCenter Server, including logic to handle delegated authentication.

n The plugin.json file specifies the vSphere Client extension points that the plug-in extends.

n The spring-context.xml file contains the Spring bean definitions for the plug-in server.

n The pom.xml file specifies how Maven will install dependencies and build the plug-in deliverable.

n The application.properties file specifies properties that the Spring application server uses to
deploy the plug-in server.

The following diagram illustrates the basic architecture of the remote plug-in sample, when installed in a
simple vSphere environment.

VMware, Inc. 12
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-1. Remote Plug-in Sample Environment

dev-box.example.com vcsa-host.example.com

Log in vSphere Client at:

https://vsca-host.example.com/ui vCenter
Server
Appliance
Browser
Fetch plug-in manifest
and views from:
https://dev-box.example.com:8443/sample-ui

Sample
Plug-in Call vSphere APIs on:
Server https://vcsa.host.example.com/sdk
https://vcsa.host.example.com/api/ui

Register download URL of plugin manifest:

Extension https://dev-box.example.com:8443/sample-ui/plugin.json
Registration
Tool

Build the vSphere Client Remote Plug-in Sample

You deploy the remote plug-in sample with a Maven build directed by the sample's pom.xml file. This
procedure builds the sample and deploys it on the plug-in server.

After you download the vSphere Client SDK, you must build the remote plug-in sample before you can
run it.

Prerequisites

Before building the remote plug-in sample, you must have the following:

n You need Java 8 to compile the code for this sample.

n You need Maven 3 to build the plug-in package.

n You need to download and unzip the SDK. See Chapter 1 About the vSphere Client SDK for
information about the structure of the SDK archive.

Procedure

1 Change to the root directory of the remote plug-in sample.

For example: cd /HD/sdk/html-client-sdk/samples/remote-plugin-sample

2 mvn validate

3 mvn clean install

These steps install the Web Services API library into the local Maven repository, download and build the
sample executable, download the Clarity design system, and build the JAR file that contains the sample
components. The sample is a Spring Boot Application that will start an embedded Tomcat server when
you run the sample in a command shell.

VMware, Inc. 13
Developing Remote Plug-ins with the vSphere Client SDK

What to do next

After you build the remote plug-in sample, you need to run the plug-in server and register the plug-in with
vCenter Server.

Find the SSL Thumbprint and GUID of vCenter Server

Before you start the remote plug-in server, you need to find the thumbprint and the GUID of the vCenter
Server where you want to register the plug-in.

You need to find out the certificate thumbprint and the GUID of a vCenter Server instance.

Prerequisites

vCenter Server must be running while you do this procedure.

Procedure

1 Connect a browser to the vCenter Server.

The URL for vCenter Server looks similar to this: https://vcenter-1.example.com

The browser displays a launch screen, with a small padlock icon in the address field.

2 Click LAUNCH VSPHERE CLIENT (HTML5) and log in to the vSphere Client.

The browser displays the default Hosts and Clusters view.

3 If you connected to a vCenter Server instance in an extended linked mode environment, you must
select the chosen vCenter Server instance in the navigation pane on the left of the vSphere Client
screen.

The URL in the browser address box contains an embedded managed object reference, similar to the
following:

Folder:group-d1:56d373bd-4163-44f9-a872-9adabb008ca9. This is an extended managed object

reference that ends with the GUID of the vCenter Server instance. The GUID is a string of 32
hexadecimal digits, organized in groups of 4, 8, or 12 digits, separated by hyphens.

4 Copy the 32 hexadecimal digits of the GUID, along with the inset hyphens, and save this into a shell
variable or a text file.

You will use the GUID when you start the plug-in server.

5 Click the padlock icon in the browser address field to access a certificate information window.

The browser displays a brief summary of browser properties.

6 Click Details to display more certificate information.

The browser displays full details of the vCenter Server certificate.

7 Scroll through the certificate details to find the SHA1 fingerprint.

The SHA1 fingerprint is a string of 40 hexadecimal digits, usually in pairs separated by spaces or
other non-alphanumeric delimiters.

VMware, Inc. 14
Developing Remote Plug-ins with the vSphere Client SDK

8 Select the SHA1 fingerprint and copy it to a text file.

9 Edit the text file to remove all spaces or other delimiters from the SHA1 fingerprint.

You now have a string of 40 contiguous hexadecimal digits. This is the thumbprint of the vCenter
Server instance.

What to do next

The thumbprint and GUID of the vCenter Server instance are needed to start the remote plug-in server.
You can start the server to determine its certificate thumbprint.

Find the SSL Thumbprint of the Remote Plug-in Server

The remote plug-in sample has an embedded application server with a self-signed certificate that is used
in encrypted communications. The certificate and its thumbprint are stored in a Java keystore file.

To register a remote plug-in with vCenter Server, you need to determine the thumbprint of the plug-in
application server's identity certificate. You use this thumbprint in the arguments to the registration
command.

Prerequisites

n Before you can find the thumbprint of the application server, you must install the SDK and build the
sample code.

n Before you start the application server to find its thumbprint, you need access to its port in the firewall.
The default port number is 8443. You can configure a different port number in the
application.properties file.

Before you can find the thumbprint of the application server, you must install the SDK and build the
sample code.

Procedure

1 In a shell window, change to the root directory of the remote plug-in sample and run the JAR file in
the target directory.

The command to run the plug-in JAR file requires several arguments, including the thumbprint, GUID,
DNS name, and HTTPS port number of the vCenter Server instance. Use a command similar to the
following example, but substitute the details that pertain to your vCenter Server:

java -jar target/remote-plugin-sample-6.7.0.jar \

--vcenter.guid=223b94f2-af15-4613-5d1a-a278b19abc09 \
--vcenter.thumbprint=3fccb81448ca98bbbf2b75dbb3ab199886accb1f \
--vcenter.fqdn=vcenter-1.example.com --vcenter.port=443

The plug-in application server runs. It might take a few minutes to initialize, and the console displays
a number of lines of output. When the server is ready, the console displays two lines saying Tomcat
started and Started SpringbootApplication.

VMware, Inc. 15
Developing Remote Plug-ins with the vSphere Client SDK

2 Connect a browser to the application server, for example, using the URL of the plug-in manifest.

The default URL for the manifest file is https://localhost:8443/sample-ui/plugin.json.

3 Examine the certificate presented by the application server.

The way to examine the certificate depends on the browser. For example, you can view a server
certificate in Firefox by clicking the padlock icon next to the URL, then selecting More Information >
View Certificate. The thumbprint is the field labelled SHA1 Fingerprint.

4 Save the certificate thumbprint to a text file.

If the thumbprint contains colon separators, do not remove them. If the thumbprint contains spaces or
other separators, replace them with colons. If the thumbprint has no separators, insert a colon after
every two digits. This is the format accepted by vCenter Server when you register the plug-in server.

What to do next

Use the application server thumbprint when you register the plug-in with vCenter Server.

Register the vSphere Client Remote Plug-in Sample

Before you can view the remote plug-in sample in the vSphere Client, you must register it with a vCenter
Server instance to which you want to connect. The vSphere Client SDK contains a vCenter Server plug-in
registration tool that registers a plug-in with a vCenter Server ExtensionManager.

You have installed the SDK and you are ready to run the remote plug-in sample.

Prerequisites

Before you register the remote plug-in sample, you must do the following:

n Build the remote plug-in sample.

n If needed, start vCenter Server.

n If needed, change permissions on the plug-in registration tool to allow execute access.

In addition, you need to know the following parameters:

n The host name or IP address of the machine where you are running the sample plug-in server. This
address must be accessible to the vCenter Server instance so that it can download the plug-in
manifest file.

n The port number where the plug-in server receives HTTPS requests. The sample serves port 8443 by
default. The port must be open on the firewall of your development machine and accessible to the
vCenter Server.

n The host name or IP address of the vCenter Server where you want to register the remote plug-in
sample.

n The username and password of a vSphere user that has permission to access the ExtensionManager
on the vCenter Server where you want to register the remote plug-in sample. For example,
administrator@vsphere.local normally has the necessary Extension.Register permission.

VMware, Inc. 16
Developing Remote Plug-ins with the vSphere Client SDK

n The SHA1 thumbprint of the plug-in server, so that vCenter Server can retrieve the plug-in manifest
file.

Note The thumbprint must contain colon separators, unlike the thumbprint format used when
starting the plug-in server. vCenter Server accepts only thumbprints that have a colon between each
pair of characters.

n The version number of the remote plug-in sample.

n The key of the remote plug-in sample, defined in the plug-in manifest. By default, this is
com.vmware.sample.remote.

n The path from the plug-in web server root to the plug-in manifest file. By default, this is /sample-ui/
plugin.json.

For more information about the registration tool, see vSphere Client Plug-in Registration Tool.

Procedure

1 In a command shell, change to the tools/vCenter plugin registration/prebuilt directory.

cd html-client-sdk/tools/*plugin*/prebuilt

The directory contains both an extension-registration.bat script for Windows DOS shells, and an
extension-registration.sh script for Unix or Linux shells.

2 Run the extension-registration script appropriate for your operating system, specifying the
prerequisite parameters.

For a Unix or Linux shell, use this syntax:

./extension-registration.sh -action registerPlugin -remote \

-url https://myvcenter/sdk \
-username administrator@vsphere.local -password mysecret \
-key com.vmware.sample.remote -version 1.0.0 \
-pluginUrl https://mydevbox:8443/sample-ui/plugin.json \
-serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:19:A7:22:A0 \
-c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a sample plug-in'

For a DOS command shell, use this syntax:

./extension-registration.bat -action registerPlugin -remote ^

-url https://myvcenter/sdk ^
-username administrator@vsphere.local -password mysecret ^
-key com.vmware.sample.remote -version 1.0.0 ^
-pluginUrl https://mydevbox:8443/sample-ui/plugin.json ^
-serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:19:A7:22:A0 ^
-c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a sample plug-in'

For a PowerShell prompt, use this syntax:

./extension-registration.bat -action registerPlugin -remote `

-url https://myvcenter/sdk `
-username administrator@vsphere.local -password mysecret `

VMware, Inc. 17
Developing Remote Plug-ins with the vSphere Client SDK

-key com.vmware.sample.remote -version 1.0.0 `

-pluginUrl https://mydevbox:8443/sample-ui/plugin.json `
-serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:19:A7:22:A0 `
-c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a sample plug-in'

Note If the password contains special characters, use the appropriate escaping sequences for your
shell.

The registration script displays a message that the plug-in has been successfully registered
in vCenter.

What to do next

In a web browser, connect to the vCenter Server URL and verify that the remote plug-in displays a Global
View.

Viewing the vSphere Client Remote Plug-in Sample

After you build and register the remote plug-in sample, you can view it in the vSphere Client.

To view the remote plug-in sample, you must run the plug-in server. If the server is not running yet,
change to the root directory of the remote plug-in sample and use a command similar to the following
example, but substitute the details that pertain to your vCenter Server:

java -jar target/remote-plugin-sample-6.7.0.jar \

--vcenter.guid=223b94f2-af15-4613-5d1a-a278b19abc09 \
--vcenter.thumbprint=3fccb81448ca98bbbf2b75dbb3ab199886accb1f \
--vcenter.fqdn=vcenter-1.example.com --vcenter.port=443

To view the plug-in user interface, open a browser window and connect to the vCenter Server instance
where you registered the plug-in. Use the fully qualified domain name of the vCenter Server to match the
server certificate. From the welcome screen you can launch the vSphere Client.

VMware, Inc. 18
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-2. vCenter Server Welcome Screen

After you select LAUNCH VSPHERE CLIENT (HTML5) and authenticate with vCenter Server, the
vSphere Client displays the home page with a vSphere HTML SDK Plugin link in the object navigator
pane on the left. The link leads to the remote plug-in global view.

The plug-in global view includes the following subviews:

n A welcome page is the default page for the global view.

n A settings page allows you to change the number of items displayed in the Chassis List page.

n A Chassis List page displays summary information about the Chassis objects currently in the store.
The Chassis store is initialized with several random Chassis objects for display. On the Chassis List
page you can do the following actions:

n Edit the Chassis object properties in a modal dialog.

n Display related Host objects.

n Display the Monitor subview or the Configure subview.

The code that supports these actions demonstrates how to use a modal dialog, how to create, delete, and
update Chassis objects, and how to make calls to the plug-in server and the vCenter Server. The
following illustrations show some of the features of the global view.

VMware, Inc. 19
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-3. Selecting the Sample Plug-in Global View in the Navigation Pane

The Global View extension point is specified by the following lines from the manifest file, plugin.json:

"global": {
"view": {
"navigationId": "com.vmware.remote.sample.entrypoint",
"uri": "index.html?view=entry-point",
"navigationVisible": false
}
}

The Global View content is specified in the file entry.point.component.html.

VMware, Inc. 20
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-4. Sample Plug-in Global View Welcome Page

Figure 2-5. Sample Plug-in Global View Chassis List Page

Figure 2-6. Sample Plug-in Edit Chassis Dialog

VMware, Inc. 21
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-7. Sample Plug-in Chassis with Related Hosts

In addition to the global view and its subviews, the remote plug-in sample provides portlets that show how
to extend the VirtualMachine vSphere object. You can see the portlets in context in the following
illustrations.

Figure 2-8. Portlet Extending the VirtualMachine Summary View

VMware, Inc. 22
Developing Remote Plug-ins with the vSphere Client SDK

The VirtualMachine Summary View extension point is specified by the following lines from the manifest
file, plugin.json:

"objects": {
"VirtualMachine": {
"summary": {
"view": {
"uri": "index.html?view=vm-portlet",
}
},
...
}
}

Figure 2-9. Portlet Extending the VirtualMachine Monitor View

The VirtualMachine Monitor View extension point is specified by the following lines from the manifest file,
plugin.json:

"objects": {
"VirtualMachine": {
...
"monitor": {
"views": {
"navigationId": "com.vmware.remote.sample.monitor",
"labelKey": "RemoteSample:vm.monitor.view.title",
"uri": "index.html?view=vm-monitor",
}
}
}
}

VMware, Inc. 23
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-10. Portlet Extending the VirtualMachine Configure View

The VirtualMachine Configure View extension point is specified by the following lines from the manifest
file, plugin.json:

"objects": {
"VirtualMachine": {
"configure": {
"views": {
"navigationId": "com.vmware.remote.sample.configure",
"labelKey": "RemoteSample:vm.configure.view.title",
"uri": "index.html?view=vm-congfigure",
}
}
}
}

The remote plug-in sample shows how to add an action item to a context menu for a VirtualMachine
object. You can see how this appears in the following illustration.

VMware, Inc. 24
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-11. Action Added to VirtualMachine Context Menu

The VirtualMachine context menu extension point is specified by the following lines from the manifest file,
plugin.json:

"objects": {
"VirtualMachine": {
"menu": {
"actions": {
"labelKey": "RemoteSample:vm.action.label",
"icon": {
"name": "action-1"
},
"trigger": {
"type"; "modal",
"uri": "index.html?view=vm-action-modal",
"titleKey": "RemoteSample:vm.action.model.title",
"size": {
"width": 600,

VMware, Inc. 25
Developing Remote Plug-ins with the vSphere Client SDK

"height": 250
}
}
}
}
}
}

The remote plug-in sample displays a HostSystem Summary view and a HostSystem Monitor view also.
The Summary view shows the number of related Chassis objects. You click the number to reach the
Monitor view. The Monitor view displays a datagrid listing all available Chassis objects. To create a
relation between a HostSystem and a Chassis object, select the checkbox beside the Chassis object and
click Update.

Figure 2-12. Portlet Extending the HostSystem Summary View

The HostSystem Summary View extension point is specified by the following lines from the manifest file,
plugin.json:

"objects": {
"HostSystem": {
"summary": {
"view": {
"uri": "index.html?view=host-summary"
}
}
}
}

VMware, Inc. 26
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-13. Portlet Extending the HostSystem Monitor View

The HostSystem Monitor View extension point is specified by the following lines from the manifest file,
plugin.json:

"objects": {
"HostSystem": {
"monitor": {
"views": [
{
"navigationId": "hostMonitor",
"labelKey": "host.monitor.view.title",
"uri": "index.html?view=host-monitor"
}
]
}
}
}

Remote Plug-in Sample Directory Structure

The following illustrations show the directory structure of the remote plug-in sample code.

VMware, Inc. 27
Developing Remote Plug-ins with the vSphere Client SDK

Top Level Directory

Figure 2-14. Remote Plug-in Sample Top Level Directory

Table 2-1. Contents of Top Level Directory

Subdirectory Description

remote-plugin-sample/libs The external library (vim25.jar) that needs to be installed as a local dependency during the project
build and deploy process.

remote-plugin-sample/src The root of the plug-in source code. It contains three main subdirectories:
n java
n resources
n ui
Descriptions of these subdirectories follow.

java Directory for Server-Side Code

The server-side code for the remote plug-in sample is written in Java. It contains several packages.

VMware, Inc. 28
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-15. Remote Plug-in Sample Server-Side Directory

Table 2-2. Contents of Server-Side Directory

Subdirectory Description

configuration The Configuration service reads connection properties of vCenter Server, such as FQDN,
thumbprint, port, and GUID, and exposes them to Spring Boot components through public
accessors.

controllers The Controller components have the logic to keep open user sessions to the vCenter Server.

gateway The Session Service interacts with vCenter Server on behalf of the plug-in server. The Session
service authenticates the plug-in server with a clone ticket.

model Object definitions for plug-in server use.

services Services that implement the plug-in server-side business logic.

store In-memory database to store custom data for the plug-in.

vim25 Components that communicate with vCenter Server:

n VimObjectService retrieves data from the vCenter Server, using the Web Services API.
n ThumbprintTrustManager helps to authenticate the remote side of a secure socket, using the
public interface javax.net.ssl.X509TrustManager interface.

SpringBootApplication.java The Spring Boot Application bootstraps, deploys, and runs the plug-in on an embedded Tomcat
application server.

resources Directory
The resources directory of the remote plug-in sample contains application configuration files and a
certificate file for encrypted communications.

VMware, Inc. 29
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-16. Remote Plug-in Sample Resources Directory

Table 2-3. Contents of Resources Directory

Subdirectory Description

application.properties Settings specific to the plug-in server, including port number for incoming HTTPS connections,
context root of the web application, log level setting, and settings pertaining to the keystore.

keystore.jks Java keystore for self-signed certificate of vCenter Server.

spring-context.xml Context configuration for plug-in server Spring application.

static/plugin.json Descriptors for UI components the plug-in adds to the vSphere Client.

ui/src Directory
The ui/src directory of the remote plug-in sample contains the client-side code for the plug-in. The main
source files are in the app subdirectory, which contains an Angular application, including the AppModule,
services, and component files.

VMware, Inc. 30
Developing Remote Plug-ins with the vSphere Client SDK

Figure 2-17. Remote Plug-in Sample ui/src Directory

Table 2-4. Contents of ui/src Directory

Subdirectory Description

app/model Object definitions for plug-in client-side use.

app/services Services that implement the plug-in client-side business logic

app/views UI views (Angular components) that implement the visible functionality of the plug-in. Each view
has its own subdirectory that contains HTML, CSS, and Angular code in separate files.

app/app.component The main component that bootstraps the Angular Application and initializes the htmlClientSdk
service.

app/app-routing.module The routing module of the plug-in client-side application.

index.html Static HTML page that loads by default when the plug-in server context path is loaded. The
index.html page loads htmlClientSkd.js and app.component, which is the entry point of the
Angular application.

VMware, Inc. 31
Remote Plug-in Architecture in
the vSphere Client 3
The vSphere Client remote plug-in architecture is designed to integrate plug-in functionality into the
vSphere Client without the need to run inside vCenter Server. This provides plug-in isolation and enables
scale-out of plug-ins that operate in large vSphere environments.

The remote plug-in architecture provides the following benefits to plug-in developers:

n Your plug-in is protected from interference by unstable or compromised plug-ins loaded in the same
vSphere Client.

n Plug-in compatibility is robust across vCenter Server upgrades.

n An incompatible plug-in does not interfere with vCenter Server operation.

n You can deploy a number of plug-in versions within the same vSphere environment.

n Your remote plug-in user interface needs to communicate with only a single back-end server.

n The topology of deployed plug-ins is well defined and easy to understand. This aids in the process of
troubleshooting a problem with your plug-in.

This chapter includes the following topics:

n Components of the vSphere Client Architecture

n vCenter Server Configurations

n Communication Paths in Remote Plug-in Architecture

n Communications Among UI Components in the vSphere Client

n Client-Server Communications with Remote Plug-ins

n Security Concepts for Remote Plug-ins

Components of the vSphere Client Architecture

The vSphere Client architecture enables administrators to manage vSphere environments of varying
scale and complexity with a single user interface. It supports environments ranging from a single vCenter
Server with an embedded Platform Services Controller to a number of vCenter Server instances in
Enhanced Linked Mode or Hybrid Linked Mode.

VMware, Inc. 32
Developing Remote Plug-ins with the vSphere Client SDK

The user interface component runs in a browser and manages the HTML5 views presented to the user.
The user interface communicates with the vsphere-ui service, requesting HTML and Javascript files and
vSphere inventory data, and authenticating as needed. The user interface also manages a sandbox for
each active plug-in, and provides client library services to the plug-in user interface.

The vsphere-ui service is an OSGi Java application server that runs on every vCenter Server node. The
vsphere-ui service communicates with all of the services provided by vCenter Server and the Platform
Services Controller, by using a variety of API styles and protocols. The vsphere-ui service maintains an
authenticated session connection as a client of each of the services.

The vsphere-ui service also provides REST and Web Sockets APIs to the vSphere Client user interface
running in the browser. The service supports authentication for users of the vSphere Client by redirecting
the browser to a login user interface provided by the VMware vCenter Single Sign-on service running in
the Platform Services Controller.

vCenter Server Configurations

Remote plug-ins can operate in linked mode configurations of vCenter Server as well as in single vCenter
Server instances. These illustrations show the components and communication paths of both kinds of
configuration.

The following illustration shows a single vCenter Server with an embedded Platform Services Controller.

Figure 3-1. vCenter Server with Embedded PSC

Browser
Redirected to
WEBSSO UI vSphere UI

Static Static REST Web

Resources HTTPS Resources APIs Sockets
Loaded Loaded
HTTPS

RHTTP Proxy

WS-Trust
VMware-STSD vsphere-ui
Service Service

PSC REST Others

Services
SOAP

Platform Services
Controller vCenter
Services

vCenter 0
Data Center

VMware, Inc. 33
Developing Remote Plug-ins with the vSphere Client SDK

The following diagram shows three vCenter Server instances configured in Enhanced Linked Mode. The
Platform Services Controller for this group is external to the vCenter Server instances.

Figure 3-2. vCenter Server Instances Configured in Extended Linked Mode

Browser
Redirected to
WEBSSO UI vSphere UI

Static Static REST Web

Resources HTTPS Resources APIs Sockets
Loaded Loaded
HTTPS

RHTTP Proxy RHTTP Proxy

WS-Trust
VMware-STSD vsphere-ui vCenter
Service Service Services

RHTTP
PSC Proxy vCenter 1
REST Others
Services
SOAP

Platform Services
Controller vCenter vCenter
Services Services

vCenter 0 RHTTP
Proxy vCenter 2
Data Center

In a linked mode configuration, the vsphere-ui service handles delegation of requests to the linked
vCenter Server instances, using the same protocols that it uses when communicating with its own
services. From the point of view of the user interface, communications are as simple as in the embedded
configuration.

Communication Paths in Remote Plug-in Architecture

This diagram shows some of the communication paths between a plug-in, its user interface, and the
vCenter Server to which the user interface is connected.

On the front end, the vsphere-ui service downloads and parses the plug-in manifest and serves UI
components to the browser, including references to plug-in components, which are served by the plug-in
server. These paths use simple HTTPS communications.

The back end communication paths between the plug-in server and the vCenter Server Web Services API
use SOAP messages over HTTPS. These communications are described in more detail in Chapter 9
Remote Plug-in Server Considerations for the vSphere Client.

VMware, Inc. 34
Developing Remote Plug-ins with the vSphere Client SDK

Figure 3-3. A Simplified View of Remote Plug-in Architecture

Browser

vSphere Client UI Plug-in UI

2 4 5

static resources static resources

3 HTML, CSS, JS
HTML, CSS, JS

vsphere-ui service

Extension
1 Manifest File
Manager

Other Managed
6 Business Logic
Objects

Web Services API

vCenter Server Plug-in Server

The circled numbers identify the following data paths:

1. The remote plug-in installer registers the plug-in manifest file with the vCenter Server Extension
Manager, by using the Web Services API.

2. A web browser downloads user interface elements of the vSphere Client from the vsphere-ui service in
vCenter Server.

3. The vsphere-ui service downloads and parses the plug-in manifest file to determine where the plug-in
extends the user interface.

4. The browser downloads user interface elements of the plug-in from the plug-in server.

5. The plug-in user interface requests data from the plug-in server.

6. The plug-in server uses the Web Services API to interact with vCenter Server.

Communications Among UI Components in the vSphere

Client
The vSphere Client user interface loads both its own components and the components belonging to the
plug-in user interface. The vsphere-ui service reads the plug-in manifest file to determine where it should
insert plug-in components in the user interface.

The user interface components loaded in the browser are organized as shown in the following diagram.

VMware, Inc. 35
Developing Remote Plug-ins with the vSphere Client SDK

Figure 3-4. User Interface with a Sandboxed Plug-in

Browser
Plug-in IFrame
1 2 3
Plug-in Client Plug-in
vSphere UI
Sandbox Library UI

Paths:

1 Internal JavaScript methods

2 window.postMessage() method in browser

3 Public JavaScript methods

The plug-in user interface operates within its own IFrame, isolated from other plug-ins. The plug-in loads
a copy of the vSphere Client JavaScript API client library, which is its sole connection to other client code.
The plug-in code communicates with the client library code using JavaScript method calls.

The client library communicates with the sandbox component that the vSphere Client provides to
interface with the plug-in UI components. The communication with the sandbox uses the browser's
window.postMessage() API. This makes it possible for the IFrame and its parent window to be loaded
from different origins.

Note In the vSphere 6.7 Update 1 release of the vSphere Client, the IFrame and its parent window
share the same origin. Do not depend on this to remain the same in future releases.

The plug-in sandbox communicates with other components of the vSphere Client user interface by using
internal Javascript APIs.

If the vSphere Client has more than one plug-in active, each plug-in is allocated its own sandbox, and
operates within its own IFrame, as shown in the following illustration.

Figure 3-5. User Interface with Two Plug-ins in Separate Sandboxes

Browser
Plug-in IFrame
1 2 3
Plug-in Client Plug-in
Sandbox Library UI

vSphere UI Plug-in IFrame

2 3
Plug-in Client Plug-in
Sandbox Library UI
1

Paths:

1 Internal JavaScript methods

2 window.postMessage() method in browser

3 Public JavaScript methods

VMware, Inc. 36
Developing Remote Plug-ins with the vSphere Client SDK

In this case, each plug-in UI communicates with its own back-end server.

Client-Server Communications with Remote Plug-ins

Client requests to back-end services are handled in a similar way for plug-in user interface components
and vSphere Client user interface components.

A plug-in sandbox runs outside the plug-in iframe. The sandbox component, along with the rest of the
vSphere Client user interface components, sends requests to the vsphere-ui service of the vCenter
Server instance that the browser connected to. Service requests use REST and Web sockets over
HTTPS. All requests pass through the vCenter Server reverse proxy, which routes them to the correct
server components.

A plug-in user interface sends service requests to the plug-in back end, using any RPC style on top of the
HTTPS transport protocol. All requests pass through the vCenter Server reverse proxy, which routes them
to the plug-in server. The proxy routing is configured at the time the plug-in is installed; it simplifies
dealing with self-signed certificates, and avoids problems with cross-origin resource access.

Security Concepts for Remote Plug-ins

Remote plug-ins typically use the HTTP protocol as a transport for requests, whether using REST or
SOAP requests. Authentication methods vary, depending on the target endpoint.

Client-side sessions with REST endpoints are tracked with a session token passed in a custom HTTP
header. Server-side sessions with SOAP endpoints are tracked with a session cookie.

A plug-in developer can choose what form of authentication suits the plug-in server component. A best
practice is to authenticate by using the session token that the plug-in user interface can get from the client
library.

To authenticate requests to vCenter Server, the plug-in server sends the token to a specific REST
endpoint of the vsphere-ui service. The vsphere-ui service verifies the authenticating token and returns a
session clone ticket. The plug-in server uses the clone ticket with the vSphere Web Services API to obtain
a SOAP session. The authentication process is described in more detail in Chapter 9 Remote Plug-in
Server Considerations for the vSphere Client.

VMware, Inc. 37
Creating a Remote Plug-in for
the vSphere Client 4
This chapter outlines how to create your own remote plug-in for the vSphere Client. The goal is to
illustrate the entire process using simple components. Other chapters deal with some of the steps in more
detail.

To create a remote plug-in, you need both front-end components and back-end components. The front-
end components constitute a user interface based on HTML 5. The back-end components include a web
server and business logic in support of the front end.

For the front end of your plug-in, you can choose any JavaScript-compatible language. The Remote Plug-
in Sample in the vSphere Client SDK uses Angular and Clarity. A best practice is to use Clarity elements
to harmonize with the look and feel of the vSphere Client.

For the back end, you can choose any language and any web server. The SDK samples are written in
Java and built with Maven, but there is no restriction on the language or tools that you use for back-end
development. The SDK samples use Tomcat as a web server because it is bundled with Spring.

This chapter includes the following topics:

n Code Components to Create a Remote Plug-in for the vSphere Client

n Deployment Requirements for a Remote Plug-in for the vSphere Client

n vSphere Client Plug-in Registration Tool

n Sample Manifest File for a Remote Plug-in

Code Components to Create a Remote Plug-in for the

vSphere Client
A remote plug-in for the vSphere Client includes several code components that you create.

To create code for a complete plug-in, you must do the following:

n Choose the extension points here your user interface views will extend the vSphere Client.

n Create front-end views that provide the user interfaces for data access.

n Create back-end controllers that interface between services and user interface views.

n Create models for your logical data objects.

n Create back-end services that translate between data models and the objects in storage that back the
models.

VMware, Inc. 38
Developing Remote Plug-ins with the vSphere Client SDK

Deployment Requirements for a Remote Plug-in for the

vSphere Client
To prepare a remote plug-in for deployment, you must prepare several files and launch some processes.

Deployment of a remote plug-in takes place at run time, but you must make preparations in advance. You
need to do the following to prepare for plug-in deployment:

n Run a web server that provides plug-in components on demand.

n Run your plug-in server binary. The plug-in server runs on a virtual or physical machine of your
choice, but it must be on the same machine as the web server.

n Prepare a plug-in manifest file, plugin.json, that specifies the plug-in components. The manifest file
must be on the same machine as the web server.

n Register your plug-in with a vCenter Server instance. To register, you need the URL and credentials
to access vCenter Server. You also need the certificate thumbprint of your plug-in server and the URL
of your plug-in manifest file. The script arguments are shown in the following example.

./extension-registration.sh -action registerPlugin -remote \

-url https://myvcenter/sdk \
-username administrator@vsphere.local -password mysecret \
-key com.mycompany.myplugin -version 1.0.0 \
-pluginUrl https://mydevbox:8443/myplugin/plugin.json \
-serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:19:A7:22:A0 \
-c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a remote plug-in'

For more information about the plug-in registration script, see vSphere Client Plug-in Registration
Tool

vSphere Client Plug-in Registration Tool

The vSphere Client SDK contains a plug-in registration tool that manages plug-in extension registration
records in the vCenter Server ExtensionManager. The tool registers, unregisters, or updates the
registration record of a plug-in.

Plug-in Registration Script

To register a plug-in, use the script in the SDK: tools/vCenter plugin registration/prebuilt/
extension-registration.sh, which is a wrapper for a Java tool. The registration tool opens a session
with the vCenter Server instance using the VMware Web Services API.

Plug-in Registration Script Syntax

The arguments of the registration script function as follows:

n -action (required) can be one of:

n registerPlugin

VMware, Inc. 39
Developing Remote Plug-ins with the vSphere Client SDK

n updatePlugin

n unregisterPlugin

n isPluginRegistered

n -c or -company is the name of the plug-in vendor.

n -k or -key (required) is an identification string for the plug-in. The plug-in registration record in the
vCenter Server ExtensionManager contains this identification.

n -local (default) is used to register or update a local plug-in. See also -remote.

n -n or -name is a user-friendly identification string for the plug-in.

n -p or -password (required) authenticates the vCenter Server user account. See also -username.

n -pu or -pluginUrl (required to register a plug-in) is the URL of the plug-in manifest served by the
plug-in back end. The path segment of the -pluginUrl must be specified relative to the directory
where you run the plug-in server.

n -remote (required for a remote plug-in) is used to register or update a remote plug-in. See also
-local.

n -s or -summary is a brief description of the plug-in.

n -show or -showInSolutionManager specifies that the plug-in will appear in the Solutions list of the
Administration panel.

n -st or -serverThumbprint (required to register a plug-in) is the SHA1 signature of the plug-in back-
end server certificate. Pairs of digits must be separated by colon separators.

n -u or -username (required) identifies a vCenter Server user account that has permission to write to
the vCenter Server ExtensionManager. See also -password.

n -url (required) is the URL of the /sdk resource of the vCenter Server. Use the fully qualified domain
name of the vCenter Server instance. For example: https://my-vcsa.example.com/sdk

n -v or -version (required) identifies the plug-in version.

Sample Manifest File for a Remote Plug-in

The following sample manifest file contains the minimum elements required for a very simple plug-in.

{
"manifestVersion" : "1.0.0",
"requirements": {
"plugin.api.version": "1.0.0"
},
"configuration": {
"nameKey": "plugin.name",
"icon": {
"name": "main"

VMware, Inc. 40
Developing Remote Plug-ins with the vSphere Client SDK

}
},
"definitions": {
"i18n": {
"locales": ["en-US"],
"definitions": {
"plugin.name": {
"en-US": "Hello World"
}
}
}
},
"global": {
"view": {
"uri": "index.html"
}
}
}

Note The URIs specified in the manifest file are relative to the location of the manifest file itself. That is,
the directory containing plugin.json should be considered the server root directory for plug-in resources.

VMware, Inc. 41
Deploying Remote Plug-ins for
the vSphere Client 5
A remote plug-in must be deployed by the vSphere Client before it can be used. Deployment is the
process of preparing components of vCenter Server to accept communications from the plug-in and to
display plug-in views in the browser.

This chapter includes the following topics:

n Remote Plug-in Life Cycle

n Remote Plug-in Discovery by the vSphere Client

n Plug-In Caching

n Remote Plug-in Deployment

n Remote Plug-in Topologies

Remote Plug-in Life Cycle

Remote plug-in content becomes visible in the vSphere Client user interface after you prepare and
register the plug-in with a vCenter Server instance. The plug-in displays when you connect a browser to
the vSphere Client URL of the vCenter Server instance, or of a vCenter Server linked to the instance
where the plug-in is registered, and log in.

VMware, Inc. 42
Developing Remote Plug-ins with the vSphere Client SDK

A remote plug-in has the following stages in its life cycle:

Build The plug-in developer assembles the resources and builds the package to
implement the plug-in.

Run The plug-in developer starts the back-end server for the plug-in.

Registration The plug-in developer registers the plug-in as a vCenter Server extension.

Discovery vCenter Server discovers the plug-in registration at the time of a trigger
event., such as a user login

Deployment vCenter Server downloads the plug-in manifest file, verifies certification and
compatibility, and configures the reverse proxy to route server requests.

Use The browser downloads plug-in resources from the back-end server into an
iFrame of the vSphere Client user interface, and the plug-in user interface
operates in conjunction with the back-end server.

Uninstallation The developer unregisters the plug-in, and vCenter Server deletes the
routing configuration.

Remote Plug-in Discovery by the vSphere Client

The vSphere Client service checks for new remote plug-ins on the following different events:

n vSphere Client service startup. Any new remote plug-ins registered in the Extension Manager before
this event will be installed and visible in the vSphere Client after the server startup finishes and the
user logs in.

n User login. User login triggers a check for remote plug-ins that were registered after the server was
started. The vSphere Client does not wait for the plug-ins to be fully installed before displaying the
vSphere Client user interface. After the newly discovered remote plug-ins are deployed and ready for
use, the user sees a notification, and a subsequent refresh will display the plug-in in the user
interface. The notification displays as a banner at the top of the vSphere Client window, similar to this
illustration:

VMware, Inc. 43
Developing Remote Plug-ins with the vSphere Client SDK

Figure 5-1. Banner notification that plug-in is installed

n Browser refresh, while in developer mode. To select developer mode, you can set
remote.plugin.updateOnBrowserRefresh=true in webclient.properties. A browser refresh while
logged in to the vSphere Client triggers a check for newly registered remote plug-ins. Similar to user
login, the vSphere Client will not wait for the plug-ins to be fully installed before proceeding. An
additional refresh may be needed after the notification is displayed.

Remote Plugin Uninstallation

Unregistering a plug-in package on vCenter Server causes the vSphere Client service to delete the plug-
in from the environment. A vCenter Server instance discovers plug-in unregistration when the vsphere-ui
service restarts. At that time it removes the plug-in from cache.

Plug-In Caching
When the vSphere Client installs a plug-in, it downloads the plug-in manifest and caches it. The cached
copy is re-used whenever the vsphere-ui process restarts.

After a plug-in has been unregistered, the vsphere-ui service detects the change during its next restart. At
that time, the cached copy of the plug-in manifest is deleted from the cache.

When a plug-in is upgraded, the vsphere-ui service detects the change during the next restart or user
login. At that time, the old plug-in version is undeployed, its cached copy is removed, and the new plug-in
version is deployed.

Note While the process of uninstallation takes place, the vSphere Client UI does not wait for the process
to complete. You might need to refresh the browser window after enough time has elapsed to complete
the uninstallation. The vSphere Client currently does not display notifications after uninstalling remote
plug-ins.

VMware, Inc. 44
Developing Remote Plug-ins with the vSphere Client SDK

Remote Plug-in Deployment

When the vSphere Client discovers a remote plug-in, it schedules the plugin for deployment. vCenter
Server takes the following steps to deploy a remote plugin in the vSphere Client:

n Download the remote plug-in manifest, plugin.json, from the location specified in the ClientInfo
property registered in the ExtensionManager. When you use the extension-registration script provided
in the SDK this is the value of the -pu or -pluginUrl argument. vCenter Server downloads your plug-
in manifest into /etc/vmware/vsphere-ui/vc-packages/vsphere-client-serenity/your_plugin_name-
your_plugin_version.

n Parse the plug-in manifest to determine what views will be shown in the user interface, and at what
extension points.

n Configure the vCenter Server reverse proxy to allow traffic to the remote plug-in server.

After these steps complete, the vSphere Client displays a notification that the remote plugin is deployed.

Remote Plug-in Topologies

Enhanced linked mode (ELM) enables you to manage all linked vCenter Server instances from a single
vSphere Client connected to any one of the linked vCenter Server instances. The way that the vSphere
Client visualizes the vSphere resources on a vCenter Server instance depends on the set of remote plug-
ins installed on that instance. The topology of remote plug-ins is the overall configuration of plug-ins that
determines how the vSphere Client interacts with the resources on different vCenter Server instances.

Remote Plug-in Terminology

The following terms are useful to understand the concepts in this chapter.

n Plug-in - A product that extends the vSphere user interface with additional functionality.

n Plug-in Version - The version of the plug-in specified at the time of registration..

n Plug-in Instance - A plug-in server registered with a vCenter Server instance. The plug-in instance is
defined by the plug-in product, version, and plug-in manifest URL.

n Plug-in UI - The part of the plug-in loaded inside an IFrame within the vSphere Client UI in the
browser.

n Plug-in Server - the back-end process to which the plug-in UI talks.

Visibility of Remote Plug-in Views

In an Extended Linked Mode (ELM) environment, the vSphere Client is capable of loading views from
plug-in instances registered with any of the linked vCenter Server instances. For the following examples,
suppose you are working with three linked vCenter Server instances: VC1, VC2, VC3. You register
instances of plug-in A with VC1 and VC2, but not with VC3.

VMware, Inc. 45
Developing Remote Plug-ins with the vSphere Client SDK

When you log in to a vCenter Server instance, it checks for plug-ins available on other linked vCenter
Server instances. However, plug-in views are visible in your vSphere Client only when appropriate, as
defined by these rules:

n Global views are always present in the vSphere Client, regardless of which linked instance of vCenter
Server you connect to. A plug-in instance selector enables you to choose between plug-in servers.
For example, if you connect to VC3 you can choose between the global views of plug-in A instances
registered with VC1 and VC2.

n The visibility of an object-specific plug-in view depends on which vCenter Server instance manages
the object. When you select an object managed by a given vCenter Server instance, you have access
to object-specific views served by the plug-ins registered with that vCenter Server instance. For
example, if you connect to VC3 and select an object managed by VC1, the vSphere Client displays
the object-specific view served by plug-in A. However, if you connect to VC1 and select an object
managed by VC3, the vSphere Client does not display the object-specific view because VC3 has no
instance of plug-in A registered.

n Plug-in visibility is also limited by version compatibility between the plug-in and your vSphere Client.
For example, suppose you connect to VC3 and select an object managed by VC2, but the instance of
plug-in A registered with VC2 uses a new method not recognized by the older version of the
JavaScript API served by VC3. Your version of the vSphere Client is unable to display the view
served by plug-in A.

Remote Plug-in Multi-Instance Support

The remote plug-in architecture allows for multiple instances of the same remote plug-in to be deployed
within an ELM environment. Instances of a remote plug-in provide distinct server instances that are
completely equivalent in function, as long as they have the same version.

Figure 5-2. One Plug-in instance per vCenter Server

UI

VC1 VC2 VC3

Plug-in A- Plug-in A- Plug-in A-

instance 1 instance 2 instance 3

This topology has three instances of PluginA, such that the first plug-in server is connected to VC1, the
second is connected to VC2, and the third server is connected to VC3. These plug-in servers are
completely equivalent in function: the plug-in manifests that they host and the plug-in specific bits they
execute are identical.

VMware, Inc. 46
Developing Remote Plug-ins with the vSphere Client SDK

Object views will be loaded from the plug-in instance connected with the vCenter Server instance that the
object belongs to. For example, if the plug-in declares a portlet on the VM summary page, then browsing
VMs on VC2 will load the portlet from the second plug-in server, and browsing VMs on VC3 will load the
portlet from the third plug-in server. Calls to the plug-in back end will be routed to the corresponding plug-
in server instance.

Global views, however, will be aggregated in a single global view with an additional instance selector
component that allows the user to choose between the global views of the different instances. A sample
instance selector is shown below:

Figure 5-3. Selector for Single Plug-in Instance per vCenter Server

The instance selector shown above displays three back-end servers that represent the three instances of
PluginA with version 1.0.0. The Plugin Instance column displays the IP address or fully qualified domain
name of each plug-in instance, and the vCenter Server column displays the vCenter Server that each
plug-in instance is connected to. Switching between the items in this drop-down will load the global view
of the remote plug-in with version "1.0.0" from the specified plug-in instance.

Differentiating Plug-in Instances

When the vSphere Client checks the vCenter Server's Extension Manager for new remote plug-ins it also
checks for new instances of a remote plug-in. If the vSphere Client finds two extension registrations in
two different vCenter Server instances such that the extension ID and extension version are the same but
the plug-in manifest URL (ExtensionClientInfo.url) is different, then these two extensions are considered
to be different instances of the same remote plug-in.

For example, consider an ELM environment with three vCenter Server instances. Suppose that the
following extension registration commands are executed:

./extension-registration.sh -action registerPlugin -url https://vc1.example.com/sdk -u

"Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'Remote Plugin Test' -s 'A
test plugin demonstrating plugin instances' -k com.example.remoteplugin.test -pu "https://
pluginserver1.example.com/path/to/plugin.json" -v "1.0.0" -st plugin1_server_thumbprint -
remote

VMware, Inc. 47
Developing Remote Plug-ins with the vSphere Client SDK

./extension-registration.sh -action registerPlugin -url https://vc2.example.com/sdk -u

"Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'Remote Plugin Test' -s 'A
test plugin demonstrating plugin instances' -k com.example.remoteplugin.test -pu "https://
pluginserver1.example.com/path/to/plugin.json" -v "1.0.0" -st plugin1_server_thumbprint -
remote

Both VC1 and VC2 have the same plug-in manifest, and thus the same plug-in server. This is considered
to be a single plug-in instance, registered with two vCenter Server instances.

Now suppose that we register the following extension in VC3:

./extension-registration.sh -action registerPlugin -url https://vc3.example.com/sdk -u

"Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'Remote Plugin Test' -s 'A
test plugin demonstrating plugin instances' -k com.example.remoteplugin.test -pu "https://
pluginserver2.example.com/path/to/plugin.json" -v "1.0.0" -st plugin2_server_thumbprint -
remote

The extension registered in VC3 has the same ID and version as the one registered in VC1 and VC2 but
has a different manifest URL. The next time a user logs in, the vSphere Client will detect that this is a
different instance of the remote plugin with ID com.example.remoteplugin.test, version 1.0.0. The UI will
show the following behavior:

n Object views declared by plug-in instance 2 (registered in VC3) will be shown for the corresponding
objects from VC3. However, the views declared by instance 1 (registered in VC1 and VC2) will be
shown for objects from VC1 and VC2.

n For global views, there will be a single entry point in the object navigator that takes the user to a plug-
in instance selector view where the user will be able to switch between the global views of the two
plugin instances.

Remote Plug-in Deployment Example with Simultaneous Users

After being detected, a remote plug-in will be scheduled for deployment in the vSphere Client. The
deployment of a remote plug-in, on a high level, consists of the following stages:

n vCenter Server downloads the remote plug-in manifest (plugin.json) from the location specified in the
Extension ClientInfo registered in the ExtensionManager. If you use the extension-registration script
provided in the SDK, this is the value of the -pu argument. The plug-in manifest is downloaded to a
file named as follows: /etc/vmware/vsphere-ui/vc-packages/vsphere-client-serenity/
your_plugin_name-your_plugin_version

n vCenter Server parses the plug-in manifest to determine what views will be shown in the UI and
where they will appear.

n vCenter Server configures the VMware reverse HTTP proxy to route plug-in UI traffic to the remote
plug-in server.

After these stages complete successfully, the vSphere Client UI displays a notification message that the
remote plug-in is installed.

VMware, Inc. 48
Developing Remote Plug-ins with the vSphere Client SDK

This example shows in more detail how the deployment process works, in a situation involving three
users simultaneously accessing the data center. The initial state consists of the following:

n Three vCenter Server instances in an ELM environment: vCENTER-0, vCENTER-1, and

vCENTER-2.

n Three users are accessing the data center: Alpha, Blue, and Claire.

n Blue and Claire are already browsing the vSphere UI loaded from vCENTER-0

n Blue is looking at the summary page of VM-1 managed by vCENTER-1.

n Claire is looking at the summary page of VM-2 managed by vCENTER-2.

n Alpha is about to install a plug-in from Example Company.

A B C

VM-1 VM-2

vCenter-0
vCenter-1 vCenter-2
vsphere-ui

1 Alpha installs and configures the back-end server for the ExampleCo plug-in.

VMware, Inc. 49
Developing Remote Plug-ins with the vSphere Client SDK

A B C
install plugin
server
1

VM-1 VM-2

vCenter-0
vCenter-1 vCenter-2
vsphere-ui

‘ExampleCo’
Plugin Server

2 Alpha registers the ExampleCo plug-in with the vCENTER-1 ExtensionManager using Example
Company's plug-in installer.

install plugin A B C
server
1

register plugin
2

Plugin Installer

VM-1 VM-2

vCenter-0
vCenter-1 vCenter-2
vsphere-ui

‘ExampleCo’
Plugin Server

3 Alpha logs in to the vSphere UI connected to vCENTER-0.

VMware, Inc. 50
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

Plugin Installer
3 login

VM-1 VM-2

vCenter-0
vCenter-1 vCenter-2
vsphere-ui

‘ExampleCo’
Plugin Server

4 Alpha's successful login triggers the vsphere-ui service to contact the ExtensionManager of each
vCenter Server instance to discover new plug-in registrations.

install plugin A B C
server
1

register plugin
2

Plugin Installer
3 login

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui

‘ExampleCo’
Plugin Server

VMware, Inc. 51
Developing Remote Plug-ins with the vSphere Client SDK

5 The vsphere-ui service discovers the new ExampleCo plug-in registered with vCENTER-1.

install plugin A B C
server
1

register plugin
2

Plugin Installer
3 login

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui
5 5
Yes: No
‘ExampleCo’ 4

No 5

‘ExampleCo’
Plugin Server

6 The vsphere-ui service downloads the plug-in manifest JSON of the ExampleCo plug-in from its back-
end server.

VMware, Inc. 52
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

Plugin Installer
3 login

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 vsphere-ui 4
5 5
Yes: No
‘ExampleCo’ 4 6

get plugin.json
No 5 plugin
manifest 6

‘ExampleCo’
Plugin Server

Alpha has completed the login and has loaded the vSphere Client UI, which displays the home
screen of the vSphere Client.

7 The vsphere-ui service sends notifications to all vSphere Client users (Alpha, Blue, and Claire). Each
user sees a blue notification banner at the top of the screen.

VMware, Inc. 53
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

Plugin Installer
new plugin
7 7 7
notification
login 3

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui
5 5
Yes: No
‘ExampleCo’ 4 6

get plugin.json
No 5 plugin
manifest 6

‘ExampleCo’
Plugin Server

Note Depending on timing, it is possible that the vsphere-ui service reads the ExampleCo manifest
before Alpha loads the vSphere Client UI. In this case, Alpha immediately sees the plug-in, and does
not see a notification.

8 When Alpha refreshes the vSphere Client UI in the browser, the ExampleCo plug-in is loaded. The
portlet adds a home menu item and a shortcut link.

VMware, Inc. 54
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

Plugin Installer
7 refresh new plugin 7
7
notification
8 browser
login 3

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui
5 5
Yes: No
‘ExampleCo’ 4 6

get plugin.json
No 5 plugin
manifest 6

‘ExampleCo’
Plugin Server

9 When Blue refreshes the vSphere Client UI in the browser, the ExampleCo plug-in is loaded for this
user. The plug-in adds a portlet on the summary page of VMs. Because VM-1 is managed by
vCENTER-1, which has the ExampleCo plug-in registered, Blue sees the newly added portlet.

VMware, Inc. 55
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

refresh 9
Plugin Installer browser
7 refresh new plugin 7
7
notification
8 browser
login 3

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui
5 5
Yes: No
‘ExampleCo’ 4 6

get plugin.json
No 5 plugin
manifest 6

‘ExampleCo’
Plugin Server

10 When Claire refreshes the vSphere Client UI in the browser, the ExampleCo plug-in can now be loaded
for this user. However, Claire is looking at VM-2, which is managed by vCENTER-2. Because vCENTER-2
does not have the ExampleCo plug-in registered, Claire does not see the newly added portlet.

VMware, Inc. 56
Developing Remote Plug-ins with the vSphere Client SDK

install plugin A B C
server
1

register plugin
2

refresh 9
Plugin Installer browser refresh
7 refresh new plugin 10
7 7 browser
notification
8 browser
login 3

VM-1 VM-2

new plugin? vCenter-0 new plugin?

vCenter-1 vCenter-2
4 4
vsphere-ui
5 5
Yes: No
‘ExampleCo’ 4 6

get plugin.json
No 5 plugin
manifest 6

‘ExampleCo’
Plugin Server

If Claire later navigates to a VM on vCENTER-1, the vSphere Client will display the portlet added by the
ExampleCo plug-in.

Remote Plug-in Multi-Version Support

Unlike local plug-ins, the remote plug-in architecture allows for co-existence of remote plug-ins with the
same ID but different versions.

Consider an ELM environment with three vCenter Server instances and the following plug-in registrations:

./extension-registration.sh -action registerPlugin -url https://vcenter-ip-or-fqdn-of-vc1/sdk

-u "Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'ExampleCo' -s 'A test
plugin demonstrating plugin instances' -k com.example.exampleco -pu "https://my-remote-
plugin-server-version-1/path-to/plugin.json" -v "1.0.0" -st plugin_server_1_thumbprint -
remote

./extension-registration.sh -action registerPlugin -url https://vcenter-ip-or-fqdn-of-vc2/sdk

-u "Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'ExampleCo' -s 'A test
plugin demonstrating plugin instances' -k com.example.exampleco -pu "https://my-remote-
plugin-server-version-2/path-to/plugin.json" -v "2.0.1" -st plugin_server_2_thumbprint -
remote

VMware, Inc. 57
Developing Remote Plug-ins with the vSphere Client SDK

./extension-registration.sh -action registerPlugin -url https://vcenter-ip-or-fqdn-of-vc3/sdk

-u "Administrator@vsphere.local" -p 'Admin!23' -c 'Example, Inc.' -n 'ExampleCo' -s 'A test
plugin demonstrating plugin instances' -k com.example.exampleco -pu "https://my-remote-
plugin-server-version-3/path-to/plugin.json" -v "3.2.0" -st plugin_server_3_thumbprint -
remote

These commands register three extensions (one in each of the three vCenter Servers) with the same ID
(com.example.exampleco) but different versions - version 1.0.0 on VC1, version 2.0.1 on VC2 and
version 3.2.0 on VC3. These are three different versions of the remote plug-in with ID
com.example.exampleco. When you log in to the UI you will see the following:

n Object views declared by plug-in com.example.exampleco version 1.0.0 will be shown on applicable
objects from VC1. Calls to the plug-in back-end server will be routed to the plug-in server dedicated to
version 1.0.0 of the plugin.

n Object views declared by plug-in com.example.exampleco version 2.0.1 will be shown on applicable
objects from VC2. Calls to the plug-in back-end server will be routed to the plug-in server dedicated to
version 2.0.1 of the plug-in.

n Object views declared by plug-in com.example.exampleco version 3.2.0 will be shown on applicable
objects from VC3. Calls to the plug-in back-end server will be routed to the plug-in server dedicated to
version 3.2.0 of the plug-in.

n There will be a single entry point in the object navigator that will take the user to a plug-in instance/
version selector view where the user will be able to switch between the global views of the different
versions and instances of the remote plug-in.

VMware, Inc. 58
Choosing Extension Points for
vSphere Client Plug-ins 6
The vSphere Client supports adding content at key extension points in the user interface. A plug-in
developer can insert custom views that present objects and functions not provided by vSphere.

The available extension points closely follow the navigation experience in the vSphere Client, which
facilitates a clear mapping of a plug-in to the views and workflows it owns. The extension points operate
at a high level to allow the developer maximum creative space and flexibility.

This chapter includes the following topics:

n Types of Extension Points in the vSphere Client

n Remote Plug-in Manifest Example

n Extension Points in the vSphere Client

Types of Extension Points in the vSphere Client

The vSphere Client provides a number of integration points that plug-ins can extend. Extensions are
separated into groups by the inventory context selection, and sub-groups by the purpose of the user
interface element.

The extension points are grouped as follows:

n Global extension points

These are plug-in UI elements that have global scope. Their context is the entire plug-in, rather than a
particular inventory object.

n View

This is a single global UI element that can consume a large section of the vSphere Client real
estate. When multiple global pages are required, they should be implemented within this single
global view. Navigation between the nested pages must be handled by the plug-in front end.

For example, this includes configuration pages or status dashboards.

n Object extension points

These are plug-in UI elements within the scope of the currently selected context object in the
inventory. They are defined per object type and displayed only for the selected object. Their views
can include other inventory objects or external objects, as long as there is a logical relevance to the
current object.

n Summary Section View

VMware, Inc. 59
Developing Remote Plug-ins with the vSphere Client SDK

This is a single plug-in view that is displayed as a small box in the object's summary view. It
should contain primarily simple name-value data. Optionally it can contain action buttons or links
to more detailed Monitor or Configure pages.

For example, this could be a view for a selected host that shows the following:

• The number of virtual machines that need backup.

• A button that backs up all virtual machines that need backup.

• A link to a Monitor view that lists all virtual machines that need backup, and allows a user to
back them up separately.

You have limited control over the size of the Summary Section View. By default, the width/height
ratio is 1:1, but you can specify 1:2 by using the <size> element in the plug-in manifest file.

For example, you can specify a double-height Summary Section View as follows:

...
"summary": {
"view": {
"uri": "index.html?view-host-summary"
"size": {
"width": 1,
"height": 2
}
}
}
...

n Monitor Views

This comprises a single Monitor category with one or more views. It can contain detailed
monitoring and maintenance data and workflows relevant to the current object.

For example, you could use a Monitor view to show the backup status of all virtual machines on a
selected host.

n Configure Views

This comprises a single Configure category with one or more views. It can contain detailed
configuration data and workflows relevant to the current object.

For example, it could show a list of virtual machines on a selected host that should be backed up.

n Menu

This is a single plug-in solution menu with one or more actions. It contains actions that apply to
the current object, allowing user input before execution.

For example, you could use a Menu action to back up all virtual machines on a selected host.

Note Menu actions in remote plug-ins are supported for only a single target object.

Note Headless actions in remote plug-ins are not supported.

VMware, Inc. 60
Developing Remote Plug-ins with the vSphere Client SDK

Remote Plug-in Manifest Example

The following JSON code is an example of a plug-in manifest file that demonstrates how to specify some
of the vSphere Client SDK extension points for your plug-in.

{
"manifestVersion": "1.0.0",
"requirements": {
"plugin.api.version": "1.0.0"
},
"configuration": {
"nameKey": "My Plugin",
"icon": {
"name": "main"
}
},
"global": {
"view": {
"navigationId": "myGlobalViewId",
"uri": "myplugin/globalView.html",
"navigationVisible": false
}
},
"objects": {
"Datacenter": {
"summary": {
"view": {
"uri": "myplugin/summary.html",
"icon": {
"name": "main"
},
"size": {
"widthSpan": 1,
"heightSpan": 2
}
}
},
"monitor": {
"views": [
{
"navigationId": "myview1",
"labelKey": "category.view1",
"uri": "myplugin/view1.html"
}
]
},
"configure": {
"views": [
{
"navigationId": "myview1",
"labelKey": "category.view1",
"uri": "myplugin/view1.html"
}

VMware, Inc. 61
Developing Remote Plug-ins with the vSphere Client SDK

]
},
"menu": {
"actions": [
{
"labelKey": "action1",
"icon": {
"name": "action-1"
},
"trigger": {
"type": "modal",
"uri": "myplugin/modal-action.html",
"size": {
"height": 250,
"width": 600
}
}
}
]
}
}
},
"definitions": {
"iconSpriteSheet": {
"uri": "myplugin/images/icon-sprite.png",
"definitions": {
"main": {
"x": 0,
"y": 0
}
}
},
"i18n": {
"locales": [
"en-US",
"de-DE",
"fr-FR"
],
"definitions": {
"category.view1": {
"en-US": "Monitor View 2",
"de-DE": "Monitoransicht 2",
"fr-FR": "Vue Surveiller 2"
}
}
}
}
}

VMware, Inc. 62
Developing Remote Plug-ins with the vSphere Client SDK

Extension Points in the vSphere Client

The vSphere Client publishes extension points that you can use to create your extensions. The following
sections contain a list of the currently supported extension points, including a brief description of each
extension point and the required extension definition type.

VMware, Inc. 63
vSphere Client Plug-in User
Interface Modules 7
The vSphere Client provides several JavaScript interfaces that your plug-in can use to communicate with
the vSphere Client platform. These JavaScript methods are documented here as if they have TypeScript
signatures, but they run as pure JavaScript, and all complex types are plain old JavaScript objects.

The plug-in web application runs in a separate iframe which is part of the vSphere Client. The iframe
content is rendered from the web application server of the plug-in back end.

Note Do not access the window.parent, which belongs to the vSphere Client. Such access is
unsupported and could cause your plug-in to fail in a future release of the vSphere Client.

This chapter includes the following topics:

n Bootstrapping the JavaScript API

n vSphere Client JavaScript API: htmlClientSdk Interface

n vSphere Client JavaScript API: Modal Interface

n vSphere Client JavaScript API: Application Interface

n vSphere Client JavaScript API: Event Interface

n Example Using the modal API

Bootstrapping the JavaScript API

The vSphere Client loads plug-in resources in a tenant iframe. The plug-in must load a thin JavaScript
library to support communication with the parent window in the vSphere Client. The library implements a
JavaScript API that the plug-in front-end code uses to manage resources outside its iframe.

To bootstrap the Client Library the following script should be added to all HTML pages in the plug-in:

<script type="text/javascript"src="/api/ui/htmlClientSdk.js"></script>

After you load the script, you initialize the htmlClientSdk object, by invoking the
htmlClientSdk.initialize() method. Before you initialize, you can only invoke
htmlClientSdk.initialize() or htmlClientSdk.isInitialized(). After you initialize the htmlClientSdk
object, you can invoke any of the methods in the JavaScript API.

VMware, Inc. 64
Developing Remote Plug-ins with the vSphere Client SDK

If you use frameworks such as jQuery, or zone.js with Angular, you only need to initialize the
htmlClientSdk object once. You should initialize as early as possible, so that the htmlClientSdk functions
will be available to all plug-in user interface components.

Note Do not use any communication method not provided by the APIs. Doing so is unsupported
because the implementation of the htmlClientSdk functions can change in future releases of the vSphere
Client.

vSphere Client JavaScript API: htmlClientSdk Interface

The htmlClientSdk object provides access to all the JavaScript API interfaces. You load and initialize the
htmlClientSdk first in your plug-in views.

htmlClientSdk.initialize() method
Signature htmlClientSdk.initialize(callback):void

Description Initializes the htmlClientSdk object and invokes the callback function when initialization is complete. After the
htmlClientSdk object is initialized, subsequent calls invoke the callback function without needing to initialize the
htmlClientSdk object.

Parameter: The callback function must have the following signature:

callback function callback():void
The callback function has access to all the functions in the JavaScript API. You use the callback to code logic for
initializing plug-in state.

htmlClientSdk.isInitialized() method
Signature htmlClientSdk.isInitialized():boolean

Description Tests whether the htmlClientSdk object has been initialized.

vSphere Client JavaScript API: Modal Interface

The modal interface enables your plug-in to manage modal dialog windows.

modal.open() method
Signature modal.open(configObj:ModalConfig):void

Description Opens a modal dialog box specified by the configObj parameter.

Parameter: configObj Specifies the properties of this modal dialog box.

modal.close() method
Signature modal.close(data:any):void

Description Closes the modal dialog box in the parent iframe.

Parameter: data Passes data to the callback function specified by onClosed property at dialog open.

VMware, Inc. 65
Developing Remote Plug-ins with the vSphere Client SDK

modal.setOptions() method
Signature modal.setOptions(options:DynamicModalOptions):void

Description Called by the parent view to modify some properties for a modal dialog box in the parent iframe.

Parameter: options Specifies values for some dialog box properties.

modal.getCustomData() method
Signature modal.getCustomData():any

Description Returns the customData object provided when a modal dialog box was opened, or null if no customData object was
provided.

modal.DynamicModalOptions type
Description Specifies values for some properties of a modal dialog box.

Name Type Required? Notes

title string no Dialog title. May not contain an icon. (If not present, no change to dialog title.)

height number no Dialog size. Specified in multiples of default size. (height={1|2}). (If not specified, no change to
dialog height.)

modal.ModalConfig type
Description Specifies the properties of a modal dialog box.

Name Type Required? Notes

url string yes Location of HTML content for the dialog.

title string no Dialog title. May not contain an icon. (default='')

size (width:number, yes Dialog size. Specified in multiples of default size. (height={1|2},
height:number) width={1})

closable boolean no Whether the dialog displays a close button. (default=true)

onClosed callbackFn no Function runs when the dialog closes.

customData any no Data the calling module passes to the dialog.

contextObjects string[] no IDs of relevant objects the calling module passes to the dialog.

vSphere Client JavaScript API: Application Interface

The app interface provides context object information and helps your plug-in navigate and control the
vSphere Client user interface.

app.getApiEndpoints() method
Signature app.getApiEndpoints():UiApiEndpoint

Description Returns the URLs of the vsphere-ui service API endpoints available to plug-ins.

VMware, Inc. 66
Developing Remote Plug-ins with the vSphere Client SDK

app.getContextObjects() method
Signature app.getContextObjects():any[]

Description Returns the current context objects.

Return value:
for global view Returns empty array. Global views have no context.

for vSphere object Returns a context item for the associated vSphere object.

for dialog opened by If dialog opened by htmlClientSdk.modal.open(configObj), returns value of

modal.open() configObj.contextObjects (or empty array, if contextObjects undefined)

for dialog opened by If dialog opened by action defined in plugin.json, returns an array of context
plugin.json actions items.

A context item is a JavaScript object containing a single property, id:string. This is the ID of the associated
vSphere object.

app.navigateTo() method
Signature app.navigateTo(options:NavigationOptions):void

Description Navigates to a specified view, and optionally passes custom data to the view.

Parameter: options Specifies the destination view and custom data.

app.getNavigationData() method
Signature app.getNavigationData():any

Description Returns the custom data passed to the view by the navigateTo() method. (If no custom data passed, returns null.)

app.getClientInfo() method
Signature app.getClientInfo():ClientInfo

Description Returns type and version info for the vSphere Client.

app.getClientLocale() method
Signature app.getClientLocale():string

Description Returns the current locale of the vSphere Client.

app.getSessionInfo() method
Signature app.getSessionInfo(callback):void

Description Retrieves information about the client's authentication session.

The callback function must have the following signature:

function callback(sessionInfo:SessionInfo)

VMware, Inc. 67
Developing Remote Plug-ins with the vSphere Client SDK

app.getTheme() method
Signature app.getTheme():PluginTheme

Description Retrieves information about the theme the plug-in should use.

app.ClientInfo type
Description Documents type and version of vSphere Client.

Name Type Required? Notes

type string info only The vSphere Client type (HTML or Flex)

version string info only The vSphere Client version string.

app.NavigationOptions type
Description Specifies a destination view and custom data for the view.

Name Type Required? Notes

targetViewId string yes Navigation ID of the destination view. (For a remote plug-in, this property must identify a
view created by the same plug-in.)

objectId string no ID of any object associated with the view. (For a global view, this field is not required.)

customData any no A custom data structure passed to the view.

app.PluginTheme type
Description Indicates the UI theme that is currently selected.

Name Type Required? Notes

name string info only Possible values: light or dark.

app.QueryParam type
Description Holds a single query parameter of a URL.

Name Type Required? Notes

name string info only Name of query parameter, as in ?name=value.

value string info only Value of query parameter, as in ?name=value.

app.SessionInfo type
Description Holds information about the current session of the vSphere Client.

Name Type Required? Notes

sessionToken string info only Identifier of the plug-in authentication session with vCenter Server.

VMware, Inc. 68
Developing Remote Plug-ins with the vSphere Client SDK

app.UiApiEndpoint type
Description Holds the parsed elements of the plug-in URL.

Name Type Required? Notes

origin string info only <protocol>://<hostname><port>

pathname string info only

queryParams Array<QueryParam> info only <name>=<value>

fullUrl string info only <origin>/<pathname>?<queryParams>

vSphere Client JavaScript API: Event Interface

The event interface helps your plug-in with event management.

event.onGlobalRefresh() method
Signature event.onGlobalRefresh(pluginCallbackFunc:function):void

Description Registers a global refresh handler that the vSphere Client will call when the Global Refresh button is
clicked.

Parameter: A reference to a global refresh handler, with signature function callback():void

pluginCallbackFunc

event.onThemeChanged() method
Signature event.onThemeChanged(themeCalbackFunc:function):void

Description Registers an event handler that the vSphere Client will call when the vSphere Client changes the
current theme.

Parameter: A reference to a theme change handler, with signature function

themeCallbackFunc themeCallbackFunc(theme:app.PluginTheme):void

Example Using the modal API

This example shows some basic features of the modal interface of the Client API.

modal.html

<html>
<head>
<script src="http://code.jquery.com/jquery-latest.min.js"
type="text/javascript"></script>
<script src="/api/ui/htmlClientSdk.js"
type="text/javascript"></script>
<script type='text/javascript'>
function handler(event)
{
var choice = $('input[name=heads_or_tails]:checked').val();

VMware, Inc. 69
Developing Remote Plug-ins with the vSphere Client SDK

htmlClientSdk.modal.setOptions({title: choice});
settimeout(function(){htmlClientSdk.modal.close(choice);}, 3000);
}
</script>
</head>
<body>
<form name='flip' onSubmit='return handler()'>
<p><input type='radio' name='heads_or_tails' value='HEADS' />HEADS</p>
<p><input type='radio' name='heads_or_tails' value='TAILS' />TAILS</p>
<input type='submit' name='submit' value='Submit' />
</form>
</body>
</html>

modal.js

flipper = function(){
# Select correct answer.
correct = ['heads', 'tails'][2*Math.random()-1];

# Create callback function.

checker = function(choice){
var correct = htmlClientSdk.modal.getCustomData();
if (choice === correct) {
alert('You chose wisely.');
} else {
alert('Sorry, you lose.');
}}

# Configure modal dialog.

var config ={
url: "example/dialog.html",
title: 'Choose!',
size: { width: 490, height: 240 },
onClosed: checker,
customData: correct}

# Open modal dialog.

htmlClientSdk.modal.open(config);
}

# Initialize Javascript API.

$(document).ready(htmlClientSdk.initialize(flipper));

VMware, Inc. 70
Using Themes with vSphere
Client Plug-ins 8
The vSphere Client SDK provides the means for a plug-in to integrate with the themes supported by the
vSphere Client. Modifying a plug-in to support themes requires changes to the plug-in style sheets and
front-end code to switch style sheets whenever the user changes the theme in the vSphere Client.

To integrate with the vSphere Client themes, a plug-in uses these methods of the JavaScript API:

n app.getTheme()

n event.onThemeChanged(callback)

The following procedures assume that the plug-in's front-end code is built using Angular and Clarity
Design System. For other frameworks and build tools, the approach is similar but you will need to adapt
the approach to suit the chosen tools. The examples in this guide are based on the HTML Plug-in Sample
provided as part of the vSphere Client SDK.

This chapter includes the following topics:

n Using Style Variables in Plug-In CSS

n Building Output Style Sheets for vSphere Client Plug-Ins

n Configuring and Loading Theme Style Sheets in vSphere Client Remote Plug-Ins

Using Style Variables in Plug-In CSS

If a plug-in uses custom styles that depend on the theme colors, the plug-in style sheets (CSS or SASS or
LESS) need to be parameterized. This enables the plug-in to adapt when the user switches themes in the
vSphere Client user interface.

In this procedure you copy any custom colors that depend on the current theme into variables in separate
style sheets that are specific to the light or dark theme. You replace the colors in the original style
sheets with instances of CSS variables. This is done to avoid style sheet duplication and to easily
integrate theming with any custom Angular components the plug-in has defined. For more information
about CSS variables, see https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables.

Prerequisites

Ensure that the plug-in's Clarity version supports the dark theme. The first Clarity version to support the
dark theme is 0.10.16.

VMware, Inc. 71
Developing Remote Plug-ins with the vSphere Client SDK

Procedure

1 Identify any theme-dependent colors or styles in your plug-in.

2 Factor out theme-dependent colors or styles into two new style sheets as CSS variables.

The SDK includes the following sample file at html-client-sdk/samples/remote-plugin-sample/src/

main/ui/src/styles-light.css.

:root {
--border-color: rgb(204, 204, 204);
--overlay-color: rgba(255, 255, 255, 0.2);
--info-icon-color: darkblue;
}

The SDK includes the following sample file at html-client-sdk/samples/remote-plugin-sample/src/

main/ui/src/styles-dark.css.

:root {
--border-color: rgb(72, 87, 100);
--overlay-color: rgba(0, 0, 0, 0.2);
--info-icon-color: darkblue;
}

3 Replace the theme-dependent colors or styles in the original style sheets with variable references.

The SDK includes the following code in the sample file at html-client-sdk/samples/remote-plugin-
sample/src/main/ui/src/app/views/list/list.component.scss.

.splitter {
flex: 0 0 auto;
width: 1px;
margin: 0 20px;
background-color: var(--border-color);
}

4 For Internet Explorer 11, which does not include support for CSS variables, include a polyfill library to
provide support for CSS variables.

The vSphere Client SDK includes a remote plug-in sample that uses css-vars-ponyfill. The
following example is borrowed from html-client-sdk/samples/remote-plugin-sample/src/
main/ui/src/index.html.

<script type="text/javascript" src="scripts/css-vars-ponyfill.js"></script>

What to do next

Use the modified input style sheets to build nte output style sheets for your plug-in.

VMware, Inc. 72
Developing Remote Plug-ins with the vSphere Client SDK

Building Output Style Sheets for vSphere Client Plug-Ins

After you isolate theme-dependent colors or styles as CSS variables, you can merge the resulting style
sheets with the standard Clarity styles to produce a set of output style sheets for optimized performance.

Angular applications which use webpack and angular-cli place the style sheet declarations inline by
default, when in development mode. Inline style declarations interfere with dynamic CSS loading. When
you build the output style sheets, always configure the build to output and use external CSS:

To build external style sheets, add the --extract-css parameter to the ng build command. The
vSphere Client SDK has examples of this usage in html-client-sdk/samples/remote-plugin-
sample/src/main/ui/package.json.

You must disable any output file name hashing in the development and production builds. Otherwise the
names of the style sheet files will change whenever the code changes, and the plug-in will not be able to
load them.

To disable file name hashing when you build style sheets, use this syntax:
ng build --prod --output-hashing none.

Prerequisites

Refactor the input style sheets for the plug-in so that they isolate theme-dependent colors and styles in
separate style sheets as CSS variables.

Procedure

1 Create a base output style sheet that is independent of the themes.

The base style sheet contains the Clarity icons style sheet and the base input style sheet for the plug-
in, which uses CSS variables. The vSphere Client SDK builds this output style sheet by using Angular
to compile the SCSS.
The following example comes from the vSphere Client SDK file html-client-sdk/samples/
remote-plugin-sample/src/main/ui/angular-cli.json.

"styles": [
{
"input": "../node_modules/clarity-icons/clarity-icons.min.css",
"output": "styles",
"lazy": true
},
{
"input": "styles.css",
"output": "styles",
"lazy": true
}
...
]

VMware, Inc. 73
Developing Remote Plug-ins with the vSphere Client SDK

This step combines the contents of html-client-sdk/samples/remote-plugin-sample/src/

main/ui/node_modules/remote-plugin-sample/src/main/ui/styles.css and html-client-
sdk/samples/remote-plugin-sample/src/main/ui/styles.css into html-client-sdk/
samples/remote-plugin-sample/target/classes/ui/styles.bundle.css.

2 Create an output style sheet file for the light theme.

This style sheet includes the Clarity style sheet for the light theme and the plug-in style sheet for the
light theme, which contains the CSS variable definitions for the light theme.

The following example comes from the vSphere Client SDK file html-client-sdk/samples/
remote-plugin-sample/src/main/ui/angular-cli.json.

"styles": [
...
{
"input": "../node_modules/clarity-ui/clarity-ui.min.css",
"output": "theme-light",
"lazy": true
},
{
"input": "styles-light.css",
"output": "theme-light",
"lazy": true
}
...
]

This step combines the contents of html-client-sdk/samples/remote-plugin-sample/src/

main/ui/node_modules/clarity-ui/clarity-ui.min.css and html-client-sdk/samples/
remote-plugin-sample/src/main/ui/styles-light.css into html-client-sdk/samples/
remote-plugin-sample/target/classes/ui/theme-light.bundle.css.

3 Create an output style sheet file for the dark theme.

This style sheet includes the Clarity style sheet for the dark theme and the plug-in style sheet for the
dark theme, which contains the CSS variable definitions for the dark theme.

The following example comes from the vSphere Client SDK file html-client-sdk/samples/
remote-plugin-sample/src/main/ui/.angular-cli.json.

"styles": [
...
{
"input": "../node_modules/clarity-ui/clarity-ui-dark.min.css",
"output": "theme-dark",
"lazy": true
},
{
"input": "styles-dark.css",
"output": "theme-dark",

VMware, Inc. 74
Developing Remote Plug-ins with the vSphere Client SDK

"lazy": true
}
...
]

This step combines the contents of html-client-sdk/samples/remote-plugin-sample/src/

main/ui/node_modules/clarity-ui/clarity-ui-dark.min.css and html-client-sdk/
samples/remote-plugin-sample/src/main/ui/src/styles-dark.css into html-client-sdk/
samples/remote-plugin-sample/target/classes/ui/theme-dark.bundle.css.

What to do next

Write front-end code to load style sheets that match the theme selected by the user.

Configuring and Loading Theme Style Sheets in vSphere

Client Remote Plug-Ins
After you compile the output style sheets for your plug-in user interface, you write front-end code to load
the style sheets that cause your plug-in to conform to the style selected in the vSphere Client.

Prerequisites

n Refactor the input style sheets for the plug-in so that they isolate theme-dependent colors and styles
in separate style sheets as CSS variables.

n Build output style sheets into a base style sheet and a style sheet for each theme.

Procedure

1 Load and configure polyfill libraries to provide CSS variable support in Internet Explorer 11.

If you use css-vars-ponyfill, consider whether to configure options to create a MutationObserver

and whether to remove CSS rulesets and declarations that do not reference a CSS custom property
value. For more information about configuring css-vars-ponyfill, see https://github.com/
jhildenbiddle/css-vars-ponyfill/tree/v1.17.1#optionswatch and https://github.com/jhildenbiddle/css-
vars-ponyfill/tree/v1.17.1#optionsonlyvars.
The vSphere Client SDK includes a remote plug-in sample that uses css-vars-ponyfill. The
following example is borrowed from the file html-client-sdk/samples/remote-plugin-
sample/src/main/ui/src/index.html.

<script type="text/javascript" src="scripts/css-vars-ponyfill.js"></

script>
// Initialize CSS vars to configure polyfill.
cssVars({
watch: true,
onlyVars: true
});

VMware, Inc. 75
Developing Remote Plug-ins with the vSphere Client SDK

The following example is borrowed from the file html-client-sdk/samples/remote-plugin-

sample/src/main/ui/.angular-cli.json.

"assets": [
"assets",
{
"glob":
"css-vars-ponyfill.js",
"input": "../node_modules/css-vars-ponyfill/dist/",
"output": "scripts/
},
…
]

2 Load the base style sheet initially.

The following example is borrowed from html-client-sdk/samples/remote-plugin-

sample//src/main/ui/src/index.html.

<link rel="stylesheet" type="text/css" href="styles.bundle.css">

3 Load and initialize the vSphere Client JavaScript API.

<script type="text/javascript" src="/api/ui/htmlClientSdk.js"></script>

<script type="text/javascript">
htmlClientSdk.initialize(init_plugin_view());
</script>

For examples in the SDK, see html-client-sdk/samples/remote-plugin-sample//src/

main/ui/src/index.html and html-client-sdk/samples/remote-plugin-sample//src/
main/ui/src/app/app.component.ts.

4 Load the style sheet for the current theme initially and whenever the style changes.

The following example is adapted from html-client-sdk/samples/remote-plugin-sample/src/

main/ui/src/app/app.component.ts.

if (this.globalService.htmlClientSdk.app.getTheme &&
this.globalService.htmlClientSdk.event.onThemeChanged) {
this.loadTheme(true, this.globalService.htmlClientSdk.app.getTheme());
this.globalService.htmlClientSdk.event.onThemeChanged(
this.loadTheme.bind(this, false));
} else {
this.loadTheme(true, { name: 'light' });
}

private loadTheme(firstLoad: boolean, theme: any): void {

let themeName: string = theme.name;
let supportedThemeNames: string[] = ['light', 'dark'];
if (supportedThemeNames.indexOf(themeName) === -1) {
themeName = supportedThemeNames[0];
}
let styleSheetLinkElement =

VMware, Inc. 76
Developing Remote Plug-ins with the vSphere Client SDK

(<HTMLLinkElement> document.getElementById('theme-stylesheet-link'));
let themeCssUrl = `theme-${themeName}.bundle.css`;

if (firstLoad) {
let initialThemeLoadCompleteListener = (event: Event) => {
this.initialThemeLoadComplete = true;
styleSheetLinkElement.removeEventListener('load',
initialThemeLoadCompleteListener);
styleSheetLinkElement.removeEventListener('error',
initialThemeLoadCompleteListener);
};

styleSheetLinkElement.addEventListener('load',
initialThemeLoadCompleteListener);
styleSheetLinkElement.addEventListener('error',
initialThemeLoadCompleteListener);
}

styleSheetLinkElement.setAttribute("href", themeCssUrl);
document.documentElement.setAttribute("data-theme", themeName);
}

VMware, Inc. 77
Remote Plug-in Server
Considerations for the vSphere
Client 9
A remote plug-in for the vSphere Client has both a server portion and a user interface portion. You can
use any coding language or framework you choose for the server portion. Your plug-in server must
generally provide the following functionality:

n A web application server that serves both the plug-in manifest file and the plug-in user interface files.

n A fixed Service Provider Interface that responds to vSphere Client requests for dynamic view content,
such as menus.

n Data access and computation services on behalf of the plug-in user interface views, if needed.

n Session cloning service to authenticate with the vCenter Server Web Services API, if needed.

This chapter includes the following topics:

n Communication Paths for Authentication in the Remote Plug-in Server

n vSphere Authentication in the Remote Plug-in Server

Communication Paths for Authentication in the Remote

Plug-in Server
The remote plug-in server operates outside the vCenter Server instance, and must authenticate with the
Web Services API to identify and authorize its access to vSphere resources. The process of
authentication requires several steps.

The plug-in user interface communicates with the vsphere-ui service through a plug-in sandbox in the
browser. The plug-in sandbox uses the vSphere Client session token to authenticate with the vsphere-ui
service in vCenter Server. The plug-in server needs a SOAP client session token to authenticate its
operations with the Web Services API. The following diagram shows the communication paths involved in
converting the vSphere Client session token to a plug-in server SOAP session token.

VMware, Inc. 78
Developing Remote Plug-ins with the vSphere Client SDK

Figure 9-1. Plug-in Server Communication Paths for Authentication

Browser
vSphere Client UI
Plug-in Sandbox JavaScript
Library
Plug-in UI

authenticated by client session token HTTPS, authenticated by

plug-in session token

REST, authenticated by
plug-in session token
vsphere-ui service Plug-in Server

SOAP, authenticated by session cookie

Managed Objects

Web Services API

vCenter Server

Cloning a session consists of three interactions involving the plug-in server:

1 The plug-in user interface sends its session ID and the vCenter Server endpoint to the plug-in server.

2 The plug-in server sends a REST request to vCenter Server to acquire a ticket that allows it to clone
the user session.

3 The plug-in server sends a SOAP request to vCenter Server to clone the user session and acquire a
new session ID.

vSphere Authentication in the Remote Plug-in Server

When a plug-in server accesses vSphere data, it needs to authenticate with vCenter Server. To
authenticate by using the Web Services API, the plug-in server clones the user session that is currently in
use by the plug-in user interface. This gives the plug-in server the same access rights as the user who is
logged in with the vSphere Client.

Following are the detailed steps to clone the user session.

Note The plug-in server must be registered with the vCenter Server instance before it can clone a
session with that instance.

1 The plug-in user interface calls the app.getSessioninfo() method in the client JavaScript library,
which in turn contacts the plug-in sandbox to request session information. The sandbox returns an
object containing a sessionToken string, which contains a new plug-in session token that can be used
for authentication by the plug-in server.

2 The plug-in user interface calls the app.getApiEndpoints() method in the client JavaScript library,
which returns an object containing a uiApiEndpoint property. The value of the uiApiEndpoint
property is an object containing a fullUrl property, which contains the endpoint URL for a plug-in
server REST request to the vsphere-ui service.

VMware, Inc. 79
Developing Remote Plug-ins with the vSphere Client SDK

3 The plug-in user interface removes any query parameters and fragments from the URL, leaving the
scheme, host, port, and path segments. The user interface sends both the session token value and
the base URL to the plug-in server.

Note Do not hard-code the URL in the server.

4 The plug-in server builds a REST request to the vsphere-ui service. The request contains the
following:

n A POST verb.

n The Content-type and Accept headers both set to application/json.

n A custom header named vmware-api-session-id, with the session token as its value.

n A JSON object body, containing a vc-guid property whose value is the GUID of the vCenter
Server instance.

The request will look similar to this:

POST /api/ui/vcenter/session/clone-ticket
Content-type: application/json
Accept: application/json
vmware-api-session-id: 12345678

{
"vc_guid": "223b94f2-af15-4613-5d1a-a278b19abc09"
}

5 The plug-in server sends the REST request to the vsphere-ui service, which returns a clone ticket
valid for the Web Services API of the vCenter Server instance. This is a single-use key to
authenticate a call to the SessionManager.

The response will look similar to this:

{
"session_clone_ticket": "cst-VCT-82cbd981-5f52-0a67-fe55-d995a7347f82--tp-B6-BC-CB-B8-59-89-C0-
F2-E4-F0-C2-91-8F-28-C1-DE-10-5E-24-69"
}

6 The plug-in server constructs a SOAP request to obtain a regular session ID from the Web Services
API, by using the cloneSession() operation on the Session Manager.

The code for the SOAP request will be similar to this Java example:

VimService vimService = new VimService();

VimPortType client = vimService.getVimPort();
ManagedObjectReference siRef = new ManagedObjectReference();
siRef.setType("ServiceInstance");
siRef.setValue("Serviceinstance");
ServiceInstance si = client.createStub(ServiceInstance.class, siRef);
ServiceInstanceContent sic = si.RetrieveContent();
SessionManager mgr = client.createStub(SessionManager.class, sic.getSessionManager());
UserSession wsSession = mgr.cloneSession(cloneTicket);

VMware, Inc. 80
Developing Remote Plug-ins with the vSphere Client SDK

7 The plug-in server uses the key property of the UserSession object to authenticate subsequent
requests to the Web Services API. The server places a vmware_soap_session cookie in its SOAP
request headers, with the session key as the cookie value.

Response Codes to session/clone-ticket Request

The REST request for a clone-ticket from the vsphere-ui service can produce the following response
codes.

Table 9-1. Response Codes to clone-ticket Request

Response Code Description

201 Session clone ticket was successfully created and returned.

The body type is application/json, and the response body has this format:

{
"session_clone_ticket": "string"
}

401 The request is not properly authenticated.

403 The remote plug-in is not registered with the vCenter Server instance identified by the specified UUID.

404 There is no vCenter Server instance identified by the specified UUID.

VMware, Inc. 81
Additional Resources 10

VMware, Inc. 82
Troubleshooting Remote Plug–
ins for the vSphere Client 11
These topics describe common problems that users see when deploying and operating remote plug-ins.
The topics describe characteristic symptoms and recommend solutions.

Some problems might be hard to distinguish because of similar symptoms. For example, several different
underlying problems can cause a situation where a plug-in user interface fails to display. If a
troubleshooting topic matches your symptom but the troubleshooting advice does not lead to a matching
cause or a working solution, check other topics for similar symptoms.

This chapter includes the following topics:

n Plug-in Does Not Appear in vSphere Client

n Missing Entry in the Instance Selector

n Unable to Change Plug-in Manifest File

n OSGi Deployment Failure

n Troubleshooting: Problems with Registration Script in SDK

Plug-in Does Not Appear in vSphere Client

The plug-in does not appear in the vSphere Client.

Problem

One or more of these symptoms is evident:

n A plug-in does not appear in the object navigator.

n A plug-in view does not display in the browser.

Cause

Several causes can prevent a plug-in from appearing. Try the following troubleshooting topics:

n Plug-in Manifest URL Unreachable

n Troubleshooting: Plug-in Thumbprint Incorrect

n Manifest Cannot Be Parsed

n Plug-in Already Registered

n Wrong Plug-in Type

VMware, Inc. 83
Developing Remote Plug-ins with the vSphere Client SDK

n Plug-in Marked As Incompatible

n Plug-in Registered with Incompatible Version

n Plug-in View is missing in the vSphere Client

Wrong Plug-in URL

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins.

Cause

This problem can occur if the plug-in URL is not reachable. The plug-in registration command might have
supplied an incorrect value for the extension.url property, which causes deployment to fail.

To verify the cause, use one of the following methods:

n In the Management UI, find the plug-in in the list under Admin > Client plugins. Next to the list entry,
look for a signpost which contains an error message saying that the plug-in failed to download:

Error downloading plug-in. Make sure that the URL is reachable and the registered thumbprint is
correct.

n If you do not find the signpost, you can search for the sample name in the log file at /var/log/
vmware/vsphere-ui/logs/vsphere-client-virgo.log to find an error message.

Solution

1 Connect a web browser to the Managed Object Browser (MOB) of the vCenter Server with which you
attempted to register the plug-in.

The MOB URL is https://vcenter_server_FQDN/MOB.

2 To view the ServiceContent data object click the content link.

3 To view the ExtensionManager managed object click the ExtensionManager link.

4 In the extensionList values, search for the extension key that you used to register the plug-in.

The more... link enables you to see more of the list of extension keys.

5 Check that the client.url property is correct.

Enter the URL in a browser address bar and verify that the browser displays the contents of the
plugin.json file.

If the URL used in the registration command was correct, check the thumbprint by using the topic
Troubleshooting: Plug-in Thumbprint Incorrect.

VMware, Inc. 84
Developing Remote Plug-ins with the vSphere Client SDK

6 If the URL used in the registration command was incorrect, reregister the plug-in as follows:

a Unregister the plug-in.

You can use the registration tool in the SDK to unregistor a plug-in. For syntax information, see
vSphere Client Plug-in Registration Tool.

b Repeat the plug-in registration step with the correct URL.

Troubleshooting: Plug-in Thumbprint Incorrect

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins.

Cause

This problem can occur if the extension.thumbprint is not valid. The plug-in registration command might
have supplied an incorrect server thumbprint, which causes deployment to fail.

To verify the cause, use one of the following methods:

n In the Management UI, find the plug-in in the list under Admin > Client plugins. Next to the list entry,
look for a signpost which contains an error message saying that the plug-in failed to download:

Error downloading plug-in. Make sure that the URL is reachable and the registered thumbprint is
correct.

n If you do not find the signpost, you can search for the sample name in the log file at /var/log/
vmware/vsphere-ui/logs/vsphere-client-virgo.log to find an error message.

Solution

1 Connect a web browser to the Managed Object Browser (MOB) of the vCenter Server with which you
attempted to register the plug-in.

The MOB URL is https://vcenter_server_FQDN/MOB.

2 To view the ServiceContent data object click the content link.

3 To view the ExtensionManager managed object click the ExtensionManager link.

4 In the extensionList values, search for the extension key that you used to register the plug-in.

The more... link enables you to see more of the list of extension keys.

5 Check that the server.serverThumbprint property is correct.

n The thumbprint should match the characters shown in the plug-in server certificate.

n Check for hidden characters.

n Pairs of digits must be separated by colon separators.

VMware, Inc. 85
Developing Remote Plug-ins with the vSphere Client SDK

If the thumbprint is correct, check the URL by using the topic Wrong Plug-in URL.

6 If the thumbprint used in the registration command was incorrect, reregister the plug-in as follows:

a Unregister the plug-in.

You can use the registration tool in the SDK to unregistor a plug-in. For syntax information, see
vSphere Client Plug-in Registration Tool.

b Repeat the plug-in registration step with the correct thumbprint.

Manifest Cannot Be Parsed

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins..

Cause

The plug-in manifest file is not valid and the plug-in deployment fails due to unsuccessful schema
validation.

You can distinguish this problem by searching for this error message in the vsphere-client-virgo.log:

Ignoring plugin extension.key because its JSON manifest could not be parsed.

Solution

1 According to the exception, locate the failure in the plug-in manifest file.

2 Trigger another plug-in discovery/deployment cycle. If the redeployment functionality is not enabled,
restart the vSphere Client service, vsphere-ui, to get the new plug-in manifest file changes.

3 Verify that the plug-in has been deployed, if not look for other errors in the plug-in manifest file.

Wrong Plug-in Type

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins.

Cause

The plug-in was not registered correctly as a remote plug-in, which causes the vSphere Client to assume
that it is a local plug-in. When the vSphere Client tries to download the plug-in manifest, it expects a .zip
file but finds a .json file instead.

You can verify the cause of the problem by searching the vsphere-client-virgo.log file for an error
message saying that the vSphere Client did not find a ZIP file at the plug-in manifest location:

VMware, Inc. 86
Developing Remote Plug-ins with the vSphere Client SDK

Couldn't open plugin zip file when trying to verify the signature of plugin extension.key:extension.version
java.util.zip.ZipException: error in opening zip file.

Solution

1 On the machine that runs the plug-in server, change to the directory that contains the plug-in
manifest.

For example: cd samples/remote-plugin-sample/target/classes/static

2 Unregister the plug-in.

For example: $tools/extension-registration.sh -action unregisterPlugin -k sample.plugin -

url https://vc-svr.example.com/sdk -u administrator@vsphere.local -p secret

3 Reregister the plug-in, specifying that it is a remote plug-in.

For example, you can use the plug-in registration tool in the SDK: $tools/extension-
registration.sh -action registerPlugin -remote -k sample.plugin -v 1.0.0 -url https://vc-
svr.example.com/sdk -u administrator@vsphere.local -p $secret -pluginUrl $pluginurl -
serverThumbprint $thumbprint -c 'Example Inc.' -n 'Example Plug-in' -s 'This plug-in is
registered with the remote keyword.'

Plug-in Marked As Incompatible

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins.

Cause

The plug-in is marked as incompatible in the compatibility matrix and is filtered out.

Note Plug-ins can be marked as incompatible with wild characters. The plug-in itself might not be
marked as incompatible, but it matches a pattern in the compatibility matrix.

In the Management UI there is a signpost for the plug-in which contains an error message saying that the
plug-in is marked as incompatible and can not be deployed:

The plug-in does not claim compatibility with the current vSphere Client version. Check plug-in's
interoperability matrix.

Solution

1 Open the /etc/vmware/vsphere-ui/compatibility-matrix.xml.

2 Mark the plug-in with extension.key as compatible by adding: <PluginPackage id="extension.key"

status="compatible"/>.

VMware, Inc. 87
Developing Remote Plug-ins with the vSphere Client SDK

Plug-in Registered with Incompatible Version

The remote plug-in does not display in the vSphere Client user interface.

Problem

The plug-in does not appear in the object navigator, but it is listed in the vSphere Client under Admin >
Client plugins.

Cause

The plug-in did not deploy because the extension.version is not well formatted.

The vsphere-client-virgo.log file contains an error message saying that the plug-in version is not well
formatted:

DEPLOYMENT_FAILED: Error deploying plugin package extension.key:extension.version. Reason:

Deployment error. java.lang.NumberFormatException: For input string: "some string".

Solution

u Verify that the extension.version is in the format "A.B.C.D", where:

n A, B, C, and D are numbers.

n A is mandatory.

n B, C, and D are optional.

The following examples form valid version strings:

n "1"

n "2.3"

n "5.4.2"

n "12.3.22.4"

Plug-in View is missing in the vSphere Client

A specific view is missing in the vSphere Client.

Problem

Navigating to some extension point shows Page Not Found.

Cause

The view was not loaded by the vSphere Client.

Verify that the view URL is correctly defined in the plug-in manifest file.

Verify directly that the URL is reachable from the plug-in server, bypassing the vCenter Server reverse
proxy.

VMware, Inc. 88
Developing Remote Plug-ins with the vSphere Client SDK

Missing Entry in the Instance Selector

A plug-in instance is missing from an Instance Selector.

Cause

This problem can occur only in an ELM environment, where multiple vCenter Server instances are linked.
The plug-in instance entry is missing because the plug-in from the vCenter Server instance did not
download or deploy the plug-in correctly.

Solution

u Verify that the plug-in is registered with the vCenter Server instance.

u Use other troubleshooting topics in Plug-in Does Not Appear in vSphere Client to find out why the
plug-in did not download or deploy.

Unable to Change Plug-in Manifest File

The vSphere Client does not respond to changes in a remote plug-in manifest file.

Problem

After a plug-in fails to deploy due to an invalid plug-in manifest file, the vSphere Client marks it as broken
and does not attempt to retry the download even if the plug-in manifest file is later updated on the plug-in
server.

Cause

After download the plug-ins are cached locally and a new download will happen if the cached manifest file
is deleted. This is expected production workflow. However, development environments require additional
configuration to avoid the cached plug-in manifest files.

Solution

1 Set the property remote.plugin.updateOnBrowserRefresh=true in the webclient.properties file.

2 Restart the vSphere Client service on the vCenter Server.

For example,

Addingremote.plugin.updateOnBrowserRefresh=true to the configuration will enable the automatic

redeploy of remote plug-ins on each browser refresh.

OSGi Deployment Failure

Your plug-in bundle fails to deploy.

Problem

The vSphere Client was unable to resolve a package dependency.

VMware, Inc. 89
Developing Remote Plug-ins with the vSphere Client SDK

Cause

Various situations can cause an OSGi bundle deployment failure.

Solution

u Check equinox.log for error messages related to the OSGi deployment.

Troubleshooting: Problems with Registration Script in

SDK
The vSphere Client SDK provides a script that you can use to register plug-ins during development.
Errors in the registration command can cause several kinds of plug-in failures. Most plug-in registration
failures go undetected until run time, but some failures cause the registration script to report an error.

Plug-in Already Registered

The remote plug-in registration script fails.

Problem

The plug-in registration script reports an error. If you overlook the error, the plug-in does not appear in the
object navigator and the plug-in is not listed in the vSphere Client under Admin > Client plugins.

Cause

The extension key was previously registered with the Extension Manager. The Extension Manager rejects
a new registration with a duplicate value in the extension key property.

The extension-registration.sh or extension-registration.bat script reports a message similar to the

following:

Client received SOAP Fault from server: A specified parameter was not correct: extension.key

Solution

1 Connect a web browser to the Managed Object Browser (MOB) of the vCenter Server with which you
attempted to register the plug-in.

The MOB URL is https://vcenter_server_FQDN/MOB.

2 To view the ServiceContent data object click the content link.

3 To view the ExtensionManager managed object click the ExtensionManager link.

4 In the extensionList values, search for the extension key that you used in your registration
command.

The more... link enables you to see more of the list of extension keys.

5 If you find the extension key in use, use a different key or unregister the extension key before you
retry the extension registration script.

VMware, Inc. 90
Developing Remote Plug-ins with the vSphere Client SDK

Unable To Unregister Plug-in

A plug-in unregistration command fails.

Problem

You use the plug-in registration tool to unregister a plug-in, but the tool reports a failure to unregister the
plug-in.

Cause

The --key argument did not match the extension.key property of the registration record in the
ExtensionManager.

Solution

1
You must use the --action unregisterPlugin argument with a key that matches the key you used
to register the plug-in. If you no longer have access to the registration command you used, you can
find the extension key value from the registration record in the ExtensionManager by using the
following procedure.
a Connect a web browser to the Managed Object Browser (MOB) of the vCenter Server with which
you attempted to register the plug-in.

The MOB URL is https://vcenter_server_FQDN/MOB.

b To view the ServiceContent data object click the content link.

c Click the ExtensionManager link to view the ExtensionManager managed object.

d In the extensionList values, search for the extension key that you used in your registration
command.

The more... link enables you to see more of the list of extension keys.

e Locate the extension.key property of the registration record for your plug-in.

2 Retry the unregistration command, supplying a corrected --key argument.

VMware, Inc. 91