Branding PowerBI Report Server & SSRS 2017

Recently I was working on rolling out a new PowerBI Report Server, along with migrating our 2014-based SQL Server Reporting Server to a newer 2017-based system. One of the benefits of moving beyond 2014 (with SSRS) is that the appearance of the web portal (company logo & color scheme) can be customized (branded) using the same files that are used for branding PowerBI Report Server (PBIRS). While the customization process is easy to implement, figuring out which web portal elements were controlled by each configuration parameter (json key value) was a bit of a challenge. So here’s a quick run-down of the requirements for creating a branding package, along with some information & examples on how to customize each of the web elements in PBRIS (Sept. 2019 release) & SSRS (2017).

Requirements:

  1. SQL Server 2012 Enterprise Edition (or newer)
  2. Software Assurance or PowerBI Premium Subscription (for PowerBI Report Server)
  3. .NET Framework 4.6
  4. Windows Server 2012 x64 or newer

Installation Considerations:

Beginning with 2016, SSRS is a downloadable installer (instead of being incorporated in the SQL Server media as with earlier versions). The license key for both SSRS & PBRIS can be found either in the SQL Server installation media, on the Microsoft Volume License web portal, or on the Premium settings tab of the Power BI admin portal (depending on how the license was purchased). Both products can also be installed on servers separate from the SQL Server instance that hosts their databases. A new PBRIS installation can use (ie upgrade/convert) an existing SSRS database, but both SSRS & PBRIS cannot share the same database. If PBRIS and SSRS are installed on the same server, one of them must be configured to use ports other than 80 & 443 (http and https).

Branding The Web Portal:

By default, both applications have similar layouts.

Clicking on the Branding menu in Site Settings will bring up the interface for uploading the customized branding package (zip file).

The zip file can contain 3 files:

  • An optional logo file (png format)
  • metadata.xml
  • colors.json

Logo file

The optional logo file will replace the PowerBI logo & text specified in the Site Settings – General – Properties – Name field. The logo file must be in PNG format and the file name shouldn’t contain any special characters (ie. spaces, dash/hyphens, etc.). The logo will be scaled to about 290 x 60 pixels.

Default Logo Example Logo Example

Metadata.xml

The metadata.xml file contains the name and version information of the branding package, along with the names of the logo and color config files.

<?xml version="1.0" encoding="utf-8"?>
<SystemResourcePackage xmlns="http://schemas.microsoft.com/sqlserver/reporting/2016/01/systemresourcepackagemetadata"
  type="UniversalBrand"
  version="1.0.0"
  name="Example brand with logo"
  >
  <Contents>
    <Item key="colors" path="colors.json" />
    <Item key="logo" path="logo.png" />
  </Contents>
</SystemResourcePackage>

Colors.json

The colors.json file contains the hex color values for the various elements of the web interface. The json keys are separated into 2 main sections: Interface and Theme. The Interface keys relate to the web portal, and the Theme keys are for mobile reports. Within the Interface section, the keys are broken down into several categories (Primary, Secondary, neutralPrimary, neutralSecondary, neutralTertiary, Report Messages & KPIs).

Interface – Primary (Buttons & Hover)

Key NameDescription
PrimaryButton background
PrimaryAltButton background (Hover)
PrimaryAlt2Title Bar Hover
PrimaryAlt3Active Tab Background
PrimaryAlt4Breadcrumb Links Text Color
PrimaryAltContrastButton Foreground (Text)

Interface – Secondary (left-side menu, title & search bars)

Key NameDescription
SecondaryTitle Bar
SecondaryAltSearch Bar Background & Left-side Menu Background
SecondaryAlt2Search Bar Button Hover & Inactive Search Bar Button Foreground (Text)
SecondaryAlt3??? unknown
SecondaryContrastTitle and Search Bar Foreground (Text) & Left-side Menu Active Foreground (Text)

Interface – NeutralPrimary

Key NameDescription
neutralPrimaryHome Bar Background & Tile Background
neutralPrimaryAltPage Background & Report Bars Background
neutralPrimaryAlt2Search Bar Dividing Line
neutralPrimaryAlt3List Lines
neutralPrimaryContrastHome Bar Foreground (Text) & List and Tile Foreground (Text) & Active Tile Outline

Interface – NeutralSecondary

Key NameDescription
neutralSecondaryText Box Background & Title Menu Background & Page Loading Background
neutralSecondaryAltDrop-down Menu Dividing Lines & Pop-up Menu Dividing Lines
neutralSecondaryAlt2Text Box Border
neutralSecondaryAlt3??? unknown
neutralSecondaryContrastText Box Foreground (Text Color) & Drop-down Menu Foreground (Text Color) & Pop-up Menu Foreground (Text Color)

Interface – NeutralTertiary

Key NameDescription
neutralTertiaryBreadcrumb Indicator
neutralTertiaryAltLeft-side Menu Foreground (Text) & Apply Button & Cancel Button Hover & Subscription Toolbar Dividing Line
neutralTertiaryAlt2Pop-up Menu Hover & Properties/Settings/Subscription Background
neutralTertiaryAlt3Settings Toolbar Hover & Download/Remove Button Background
neutralTertiaryContrastSettings & Subscription Page Foreground (Text)

Report Messages – The following keys allow for customizing the text and background colors of their respective report message types.

Key NameDescription
dangermessage background
success message background
warning message background
info message background
dangerContrasttext/foreground
successContrast text/foreground
warningContrast text/foreground
infoContrast text/foreground

KPI

Key NameDescription
kpiGoodGood KPI Background
kpiBadBad KPI Background
kpiNeutralNeutral KPI Background
kpiNoneNone KPI Background
kpiGoodContrastGood KPI Foreground (Text)
kpiBadContrastBad KPI Foreground (Text)
kpiNeutralContrastNeutral KPI Foreground
kpiNoneContrastNone KPI Foreground (Text & Graphics)

Theme (Mobile Report Visualizations) – These keys will be used to create a custom for mobile reports. The theme will appear in the server’s list of available themes (upper-right menu) in the Mobile Report Builder.

Leave a Reply

Your email address will not be published. Required fields are marked *