jondwaite/vcd-h5-themes

VMware vCloud Director 9.x PowerShell cmdlets to assist managing HTML5 portal & themes

vcd-h5-themes

VMware vCloud Director 9.x PowerShell cmdlets to assist managing HTML5 portal & themes

This module provides several cmdlets to assist in managing the configurations and content of customization of the HTML5 portal in VMware vCloud Director v9.x environments. Note that none of these modules will affect branding or customization in the legacy FlexUI (Flash-based) portal present in previous releases of vCloud Director.

The table below shows the cmdlets included in this module, a brief description of each and the minimum vCloud Director version required for each.

cmdlet Name	Function	Minimum API / vCD Version
Get-Branding	Gets the currently defined HTML5 portal branding settings	30.0 (vCloud Director v9.1) / 32.0 (vCloud Director 9.7) for per-tenant branding
Set-Branding	Sets the vCloud Director HTML5 portal branding settings	30.0 (vCloud Director v9.1) / 32.0 (vCloud Director 9.7) for per-tenant branding
Get-Theme	Gets the available portal themes	30.0 (vCloud Director v9.1)
Set-Theme	Sets which portal theme is the current system default	30.0 (vCloud Director v9.1)
Remove-Theme	Deletes a portal theme	30.0 (vCloud Director v9.1)
New-Theme	Creates a new portal theme	30.0 (vCloud Director v9.1)
Publish-Css	Uploads a generated CSS file for a vCloud Director theme	31.0 (vCloud Director v9.5)
Get-Css	Downloads a CSS file from a vCloud Director theme	31.0 (vCloud Director v9.5)
Publish-Logo	Uploads a PNG file to be used as the portal logo	30.0 (vCloud Director v9.1) / 32.0 (vCloud Director 9.7) for per-tenant branding
Get-Logo	Downloads the PNG file being used as the portal logo	30.0 (vCloud Director v9.1) / 32.0 (vCloud Director 9.7) for per-tenant branding
Publish-Icon	Uploads a PNG file to be used as the browser icon	32.0 (vCloud Director v9.7)
Get-Icon	Downloads the PNG file being used as the browser icon	32.0 (vCloud Director v9.7)

The sections below provide documentation of each cmdlet and the parameters it takes together with example usage information.

Installation

This module has been uploaded to PowerShell Gallery and can be installed for the current user by:

Install-Module vcd-h5-themes -Scope CurrentUser

or globally using:

Install-Module vcd-h5-themes

It can also be downloaded and added to the current PowerShell session by:

Import-Module .\vcd-h5-themes.psd1

Get-Branding

This function retrieves the current branding settings for a vCloud Director instance. It returns the currently configured portal name, color scheme and currently selected default theme.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Tenant	String	None	No	An optional value to get the per-tenant branding, will return the system default branding if no specific branding is defined for this tenant or the tenant cannot be found.

Output:

A PSObject containing the configured branding settings for the Portal Name, Color (banner background), currently selected Theme and any defined customLinks entries.

Example:

C:\PS> Get-Branding -Server 'my.cloud.com'

portalName               portalColor selectedTheme                      customLinks
----------               ----------- -------------                      -----------
My Cloud Portal          #0C0C01     @{themeType=CUSTOM; name=MyCloud}  {}

Set-Branding

This function updates the current branding settings for a vCloud Director instance. It returns a message confirming the setting has been successfully applied.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
portalName	String	None	No	A new name for the site portal, if omitted the previous portal name is retained.
portalColor	String	None	No	A new color for the site portal banner, if omitted the previous color value is retained. Must be specified in HTML hexadecimal 16-bit color values using upper-case characters (e.g. '#1A2B3C'). If set to 'Remove' then any existing portal color will be removed.
customLinks	PSObject	None	No	Custom links to be configured in the vCD Portal. Note that this functionality is only available in vCD versions >= 9.7 (API Version 32.0). The format of this entry has changed from the (non-functional) equivalent call in v9.5 and prior. See my blog post here for details on how to configure a suitable customLinks object and pass this to Set-Branding. A template script to configure an appropriate customLinks object is included in this repository as 'example-customlinks.ps1'.
Tenant	String	None	No	If specified the branding will be configured for the specified tenant only and the system default left unchanged. Note that this feature is only available in vCD versions >= 9.7 (API Version 32.0).

Output:

A message confirms whether the requested changes have been successfully submitted to the vCloud API or an error. Settings can be verified by using Get-Branding

Example:

C:\PS> Set-Branding -Server 'my.cloud.com' -portalName 'My Cloud Portal'
Branding configuration sent successfully.

Get-Theme

This function returns the list of currently configured themes in vCloud Director. It will usually show the default built-in themes ('Default' and 'Dark') as well as any custom themes created. If an optional Theme is supplied only themes matching that name will be returned (can be used to check if a theme already exists).

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	No	A theme name to match, can be used to determine if a theme already exists.

Output:

A PSObject of themes found in the vCloud instance.

Example:

C:\PS> Get-Theme -Server 'my.cloud.com'

themeType name
--------- ----
CUSTOM    MyTheme
BUILT_IN  Default
BUILT_IN  Dark

Set-Theme

This function sets the specified theme to be the system default theme for vCloud Director to use in the HTML5 portal. Changes made here will be shown in subsequent Get-Branding requests.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	Yes	The theme to be set as the new system default theme. If the theme name cannot be matched an error will be generated and no changes made.
Custom	Boolean	true	No	Specifies whether the theme is a custom (user-created) theme or a built-in theme. Only needs to be specified (as 'false') if reverting to one of the VMware supplied default themes ('Default' or 'Dark').

Output:

A message indicating that the default theme configuration has been set successfully or an error.

Example 1: Set a custom theme as default:

C:\PS> Set-Theme -Server 'my.cloud.com' -Theme 'MyTheme'
Default theme configuration set successfully.

Example 2: Revert to default 'Dark' Theme:

C:\PS> Set-Theme -Server 'my.cloud.com' -Theme 'Dark' -Custom:$false
Default theme configuration set successfully.

New-Theme

This function creates a new theme with the specified name. Note that the created theme will not automatically be activated as the default system theme, that needs to be done using Set-Theme once created.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	Yes	The theme to be created. If the theme already exists an error will be generated and no changes made.

Output:

A message indicating that the new theme has been created successfully or an error.

Example:

C:\PS> New-Theme -Server 'my.cloud.com' -Theme 'MyTheme'
Theme MyTheme created successfully.

Remove-Theme

This function deletes a theme with the specified name.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	Yes	The theme to be removed. If the theme doesn't exist an error will be generated and no changes made.

Output:

A message indicating that the theme has been removed or an error.

Example:

C:\PS> Remove-Theme -Server 'my.cloud.com' -Theme 'MyTheme'
Theme MyTheme was removed successfully.

Publish-Css

This function uploads the specified .css file as the customization for the specified portal theme. Compatible .css files are generated by the VMware theme builder available in the VMware vcd-ext-sdk project under the /ui/theme-builder folder.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	Yes	The theme to which the CSS content should be uploaded.
CssFile	String	None	Yes	The path and filename of a .css file to be uplaoded as the CSS content for the specified theme, generally this will be the .css outputted by the VMware theme-builder.

Output:

A message indicating whether the .css file has been successfully uploaded or not.

Example:

C:\PS> Publish-Css -Server 'my.cloud.com' -Theme 'MyTheme' -CssFile 'mytheme.css'
Theme CSS file uploaded succesfully.

Get-Css

This function downloads any customization css that has been uploaded to a theme.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
Theme	String	None	Yes	The theme from which the CSS content should be retrieved.
CssFile	String	None	Yes	The path and filename of a file to be written with the downloaded css information, an existing file with the same name will be overwritten.

Output:

A message indicating whether or not the specified CSS was downloaded.

Example:

C:\PS> Get-Css -Server 'my.cloud.com' -Theme 'MyTheme' -CssFile 'mytheme.css'
Theme CSS file downloaded succesfully.

Publish-Logo

This function uploads the specified PNG file as the portal logo.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
LogoFile	String	None	Yes	The path and filename of a .png file to be uploaded as the portal logo.
Tenant	String	None	No	The Tenant Organization for which the logo should be published. Note that this option requires vCloud API v32.0 (vCloud Director 9.7) or later.

Output:

A message indicating whether the .png file has been successfully uploaded or not.

Example:

C:\PS> Publish-Logo -Server 'my.cloud.com' -LogoFile 'mylogo.png'
System logo file uploaded succesfully.

Get-Logo

This function downloads a PNG file of the current portal branding logo.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
LogoFile	String	None	Yes	The path and filename of a file to be written with the downloaded Logo file, an existing file with the same name will be overwritten.
Tenant	String	None	No	The Tenant Organization from which the logo should be downloaded. Note that this option requires vCloud API v32.0 (vCloud Director 9.7) or later.

Output:

A message indicating whether or not the specified PNG file was downloaded.

Example:

C:\PS> Get-Logo -Server 'my.cloud.com'  -LogoFile 'mylogo.png'
Logo PNG file downloaded succesfully.

Publish-Icon

This function uploads the specified PNG file as the portal browser icon.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
IconFile	String	None	Yes	The path and filename of a .png file to be uploaded as the portal browser icon.
Tenant	String	None	No	The Tenant Organization for which the browser icon should be published.

Output:

A message indicating whether the .png file has been successfully uploaded or not.

Example:

C:\PS> Publish-Icon -Server 'my.cloud.com' -IconFile 'myicon.png'
System icon file uploaded succesfully.

Get-Icon

This function downloads a PNG file of the current portal browser icon.

Parameters:

Parameter	Type	Default	Required	Description
Server	String	None	No	The FQDN of the vCloud Site (e.g. 'my.cloud.com'). Must be specified if you are connected to multiple vCD sites (Connect-CIServer) already. If only connected to a single vCD site then this will be used automatically.
IconFile	String	None	Yes	The path and filename of a file to be written with the downloaded browser icon file, an existing file with the same name will be overwritten.
Tenant	String	None	No	The Tenant Organization from which the logo should be downloaded.

Output:

A message indicating whether or not the specified PNG file was downloaded.

Example:

C:\PS> Get-Icon -Server 'my.cloud.com'  -IconFile 'myicon.png'
Logo PNG file downloaded succesfully.

vcd-h5-themes's Issues

Publish-Logo doesn't support SVGs

VMware Cloud Director supports both PNGs and SVGs for logos in branding, but the command is currently hardcoded to only support PNG files.

Incorrect URL for branding in Get-Branding

In the updates to the module for v1.6.0 that added vCD 10.3 support, there was a number of URL Changes to account for API changes, however this one is wrong.

vcd-h5-themes/vcd-h5-themes.psm1

Lines 138 to 143 in 6215ee3

	# For API path change in VCD 10.3+:
	if ([Float]$apiVersion -lt 36.0) {
	$uri = "https://$Server/cloudapi/branding"
	} else {
	$uri = "https://$Server/cloudapi/branding/themes"
	}

/cloudapi/branding is still the correct path for branding in vCD 10.3, /cloudapi/branding/themes returns the available themes instead when running the Get-Branding command.

Enhancement: Set-Branding should be able to remove portalColor (revert to Default)

Get-APIVersion : Could not retrieve API versions, Status Code is .

This occurs when the SSL certificate presented by vCloud Director is not trusted by the machine running the script.

Need to check the SSL certificate presented by the vCD API and give a more meaningful error message. The actual fix is to configure trust for the certificate presented (in Dev/Test) or ensure an appropriate trusted certificate is in use (Production).

Set-Branding 405

I'm having an issue with setting a tenant branding. I'm getting a 405 when attempting it. All other branding stuff seems to work. I'm using VCD 10.1.2 and H5-themes 1.5.2.

PS C:\Users\user> get-branding -tenant BrandingTest |FL
portalName : DEV Cloud Director
portalColor : #0B1E40
selectedTheme : @{themeType=BUILT_IN; name=Default}
customLinks : [redacted]

PS C:\Users\user> set-branding -tenant BrandingTest -portalName 'Branding Test'
set-branding : Error occurred configuring branding, Status Code is 405.
At line:1 char:1

• set-branding -tenant BrandingTest -portalName 'Branding Test'

•   + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Set-Branding
  

PSGallery Module out of date

The PSGallery Module version is still 1.5.2, missing the vCD 10.3 fixes.
Can you please update the version of the module in the gallery? :)

set-branding headers

In the set-branding function you should add the header api version from "31" to "32":

$headers = @{ "x-vcloud-authorization" = $mySessionID; "Accept" = 'application/json;version=32.0' }

Publish-Css Fails - Cannot index into a null array

I've run into an issue whereby I cannot publish-css to my server. I've created a new theme called 'USS' and I've been trying to get this CSS in there. It fails, stating I cannot index into a null array. I'm testing against vCD 9.7.0.2 with the latest version of your plugin. Can you advise?

PS C:\Users\user\Desktop> publish-css -server $server -theme 'USS' -CssFile 'theme-USS.css'
Cannot index into a null array.
At C:\Users\lab_rfish\Documents\WindowsPowerShell\Modules\vcd-h5-themes\1.5.1\vcd-h5-themes.psm1:585 char:5

• $uploaduri = $r1.RelationLink['upload:default']
  

• ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : InvalidOperation: (:) [], RuntimeException
  • FullyQualifiedErrorId : NullArray

publish-css : Error occurred obtaining uploading CSS file, Status Code is .
At line:1 char:1

• publish-css -server $server -theme 'USS' -CssFile 'theme-USS.css'

•   + CategoryInfo          : NotSpecified: (:) [Write-Error], WriteErrorException
    + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Publish-Css
  

Set-Branding -portalColor does not work

I am unable to configure any portalColor with Set-Branding. It fails to set any value. No error is generated. I've tried the syntax in several different ways with the same result. We're testing against vCD 9.7.0.2.

PS C:\Users\lab_rfish\Downloads> set-branding -server $server -portalName "testvCloud" -portalColor "#0F2D61"
Branding configuration sent successfully.
PS C:\Users\lab_rfish\Downloads> Get-Branding | fl

portalName : testvCloud
portalColor :
selectedTheme : @{themeType=BUILT_IN; name=Default}

Enhancement: Add support for UI Plugin uploads

Comparable to CSS upload, as a user I want to be able to upload (and publish) full UI Plugin .zip files to vCD.

I'll try to start working on it, just want to track it here to make sure it fits and doesn't overlap....

Enhancement: Support for per-tenant branding in vCD 9.7

In vCD 9.7 it is now possible to publish themes on a per-tenant base. Would be a great addition to the module to support this.
For the Get|Set-Branding cmdlets an additional switch --tenant could be added, that calls the /branding/tenant/{org} endpoint to activate a theme or set the logo/color for a given org.