Bob's SQL Reporting Services Blog : Report Design

Add Excel-like "color scale" conditional formatting to your reports

bobmeyers — Sat, 01 Aug 2009 03:09:00 GMT

I’ve been meaning to do this for a long time, and it looks like David Lean beat me to it earlier this year by posting an incredibly thorough four-part discussion of how to do conditional formatting in Reporting Services. I’ve played with his sample code a bit and put together a variation on his theme that meets some additional requirements, which I have found helpful.

The attached sample code is designed to provide the following functionality (the usual disclaimers apply):

· Convenient support for the standard color scales available in Excel 2007

· Support for arbitrary colors, including named colors (“MintCream”)

· Robust handling of null, error, and out-of-range values

· Robust handling of all integral and floating point numeric types

To use them in a report, do the following:

1. Open the Report Properties dialog (right-click on the space around the report body, choose Report Properties)

2. On the Code page, paste in the attached code

3. On the References page, add a reference, click Browse, locate and select System.Drawing.dll, usually in C:\Windows\Microsoft.NET\Framework\v2.0.50727 (this references allows the code to handle named colors)

The simplest and most common usage of these functions is to create a red-yellow-green “heat map” based on the value being displayed in the text box. This is done by setting the text box’s Fill color to an expression similar to the following:

=Code.ColorScaleRYG(Sum(Fields!SalesAmount.Value), 0, 100000)

The arguments 0 and 100000 are the min and max values for the color scale. In this case, the ColorScaleRYG function is used, which assigns red to the low value, green to the high value, and yellow to the value half-way in between.

The min and max values can also be calculated, like this:

=Code.ColorScaleRYG(Sum(Fields!SalesAmount.Value), Min(Fields!SalesAmount.Value, “Dataset1”), Max(Fields!SalesAmount.Value), “Dataset1”))

The argument “Dataset1” defines the scope in which the min or max value is calculated, which must be a parent scope of the current scope.

Note that these colors are not the pure “Red”, “Green”, and “Yellow” colors defined in HTML/.NET/SSRS, but rather the default values used in Excel which are intended to provide a reasonable background for black text. If you don’t like them, it’s easy to specify your own colors instead.

Here’s a full list of the functions provided:

‘ Convenience functions for standard 3-color scales

public function ColorScaleRYG(value, minValue, maxValue) as string

public function ColorScaleGYR(value, minValue, maxValue) as string

public function ColorScaleRYB(value, minValue, maxValue) as string

public function ColorScaleBYR(value, minValue, maxValue) as string

public function ColorScaleRWB(value, minValue, maxValue) as string

public function ColorScaleBWR(value, minValue, maxValue) as string

‘ Convenience functions for standard 2-color scales

public function ColorScaleRY(value, minValue, maxValue) as string

public function ColorScaleYR(value, minValue, maxValue) as string

public function ColorScaleGY(value, minValue, maxValue) as string

public function ColorScaleYG(value, minValue, maxValue) as string

‘ Arbitrary 3-color scale with interpolated midpoint value

public function ColorScale3(value as object, minValue as object, minColor as string, midColor as string, maxValue as object, maxColor as string) as string

‘ Arbitrary 3-color scale with explicit midpoint value

public function ColorScale3(value as object, minValue as object, minColor as string, midValue as object, midColor as string, maxValue as object, maxColor as string) as string

‘ Arbitrary 2-color scale with optional error color (the core function)

public function ColorScale(value as object, minValue as object, minColor as string, maxValue as object, maxColor as string, optional errorColor as string = "Transparent") as string

Enjoy!

How to build a Clickthrough link in Report Builder 2.0

bobmeyers — Thu, 05 Mar 2009 18:45:00 GMT

As I mentioned in a previous post, due to resource constraints in this release, Report Builder 2.0 is not a strict superset of RB 2005/1.0. One of the features missing from RB 2.0 is automatic creation of Clickthrough links. You can still get them, of course, by creating the basics of your report in RB 1.0, then saving and reopening in RB 2.0. It is also possible to build them manually.

Here's how:

1. Determine what the target entity should be. This is the model entity the Clickthrough link should drill to. For example, if the value being displayed is # Sales Orders, you'll want to drill to the Sales Orders entity.

2. Get the target entity ID. (This is the worst part) Unfortunately, this value is not accessible from within RB 2.0. You can see it in the property grid in Model Designer, or you can get someone who has the RS Script Utility to use the attached script to get a list of all the entity IDs in the model. Keep the list around for reference.

3. Determine whether to show a single-instance or multiple-instance report. If the path from the value’s context to the target entity involves at least one “one-to-many” relationship, then the drill action can return multiple instances of the target entity, so you’ll need to show a multiple-instance report. Remember that the path from a report subtotal to the target entity is always one-to-many. Only use a single-instance report if there are no one-to-many relationships along the path. For example, if the value being displayed is # Sales Orders per Sales Territory, the value’s context is Sales Territory, and the path from that context to the target entity is Sales Territory -> Sales Person -> Sales Orders. Both of those relationships are one-to-many, so this Clickthrough action should use a multiple-instance report.

4. Create a "Go to report" action. Open the property dialog for the Text Box, Placeholder, Chart Series, or other report element that has Action properties, and go to the Action property page. Select the “Go to report” option and use the following settings:

Setting	Value
Report Path	=DataSources!MyDataSource.DataSourceReference
Parameters	Value
rs:EntityID	(Target entity ID)
rs:DrillType	“Detail” or “List” for single- or multiple-instance, respectively
rs:Command	“Drillthrough”
DrillthroughSourceQuery	=Datasets!MyDataset.RewrittenCommandText
DrillthroughContext	=CreateDrillthroughContext()

A few tips:

· Clickthrough links will not work correctly in a “details” scope, i.e. a group with no grouping expression. If you want to use them in a scope that is currently a details scope, you’ll have to change it to a non-details scope by adding one or more grouping expressions that uniquely identify each row of data.

· If the value you are displaying is an expression that involves multiple field references, set the target entity as the entity at the end of the longest common path between them.

· Read up on how creating customized Clickthrough reports can help maximize the value of every Clickthrough link you create.

Filtering on totals in Report Builder

bobmeyers — Fri, 28 Sep 2007 17:06:00 GMT

Since releasing Report Builder almost two years ago, we've found that many users run into difficulty at some point with filtering on totals. A classic example of this is, "show me a list of customers with more than $5000 in Accessory sales." "Accessory sales" is a typical slice-and-dice filter, because it just eliminates detail or measure values (sales). It means, "include only the sales for products in the Accessory category." "More than $5000", on the other hand, is not a typical slice-and-dice filter. It means, "include only the customers for which the sales total is more than $5000." In other words, the filter does not eliminate detail or measure values (sales), it eliminates groups instances (customers) based on a detail or measure total.

Filtering on totals can be very handy at times. It is possible in an Excel PivotTable using the "Value Filters" context menu on the row or column labels (try it -- it's fun). It eliminates items from the row or column axis based on the value totals at the outermost level. Filtering on totals is also possible at any level in Report Designer by adding group filters, although this is not always recommended, since it may mean requesting much more data in your query than your report really needs to display.

Filtering on totals is also possible in Report Builder, but (a) there is only limited support for it, (b) it takes some training to ensure you build the right filter, and (c) in the case of RB-over-AS, the performance of the resulting queries will probably be unacceptable. Why is filtering on totals so hard right now? Because in this release RB was primarily designed and optimized for relational/operational reporting. It has a number of innovative and powerful features that are especially valuable in this space (and unavailable in typical OLAP reporting, e.g. Excel). The reverse is also true: some features typical in OLAP reporting have only limited or no support in this release of RB. Filtering on totals is one of those features. There is still a large area of overlap, though (i.e., the extremely common "slice-and-dice" scenario), which is why we offer the option of RB-over-AS. However, users should realize that in this release there will be some challenges/limitations. Specifically, filtering on totals when using RB over AS will rarely result in acceptable performance.

That said, let me go through a couple of examples to help explain what is possible, and what to watch out for.

Example 1: A botched report
The report we want is, "show me a list of customers with more than $5000 in Accessory sales" (same as above). Conceptually this is fairly easy to think about, so many users will assume it must be easy to build. So they'll just follow their nose and build a report that has all the parts they think it needs, then hit "Run" and expect the right answer, like this:

1. Create a new table report using the AdventureWorks sample report model
2. Add Customer->Customer Name to the report
3. Add Customer->Sales Orders->Sales->Sum Line Total to the report
4. Open the Filter dialog
5. Add Customer->Sales Orders->Sales->Product->Product Category to the filter, and set it to "Accessories"
6. Add Sale->Line Total to the filter, and set it to "greater than 5000".
7. Close the filter dialog and run the report

Looks like it should do the job, right? Nope. This report actually returns no data. What went wrong?

Well, there are two problems. The first is that step 5 caused RB to change the primary entity of the report from Customer to Sale, based on the fact that the little checkbox at the bottom of the filter dialog was checked. Changing the primary entity ensures the filter condition will filter all the values added to our report, not just toss out some of the rows. This would be perfect if all we were doing was slice-and-dice filtering. However, we are trying to filter on a total at the same time. This change in the primary entity means that the context of the report filter is now Sale instead of Customer, so the condition added in step 6 means "include only individual sales where Line Total is greater than 5000" (notice that this change is reflected in the text at the top of the filter dialog, and later in the filter description on the surface of the report). As it turns out, there are no individual sales of a product in the Accessory category where the line total is greater than 5000, so we get no results.

The second problem is that in step 6, we selected Line Total instead of Sum Line Total. This actually doesn't make a difference in this case because of the effect of the first problem, but it was nevertheless an issue because we weren't thinking about the fact that we wanted to filter on an aggregate of Line Total in some other context (Customer), not the individual Line Total value attached to a single Sale. We shouldn't have expected to specify both filter conditions in the same place.

Example 2: Getting it right
This report is possible in RB using the approach described below, and has reasonable performance over a relational database (on AdventureWorks on my laptop, this report returns in <2 seconds). Be warned, however, that for a number of reasons, running a report that uses this approach over AS will have performance ranging from disappointing to tragic.

To do the same report as Example 1 correctly, we need to avoid making Sales the primary entity, because that would keep us from being able to specify a filter at the Customer level. We can accomplish this by applying the slice-and-dice part of our filter directly to the displayed field instead of to the overall report. We can then reuse the filtered field to create a report-level filter condition in the context we want (Customer).

1. Create a new table report based on the AdventureWorks sample report model.
2. Add Customer->Name to the report
3. Add Customer->Sales Orders->Sales->Sum Line Total to the report
4. Right-click on the Sum Line Total field in the table, and choose Edit Formula (the Formula dialog opens)
5. Double-click on the field reference in the formula to expand it
6. Click on the link to add a filter on Sales
7. Add Sale->Product->Product Category to the filter, and set it to "Accessories"
8. Click OK to close the Filter dialog.
9. Check the box at the bottom of the Formula dialog to create a custom field using this formula, click OK, and name the field "Accessory Sales".
11. Open the main Filter dialog
12. Add the new "Accessory Sales" field to the filter, and set it to "greater than 5000"
13. Close the Filter dialog and run the report

Result: A quick 1-page report showing customers with more than $5000 in accessory sales.

So, that's great! Does that mean RB supports any kind of filtering on totals? No. You can filter on totals as long as (a) all the totals are in a single context, and (b) that context is the primary entity of the report.

If you wanted to filter on totals in more than one context, such as "show me customers grouped by territory, but only show customers with > $10000 in sales and territories with > $1M in sales acoss all customers", it wouldn't work, because you need a filter on the sales total for each customer and the sales total for each territory. Note that this isn't possible in Excel either, since it only allows filtering on totals for the outermost group on an axis.

If you wanted to filter on a total in a context other than the primary entity, such as "show me customer sales grouped by territory, but only show territories with > $1M in sales", that wouldn't work either, because you need to show values for each customer (which means Customer needs to be the primary entity), but filter on totals for each territory (which would not be the primary entity). This is possible in Excel, but note that if you add an outer group like Territory in Excel, you actually can't do the report I described above, because it won't let you filter on a total for an inner group.

Another, more common example is when you want to filter on a total at the lowest level of detail in the report, but that doesn't happen to be an entity context, such as "show me monthly sales, but only months with > $1M in sales." This would work if Month were an entity, but chances are it isn't in your report model, and if not, you can't make it the primary entity, so you won't be able to filter on a total in that context (in this case, the primary entity would probably be Sales Order, where Order Date->Month is defined). This is possible in Excel, because it doesn't distinguish between entity groups and value groups.

So, what kind of filters can you do in RB that you often can't do in OLAP reporting? Actually, a lot. RB supports an arbitrary number of filter conditions, "OR" groups, aggregate filter groups (e.g. "customers with any orders where Year=2004"), row filters that don't filter the displayed values (e.g. "show customers and their total sales, but only those with > $1000 sales in the last month), and independently filtered fields (e.g. the "Accessory Sales" custom field we created in Example 2), including those with filters on multiple levels (e.g. "total sales with Product->Category = "Accessories" and Sales Order->Order Year = 2004"). All of these features help deliver a rich and powerful relational/operational reporting experience, which is what this release of RB was primarily designed to do.

Rest assured, however, that improving support for filtering on totals is still a high priority for the product team.

Getting grouping right in Report Builder

bobmeyers — Thu, 21 Dec 2006 02:55:00 GMT

One thing Report Builder users need to be aware of when building a report is the difference between an entity group, which displays exactly one instance for each row in the underlying table, and a value group, which displays one instance for each distinct value of a particular field. The type of group they get depends on the field(s) they used to create the group initially. Problems can arise if the user intends to create an entity group with many fields, but instead creates a series of value groups (one for each field). This may make it impossible to get the sorting they want, and can introduce unwanted subtotals levels as well.

For example, a user might drag in the Last Name field as the first step in creating an Employee report. However, if the DiscourageGrouping property for this field in the report model is "false", dragging in this field creates a value group on Last Name. This means that the group cannot be used to display data about individual employees; it can only show totals for all employees with a given last name. So, other fields that are not totals (e.g. First Name) must be added to a new group. If they also do not discourage grouping, a value group will be created for them as well. And so on...

The safest way for the user to get an entity group when they really want one is to drag in the entity itself from the entity list, instead of dragging in a field first. This will create an entity group displaying the DefaultDetailAttributes or IdentifyingAttributes for that entity. This is also a convenient shortcut for adding the fields they almost certainly want to include anyway. As the developer of the report model, you can help users who are unaware of this trick by setting the DiscourageGrouping property in the report model on any field for which users are unlikely to want a value group. They can still get one in their report by using a custom field that simply references it, but the default behavior will give them an entity group instead.

How to get RB to load a report created in VS Report Designer

bobmeyers — Thu, 28 Sep 2006 20:02:00 GMT

Loading an arbitrary Report Designer report in Report Builder is not supported in SQL Server 2005. However, if you are trying to make it work for some reason, here are a few tips:

- Don't use page headers or footers

- Don't use rectangles or lists

- Only use a single data region (table, matrix, or chart)

- Always bind the data region to a report model query

- Make sure the data region groups (including the Details group, which must always be present) *exactly* matches the groups in the query, both in number and sequence (left-to-right for table, rows then columns for matrix, category then series for chart).

If you can get the report loaded, RB will add the appropriate Clickthrough links when you save it back out.

Using RDL expressions in Report Builder

bobmeyers — Sun, 26 Mar 2006 05:57:00 GMT

While not a documented feature, you actually can enter an arbitrary RDL expression into a textbox in a Report Builder report. For example, you could add a textbox that shows the date the report was run by setting the value of the textbox to the following:

=String.Format("Date: {0:MM/dd/yyyy}", DateTime.Today)

Another potential use of this undocumented feature is to display the values selected by the user for each report parameter. This is a helpful workaround for the fact that the auto-generated filter description does not insert the run-time values for each parameter. Here's an example of an RDL expression that would provide this info:

=String.Format("Sales Year: {0}", Parameters!OrderYear.Value)

Note that you will have to guess the name of the report parameter generated by Report Builder. Typically it will be the name of the field used in the prompted filter condition, with any spaces removed.

You cannot enter an RDL expression directly into a detail or subtotal cell in a table or matrix.

Adding parameters (prompts) to a Report Builder report

bobmeyers — Thu, 16 Mar 2006 06:15:00 GMT

You easily can add basic parameters to a Report Builder report using the Filter dialog. For example, to let the user choose which year to view sales data for, add an Order Year filter condition to your report filter, then, instead of specifying a value, click the "Order Year" label on the left side of the condition and choose "Prompt" from the menu. This will create a corresponding report parameter that will supply the value when the report is run. If you also specify a value in the filter dialog, this value will be used as the default parameter value.

The philosophy behind Report Builder data navigation

bobmeyers — Sat, 15 Oct 2005 09:10:00 GMT

The top part of the Explorer pane in Report Builder is probably unlike anything most people have ever used. It starts out as a flat list of entities -- big "things" in your database like Customers, Orders, Products, etc. -- but then rearranges itself once you've added the first field to your report into an auto-collapsing, recursive tree. What's really going on here? Why the new-fangled interface?

Well, the first issue is the peculiar role that the root of the tree plays in building your report. Whichever entity ends up as the root is the "primary" entity of your report. One way to think of this is that the primary entity is the focus of your report, e.g. this report is fundamentally about Customers. Thus, having selected that entity, all other data in your database is represented via its relationship to that entity. Database folks will quickly latch on here and suppose that the navigator is just displaying the tables and relationships in the underlying database. This is not quite true, and it misses the key to the navigator's power.

The key concept is that the nodes immediately below the root are not just the related entities. They represent the specific instances of that entity that are related to a given instance of the root entity. Thus if Customer is the root entity, the Orders node immediately below it does not represent the Orders entity in general; it represents the orders placed by a given customer.

A good analogue would be a paper filing system with a card for each customer, followed by a folder of orders placed by that customer. There is no folder that contains all Orders -- there is just Customers and their Orders.

This explains why adding Customer->Name to your report, and then Customer->Orders->#Orders, results in a report that shows the Name of each Customer with the # of Orders for that customer. No joining or filtering is necessary to constrain #Orders. It is all implicit in the navigation.

The fun really starts, though, when you realize that you can go anywhere using these relationships (including back to the same entity, because the instances will be different), and the path you use fully describes and constrains exactly what data you are referring to. For example, the path Customer->Orders->Employee->Territory->Employees->Orders->OrderDetails->Products represents the products from each order detail of each order taken by the employees in the same territory as the employees that took the orders of this customer. Now, that particular example may not be very useful in a practical sense, but you get the idea.

This also explains why one should be very careful not to just drag in fields from any old node in the tree that looks like it might be what you're looking for. The instances of that entity to which your fields are referring will depend on the path you used to get there.

I'm curious what others think of this approach. Please comment or drop me a note if you have some thoughts you'd like to share on the subject.