How to create a custom brand package for Reporting Services with SQL Server 2016

UPDATE: Thanks for the feedback in the comments section - we've updated this post to include brand packages with the default color scheme (one with the Microsoft logo, and one without).
- Download the default brand package (without MSFT logo)
- Download the default brand package (with MSFT logo)

Happy Monday everyone!  I know folks have been excited about being able to create custom brand packages for Reporting Services since the announcement at PASS last year.  And for the past few years, basically every customer I spoke to was looking for this type of functionality.  In fact, it was one of the most popular features in the standalone Datazen product.  Well, today we’re pleased to announce that with the latest SQL Server release candidate, custom brand packages are now supported in Reporting Services.

Now that brand packages are supported, it’s time for you to make your own.  As you’ll soon see, this is VERY easy to do.  That’s because the brand package creation experience in Reporting Services has been designed so users don’t need deep css knowledge to create one.  Let me show you just how easy it is.

You’ll need the following items to get started -

- Download SQL Server 2016 RC1 (Only RC1 and newer versions of SQL Server 2016 will have brand package support)
- Download a sample brand package (You can use this right away, but I doubt you’ll want to.  It is ugly as sin, but there’s a reason why.  Just keep reading)
- Download the finished brand package we’ve put together as we walk through this post.

This is what the final product looks like for me.

image

Pretty cool, huh?  Let's get started.

Overview

A brand package for Reporting Services consists of three items and is packaged as a zip file. These items are –

- A colors.json file
- A metadata xml file
- A logo.png file (optional)

You must use these naming conventions for the files included in the brand package, however, you may name the zip file whatever you’d like.  Let’s go through these items one at a time as I create the Xbox brand package.

Metadata file

The metadata.xml file allows you to set the name of brand package that you see in Reporting Services, and has a reference entry for both your colors.json file and logo.png file (if applicable).

To change the name of your brand package, change the entry in the XML file title name. It looks like the following item in our sample file –

name="Multicolored example brand"

which means I’m changing it to this in my new brand package

name="Xbox"

Next, to use a logo in your brand package, make sure to update the metadata.xml file to include a reference to a file called “logo.png” in the Contents section.

Example contents section without logo entry –

<Contents>
<Item key="colors" path="colors.json" />
< /Contents>

That’s what my base brand package looks like right now.  Since I want to use a logo in mine, I’m going to change it to look like this -

<Contents>
<Item key="colors" path="colors.json" />
<Item key="logo" path="logo.png" />
< /Contents>

Now let’s move onto the biggest part of any brand package – the colors.json file.

Colors

Almost all the work you need to do for your brand package will happen in this file.  When the brand package is uploaded, the server extracts the appropriate name/value pairs from the colors.json file and merges them with a master LESS stylesheet, brand.less. This LESS file is then processed and the resulting CSS file is served to the client.  All colors in the stylesheet follow the six-digit hexadecimal representation of a color.

The file for RS has two main categories under which items are grouped –

- Interface, which includes items that are specific to the new Reporting Services portal.
- Theme, which includes items are specific to Mobile Reports you create.  Starting with RC2, if you’re using the latest version of the Mobile Report Publisher, when you connect to report server for the first time with the Publisher, a copy of the theme will persist locally with the Publisher and you can use for it any mobile reports you create and publish.  An Xbox themed mobile report looks like this, for example -

image

Now you’ll see why we gave you the sample brand package we did.  Go ahead and load that your server now.  To do so, you must be an admin in the portal, and you’ll need to follow these steps  -

1. Go to Site Settings from the site menu

image

2. Select the Branding menu

image

3. Upload the sample brand package zip file title "Multicolored example brand" that you (hopefully) downloaded earlier.  Your portal should now look like the following -

image

GAH!  That looks awful, doesn’t it?  Well, it’s supposed to.  The brand package uses unique colors to make it easy to see which option in the colors.json file maps to each element in the web portal.  So let’s look at our file again.  The first section of the interface has the following items:

"primary":"#b31e1e",
"primaryAlt":"#ca0806",
"primaryAlt2":"#621013",
"primaryAlt3":"#e40000",
"primaryAlt4":"#e14e50",
"primaryContrast":"#fff",

You can use a number of sites to translate these hex codes, but I prefer color-hex.com.  So let’s copy the first color into the translator – it looks like the red color I see above in the button background.  I'll try replacing it with a green color “#7cbb00” and re-upload my brand package to see what that looks like.

image

Hey, not bad.  But if I roll my mouse over the button, look what happens

image

I bet that’s the primaryAlt color.  Let’s try changing that to the following “#f65314

image

So each section of the interface (primary, secondary, etc.) corresponds to a different part of the portal screen.  In general terms, that breaks down to the following items under the interface section -

Primary Section – button colors, hover colors
Secondary Section – title bar color, search bar, the left-hand menu (when present), and text color for those items
Neutral Primary – Home background, Reports Area background
Neutral Secondary – Text Box background, Folder Options background, Settings Menu
Neutral Tertiary -  Site Settings backgrounds
Danger/Warning/Success Messages
KPI colors (Good – Green, Bad - Red, Neutral – Orange, None – Black)

Couple suggestions for you -

- You are probably going to do a lot of experimenting the first time you create a brand package to see what works and was doesn't.  To save time, you don't need to remove the existing brand package you've uploaded before you make a change.  Each time you upload a new file, it will simply overwrite the existing one, so you can iterate more quickly.

- While the sample file I provided has every major item with a different color, you might find it easier to manage a much smaller number (three or four), along with white and black.  This made it easier for me to get started and create new ones.

When it comes to the theme for your mobile reports, most of the information you need for that section is visible in the Mobile Report Publisher theme dropdown -

image

The background color is represented on each theme, along with the data points (the twelve colors lined up at the bottom), with the options for good, bad, and neutral normally being green, red and yellow respectively.  The other items called out in the brand package, like accent colors, map colors, panel backgrounds, etc. should be readily understood by anyone who’s used the Mobile Report Publisher (or the Datazen Publisher) before.

Almost done now – just need to add my logo to the brand package.

Logo

If you include a logo with your brand package, it will appear in the reporting portal in place of the Name you set for the portal in the Site Settings menu.  You can't use a title and a logo simultaneously in the portal.

Without logo in brand package –

image

With logo in brand package -

image

The file you include for a logo must use the .png file format. The file dimensions will be automatically adjusted once uploaded to the server, so you don’t have to save it as a certain size for it to work.

Now it’s your turn!

You now have everything you need to get started creating your own brand packages for Reporting Services.  We’re excited to see what you come up with, and we’ll be keeping on eye out on Twitter for screenshots of what you create!  As always, please give us feedback around what you like/don’t like in the product so we’re always meeting your needs.  Have fun!